MidasTechnologiesInc/MidasEngine
3
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Entirely new file path. Addd Standard Practices, Moved Docs

Browse Source
This commit is contained in:
klein panic
2024-11-01 01:20:14 -04:00
parent b00fc25044
commit c98fffeada
38 changed files with 2201 additions and 455 deletions
Download Patch File Download Diff File Expand all files Collapse all files

220
BranchingPracticesAndStandards.md
View File

@@ -1,220 +0,0 @@
# Branching Practices and Standards for MiadTechnologies
## Overview
In this repository, we use a structured branching strategy to keep our code organized, stable, and easily manageable. Our branching workflow consists of **two main branches**—`main` and `dev`—and **feature branches** created for specific work. This approach helps to streamline the development process, manage updates efficiently, and maintain code quality.
---
## Branch Structure
### 1. `main` Branch
- The `main` branch is the **production-ready** branch. Only stable and tested code should be merged here.
- All code on `main` is reviewed and approved before merging.
- Only authorized personnel (project maintainers) can merge code into `main`.
### 2. `dev` Branch
- The `dev` branch is for **testing** new features, bug fixes, and other updates before they go to `main`.
- Code pushed to `dev` should come through **pull requests** from feature branches and is reviewed before merging.
- All developers push their work to `dev` via feature branches.
### 3. Ad-hoc Branches
- Each new feature, bug fix, or task gets its **own branch off `dev`**.
- Ad-hoc branches should be named according to the work they address, and/or the dir or file name or path (e.g., `DataCollection-NewScraper`, `bugfix-button`, or `docs-readme`).
- Once completed, the feature branch is **merged back into `dev`** through a pull request, then reviewed, and tested.
- Ad-hoc branches can be nested, and should be when doing work on complex code sets. For instance, when doing work in dev, and working on DataCollection, you should branch into DataCollection to do all the work specific to that functionality. Knowing that DataCollection can be a complex branch in of itself, one can further branch into a properly named branch to match the work they address (e.g `git check dev` (Main Development Branch), then `git checkout DataCollection dev` (Known branch off dev), then `git checkout -b {functionality} DataCollection` (new branch to address new changes branched off DataCollection branch))
---
## Workflow for Contributors
### Step 0: If You Do Not Have The Repository - Clone The Repository
Start by cloning the repository to your local machine:
```bash
git clone git@github.com:MiadTechnologiesLCC/MidasTechnologies.git
cd MidasTechnologies
```
> Note if you're new, or not a known contributor this will not work. Contact admins
### Step 1: Set Up Branch Tracking
Make sure you have the latest branches set up locally:
```bash
git fetch origin
```
### Step 2: Check Out `dev` for New Work
Always base new work off the `dev` branch:
```bash
git checkout dev
git pull origin dev # Make sure your dev branch is up to date
```
---
## Working with Ad-Hoc Branches
### Step 1: Create a New Ad-Hoc Branch
For each new task or feature, create a new branch off `dev`. Name your branch descriptively:
```bash
git checkout -b ad-hoc-branch-name dev
```
Example:
```bash
git checkout -b ad-hoc-login dev
```
### Step 2: Make and Commit Changes
As you work on the feature, make commits regularly:
```bash
git add .
git commit -m "Descriptive commit message about the change"
```
### Step 3: Push the Feature Branch to GitHub
When you’re ready to share your work, push the feature branch to GitHub:
```bash
git push -u origin ad-hoc-branch-name
```
---
## Pull Request and Review Process
Once your feature branch is ready, follow these steps:
1. **Create a Pull Request (PR)**: Go to GitHub, find your branch, and create a pull request targeting `dev`.
2. **Request a Review**: Mention the team lead or project maintainer in your PR and ask for a review.
3. **Address Feedback**: Make any requested changes by committing and pushing to your feature branch.
Once your PR is approved, it can be merged into `dev`.
---
## Merging into `main`
Only the team lead or project maintainer will manage merging from `dev` to `main` once testing and reviews are complete. This ensures `main` remains stable.
The Project Maintainer currently, and author of this file is KleinPanic
---
## Git Commands Cheat Sheet
Here’s a quick reference for Git commands relevant to our workflow:
1. **Clone the repository**:
```bash
git clone git@github.com:MiadTechnologiesLCC/MidasTechnologies.git
```
2. **Create a new branch**:
```bash
git checkout -b branch-name dev
```
3. **Add changes**:
```bash
git add .
```
4. **Commit changes**:
```bash
git commit -m "Your message here"
```
5. **Push a branch to GitHub**:
```bash
git push -u origin branch-name
```
6. **Switch branches**:
```bash
git checkout branch-name
```
7. **Fetch updates from GitHub**:
```bash
git fetch origin
```
8. **Pull updates from a branch**:
```bash
git pull origin branch-name
```
9. **Delete a branch (locally)**:
```bash
git branch -d branch-name
```
10. **Delete a branch (remotely)**:
```bash
git push origin --delete branch-name
```
---
## Example Workflow
Here’s an example of a typical workflow for a new feature:
1. Switch to `dev` and ensure it’s up to date:
```bash
git checkout dev
git pull origin dev
```
2. Create a new branch:
```bash
git checkout -b feature-user-profile dev
```
3. Work on the feature, adding and committing changes as you go.
4. Push your branch to GitHub:
```bash
git push -u origin feature-user-profile
```
5. Create a pull request from your branch to `dev` on GitHub, request a review, and wait for approval.
---
## Summary
- `main`: Production-ready, stable code only.
- `dev`: Testing branch; pull requests from feature branches go here.
- **Feature Branches**: Branch off `dev` for specific features or bug fixes.
Following this workflow will ensure our codebase remains organized and stable while allowing for efficient development and collaboration.
> Contact Admins with questions.

2
Business-itselfs/Business-Structure
View File

@@ -1,2 +0,0 @@
# Business Structure and Legalities.

BIN
Business-itselfs/MidasTechnologiesBylaws.pdf
View File

Binary file not shown.

168
Midas-Tech.md
View File

@@ -1,168 +0,0 @@
MIDAS TECHNOLOGIES: Executive Summary
Mission Statement:
The goal of Midas Technologies is to develop algorithmic investment software over-time to build a diversified fund of algorithmic trading strategies that yield an above market return on as frequent a basis as possible.
Business Model:
Build an algorithmic trading Python program, that accurately predicts, and trades shares and options on the price of crude oil. This algorithm will have the goal of getting a given return with a given risk level on a weekly basis. The algorithm will not be used on the market until it has a consistent win rate of 60% and above. We will trade this based on technical indicators
Technology Overview:
The program will be built like this:
Price Prediction Models:
Speculative Indicators: These will be functions that analyze aspects of a news article or other variable to come to a conclusion of how much the price of oil will change in a dollar value. Each indicator needs to print out a predicted price for tomorrow
Economic Indicators: These will be functions that analyze relationships between different economic factors based on data such as GDP, supply, demand, and USD. Each indicator need to print out a predicted price for tomorrow
All prices will be fed into a weighted average formula. The formula will show the predicted price at market close tomorrow. The weights represent the percentage the market thinks that particular indicator is important
PriceTomorrow= PriceNews〖(w〗_1)PriceSupply(w_2 )PriceDemand(w_3 )….
Market Importance Ranking
Based on optimizing of the above problem to minimize margin of error, we will find the weights. These weights will be the backbone of our predictions and we
must test them continuously to find the most accurate price prediction.
Trading Bot
MIDAS TECHNOLOGIES: Roles and Responsibilities
Board of Directors:
Jacob Mardian: 1 Vote
Equity: 33.33%
Role:
Responsibilities: Business paperwork, research, learn more about trading strategies, code trading bot
Griffin Witt: 1 Vote
Equity: 33.33%
Role: Chief of
Responsibilities: Building the intrinsic evaluation system. Finding the relationships between different economic and measurable factors to determine a price
Collin Schaufele: 1 Vote
Equity: 33.33%
Role: Chief of Systems
Responsibilities: Building speculation model that finds an estimated price based on as many possible speciulative indicators as possible and get a license
MIDAS TECHNOLOGIES: Technology Overview
Stage 1: Architecture and Modularity
Core Architectural Design The first step is to refactor the existing code into distinct, modular components. Each component should be as independent as possible, allowing flexibility and scalability for future enhancements.
Modularization Plan:
Data Acquisition Module: Handles all API calls to get historical stock, options, and other relevant market data.
Signal Generation Module: Incorporates all technical indicators (e.g., Moving Average, RSI, Bollinger Bands, etc.) and allows plug-and-play functionality for new strategies.
Optimization Module: Responsible for finding the best combination of strategy weights using an optimization function.
Backtesting Module: Takes historical data, applies the strategy, and returns metrics like profit/loss, Sharpe ratio, and win rate.
Risk Management Module: Includes position sizing, drawdown limits, and hedging capabilities.
Execution Module: Prepares the system for live trading by handling broker API integration and managing trade execution based on generated signals.
Reporting Module: Generates detailed reports (PDF, Excel, or HTML) after backtesting or live trading sessions.
Object-Oriented Design (OOP) Each module will be encapsulated in an object, simplifying code management and enhancing scalability.
Example: Data Acquisition Class
python
Copy code
class DataAcquisition:
def __init__(self, ticker):
self.ticker = ticker
def fetch_price_data(self, start_date, end_date):
"""Fetch historical price data"""
data = yf.download(self.ticker, start=start_date, end=end_date)
return data
def fetch_options_chain(self, expiration_date):
"""Fetch options chain for the given expiration date"""
stock = yf.Ticker(self.ticker)
options_chain = stock.option_chain(expiration_date)
return options_chain
________________________________________
Stage 2: Data Acquisition and Expansion
API Access and Data Sources At hedge-fund complexity, robust and comprehensive data is required. This includes expanding beyond Yahoo Finance:
Yahoo Finance for initial data.
IEX Cloud, Alpha Vantage, or Quandl for high-frequency data.
OptionMetrics, Quandl, or CBOE for comprehensive options data.
News Sentiment Data from NewsAPI or scrapers for financial sentiment from Twitter, Reddit, etc.
Alternative Data Sources Advanced hedge funds use alternative data:
Satellite imagery for crude oil supply insights.
Social sentiment analysis via Twitter and Reddit.
Macro data (inflation, crude oil futures, interest rates).
Data Normalization and Preprocessing Preprocessing is critical for handling missing values and ensuring consistency across different data sources.
Example of Data Preprocessing:
python
Copy code
def preprocess_data(data):
data.fillna(method='ffill', inplace=True)
data['returns'] = data['Close'].pct_change() # Calculate daily returns
return data
________________________________________
Stage 3: Model Development and Complexity Expansion
Advanced Technical Indicators and Strategies To expand on current strategies, multiple timeframes and additional indicators should be added:
Multi-Timeframe Strategies: Daily, weekly, and monthly analysis.
Additional Indicators: MACD, Stochastic Oscillator, ADX, Ichimoku Cloud, Fibonacci Retracement, etc.
Multi-Strategy Optimization: Machine learning can be used to optimize the weight of different strategies.
Machine Learning for Signal Prediction Machine learning should be incorporated to improve signal predictions and strategy selection:
Random Forest or XGBoost: Predict buy/sell signals based on historical data.
Reinforcement Learning: To optimize decision-making based on maximizing profits.
LSTM (Long Short-Term Memory): For time-series forecasting.
Example:
python
Copy code
from sklearn.ensemble import RandomForestClassifier
def train_model(data):
X = data[['MA', 'RSI', 'Bollinger_Bands']] # Features
y = data['buy_sell_signal'] # Target labels
model = RandomForestClassifier(n_estimators=100)
model.fit(X, y)
return model
Factor-Based Models Incorporate factor models frequently used in hedge funds:
Momentum: Track stocks with positive returns over specific periods.
Value: Use P/E ratios, EBITDA, etc., to find undervalued stocks.
Volatility: Leverage implied and historical volatility as factors for decision-making.
________________________________________
Stage 4: Risk Management and Hedging
Advanced Risk Management Incorporating sophisticated risk management is critical:
Position Sizing: Allocate positions based on volatility and confidence levels.
Drawdown Limits: Stop trading when predefined drawdown limits are hit.
Dynamic Stop-Loss and Take-Profit: Adjust based on trailing volatility and other market conditions.
Portfolio Hedging Hedge portfolios using more advanced strategies:
Hedge Long/Short Positions: Use correlated assets (e.g., oil futures) to hedge directional bets.
Options Spreads: Implement complex options strategies (Iron Condors, Bull Call Spreads).
Beta-Hedging: Adjust based on GUSH's beta against broader market indices.
________________________________________
Stage 5: Scalability and Live Trading Infrastructure
Execution Module Real-time trade execution and integration with broker APIs is key for scalability:
Interactive Brokers API for live trade execution.
Alpaca API for commission-free trading automation.
Execution Risk Management: Incorporate slippage and market impact analysis.
Scalable Infrastructure (Cloud-Based) Building the system on a scalable cloud infrastructure (e.g., AWS or Google Cloud) ensures high availability:
Auto-Scaling: Increase computing resources during heavy data processing or trading.
Fault Tolerance: Implement fail-safe mechanisms to handle unexpected system failures.
Advanced Monitoring and Reporting Use real-time dashboards for strategy monitoring and exploratory analysis:
Plotly Dash: Interactive dashboard for strategy performance.
Jupyter Notebooks: For in-depth analysis and rapid prototyping.
Real-Time Alerts Real-time notifications for market conditions or trading signals can be achieved via:
SMS/Email Alerts: Integrate with Twilio or SendGrid.
Webhook Integration: Slack or Telegram for team-based alerts.
________________________________________
Step-by-Step to Hedge-Fund Level Complexity
Refactor Code into Modules: Organize code into modular components (data acquisition, strategy generation, backtesting, etc.).
Upgrade Data Sources: Use multiple sources, including alternative and real-time data for better accuracy.
Introduce Machine Learning: Use Random Forests, LSTMs, and Reinforcement Learning for better prediction of buy/sell signals.
Risk Management: Implement advanced position sizing, drawdown limits, stop-losses, and hedging strategies.
Optimize Execution: Integrate broker APIs for live trading and build a cloud-based infrastructure for scalability.
Add Hedging Capabilities: Implement multi-leg options strategies, beta-hedging, and portfolio risk management.
Monitor and Improve: Create real-time dashboards, backtest rigorously, and set up alert systems.
________________________________________
By following this roadmap, you can evolve your trading program to hedge-fund-level complexity, adding technical sophistication, robust data acquisition, advanced machine learning, and scalable infrastructure.

BIN
Oil Oracle 1 TechOverview.docx
View File

Binary file not shown.

184
docs/BusinessDocumentation/BusinessPlans/ExecutiveSummary.md Normal file
View File

@@ -0,0 +1,184 @@
# MIDAS TECHNOLOGIES: Executive Summary
---
## Table of Contents
1. [Mission Statement](#mission-statement)
2. [Business Model](#business-model)
3. [Technology Overview](#technology-overview)
- [Price Prediction Models](#price-prediction-models)
- [Market Importance Ranking](#market-importance-ranking)
4. [Roles and Responsibilities](#roles-and-responsibilities)
5. [Comprehensive Technology Roadmap](#comprehensive-technology-roadmap)
- [Stage 1: Architecture and Modularity](#stage-1-architecture-and-modularity)
- [Stage 2: Data Acquisition and Expansion](#stage-2-data-acquisition-and-expansion)
- [Stage 3: Model Development and Complexity Expansion](#stage-3-model-development-and-complexity-expansion)
- [Stage 4: Risk Management and Hedging](#stage-4-risk-management-and-hedging)
- [Stage 5: Scalability and Live Trading Infrastructure](#stage-5-scalability-and-live-trading-infrastructure)
6. [Implementation Pathway](#implementation-pathway)
---
## Mission Statement
The mission of **Midas Technologies** is to develop algorithmic investment software designed to continuously build a diversified portfolio of algorithmic trading strategies, delivering above-market returns on a consistent basis.
## Business Model
Our initial product will be an **algorithmic trading system** focused on predicting and trading the price of crude oil. This Python-based algorithm is engineered to meet specific weekly return and risk benchmarks, using a combination of technical indicators and market sentiment.
**Core Requirements**:
- The algorithm will only be utilized for live trading once it consistently achieves a **60% win rate or higher**.
- All trades are informed by a robust analysis of technical indicators and proprietary sentiment metrics.
## Technology Overview
### Price Prediction Models
1. **Speculative Indicators**: Functions that analyze speculative variables, such as news articles, and forecast oil price shifts based on sentiment.
- **Objective**: Each indicator outputs a dollar-based price prediction for the following day.
2. **Economic Indicators**: Functions analyzing macroeconomic relationships, including GDP, supply, demand, and currency fluctuations.
- **Objective**: Each indicator provides a forecasted price for the next trading day based on economic trends.
3. **Weighted Price Prediction Formula**:
- The model will consolidate individual indicator predictions into a weighted average to produce an overall prediction.
- Each indicator’s weight represents its market relevance, with weights optimized to minimize prediction error.
- **Formula**:
```
PriceTomorrow = PriceNews * (w1) + PriceSupply * (w2) + PriceDemand * (w3) + ...
```
- These weights, continuously refined through backtesting, are foundational to the accuracy of our predictions.
### Market Importance Ranking
- Our system will use optimization algorithms to dynamically adjust indicator weights, ensuring accuracy and adapting to market conditions.
---
## Roles and Responsibilities
### Board of Directors
- **Jacob Mardian**
- **Equity**: 33.33%
- **Role**: Business Operations
- **Responsibilities**: Business paperwork, research, trading strategy development, coding the trading bot.
- **Griffin Witt**
- **Equity**: 33.33%
- **Role**: Chief of Economic Analysis
- **Responsibilities**: Building the intrinsic valuation system, identifying relationships among economic indicators to forecast oil prices.
- **Collin Schaufele**
- **Equity**: 33.33%
- **Role**: Chief of Speculative Analysis
- **Responsibilities**: Developing models to estimate oil prices based on speculative indicators, licensing and compliance.
---
## Comprehensive Technology Roadmap
This roadmap outlines a progressive pathway for developing Midas Technologies’ trading platform, expanding from a basic algorithm to a hedge-fund-grade system.
### Stage 1: Architecture and Modularity
1. **Core Design**: Begin by modularizing existing code, creating independent components for scalability and flexibility.
2. **Modularization Plan**:
- **Data Acquisition Module**: API integration for historical and real-time market data.
- **Signal Generation Module**: Incorporates technical indicators (e.g., Moving Average, RSI) for easy strategy updates.
- **Optimization Module**: Finds optimal strategy weights for maximum performance.
- **Backtesting Module**: Analyzes historical data, providing profit/loss, Sharpe ratio, and win rate metrics.
- **Risk Management Module**: Manages position sizing, drawdown limits, and hedging.
- **Execution Module**: Handles broker integration and trade execution.
- **Reporting Module**: Generates detailed reports in PDF, Excel, or HTML formats post-backtesting or trading.
**Example (Python)**:
```python
class DataAcquisition:
def __init__(self, ticker):
self.ticker = ticker
def fetch_price_data(self, start_date, end_date):
"""Fetch historical price data"""
data = yf.download(self.ticker, start=start_date, end=end_date)
return data
```
### Stage 2: Data Acquisition and Expansion
1. **Data Sources**:
- **Yahoo Finance**: Initial data source.
- **IEX Cloud, Alpha Vantage**: High-frequency trading data.
- **Quandl, CBOE**: Options and market sentiment data.
- **Alternative Data**: Social sentiment, satellite data for supply analysis.
2. **Data Preprocessing**: Handle missing values and normalize across data sources.
**Example**:
```python
def preprocess_data(data):
data.fillna(method='ffill', inplace=True)
data['returns'] = data['Close'].pct_change()
return data
```
### Stage 3: Model Development and Complexity Expansion
1. **Advanced Technical Indicators**:
- Integrate multi-timeframe analysis (daily, weekly, monthly).
- Use advanced indicators like MACD, ADX, and Fibonacci Retracement.
2. **Machine Learning for Signal Prediction**:
- **Random Forests** and **Reinforcement Learning** to enhance signal prediction.
**Example (Random Forest)**:
```python
from sklearn.ensemble import RandomForestClassifier
def train_model(data):
X = data[['MA', 'RSI', 'Bollinger_Bands']]
y = data['buy_sell_signal']
model = RandomForestClassifier(n_estimators=100)
model.fit(X, y)
return model
```
### Stage 4: Risk Management and Hedging
1. **Risk Controls**:
- Position sizing based on volatility and drawdown limits.
- Dynamic stop-loss and take-profit settings.
2. **Hedging Strategies**:
- Long/short position hedging using oil futures.
- Options strategies like Iron Condors and Bull Call Spreads.
### Stage 5: Scalability and Live Trading Infrastructure
1. **Execution Module**:
- Real-time broker API integration (Interactive Brokers, Alpaca).
- Manage execution risks like slippage.
2. **Cloud-Based Scalability**:
- Deploy on AWS or Google Cloud for scalability.
- Use auto-scaling for intensive data processing.
3. **Advanced Monitoring**:
- Real-time dashboards using Plotly Dash.
- SMS/email alerts for key trading signals.
---
## Implementation Pathway
| Stage | Timeline | Key Tasks |
|---------------|-------------------------|-------------------------------------------------------------------------------------------------|
| Weeks 1-2 | Develop Scraper & Sentiment Analysis | Build news scraper, implement sentiment analysis models. |
| Weeks 3-4 | Confidence Scoring, Volatility Module | Add confidence scoring, build pre-market volatility prediction models. |
| Weeks 5-6 | Historical Pattern & Technical Analysis | Implement historical pattern matching, integrate technical indicators for analysis confirmation.|
| Weeks 7-8 | Trade Execution and Decision Modules | Develop modules for trade execution, options selection, and risk management. |
| Weeks 9-10 | Monitoring and Real-Time Adjustments | Real-time tracking, set up alert systems, finalize dashboards. |
---
Through this phased approach, Midas Technologies will evolve its algorithmic trading platform to a sophisticated system with robust data processing, advanced modeling, and real-time trading capabilities.
```

117
docs/BusinessDocumentation/BusinessPlans/oil_oracle.md Normal file
View File

@@ -0,0 +1,117 @@
# Oil Oracle 1.0 Technology Overview
## Table of Contents
1. [Overview](#overview)
2. [Step-by-Step Development](#step-by-step-development)
- [Step 1: News Scraper and Sentiment Analysis](#step-1-news-scraper-and-sentiment-analysis)
- [Step 2: Confidence Scoring Module](#step-2-confidence-scoring-module)
- [Step 3: Pre-Market Volatility Assessment Module](#step-3-pre-market-volatility-assessment-module)
- [Step 4: Historical Pattern Matching](#step-4-historical-pattern-matching)
- [Step 5: Technical Confirmation through Chart Analysis](#step-5-technical-confirmation-through-chart-analysis)
- [Step 6: Trade Execution Decision Module](#step-6-trade-execution-decision-module)
- [Step 7: Trade Monitoring and Exit Strategy](#step-7-trade-monitoring-and-exit-strategy)
3. [Implementation Timeline](#implementation-timeline)
---
## Overview
The **Oil Oracle 1.0** system is designed to analyze market sentiment, volatility, and technical patterns in real-time to make informed trading decisions. The following step-by-step guide outlines each module of the system, detailing how these components will work together to identify optimal trading opportunities.
---
## Step-by-Step Development
### Step 1: News Scraper and Sentiment Analysis
**Objective**: Scrape and analyze relevant oil news to determine market sentiment at 9:29 a.m. EST daily.
- **Source Selection**: Choose reliable oil news sources (e.g., Bloomberg, Reuters, OilPrice.com).
- **Scraping**:
- Schedule a web scraper to pull relevant articles daily.
- Include robust error handling, using proxies and custom user agents to prevent blocking.
- **Sentiment Analysis**:
- **Text Preprocessing**: Clean and standardize text data by removing HTML tags, punctuation, and irrelevant symbols.
- **NLP Model**: Use a model like BERT to determine sentiment.
- Assign -1 for positive and +1 for negative sentiment based on expected price movements.
- **Confidence Score**: Output a decimal confidence score to reflect sentiment strength (e.g., -0.8 for strong positive, +0.4 for moderate negative).
- **Backtesting**: Validate the model by testing historical oil-related news and price trends.
### Step 2: Confidence Scoring Module
**Objective**: Assign confidence scores to sentiment analysis predictions.
- **Algorithm**:
- Use ensemble learning, averaging predictions across multiple NLP models.
- Factor in the reliability of news sources and historical impact on oil prices.
- **Quality Control**:
- Filter out low-confidence predictions below a threshold (e.g., 80%) to reduce false signals.
### Step 3: Pre-Market Volatility Assessment Module
**Objective**: Assess potential price movement based on historical patterns and pre-market data.
- **Volatility Analysis**:
- Use volatility indicators like Average True Range (ATR) and options data for implied volatility.
- Backtest historical price reactions to similar news events.
- **Predictive Model**:
- Employ machine learning models (e.g., LSTM, XGBoost) to estimate daily volatility using news strength, previous day’s price action, and economic indicators.
- **Output**: Predict intraday price movement in percentage terms to inform profit targets and stop-loss levels.
### Step 4: Historical Pattern Matching
**Objective**: Validate analysis by comparing current sentiment and volatility to historical data.
- **Pattern Matching**:
- Build a repository of similar historical news events and their impact on oil prices.
- Use clustering algorithms to match patterns and assign a correlation score.
- **Thresholds**: Set a minimum correlation requirement to validate trading signals.
### Step 5: Technical Confirmation through Chart Analysis
**Objective**: Align technical analysis with sentiment and volatility insights.
- **Technical Analysis**:
- Incorporate indicators like Moving Averages, RSI, and Bollinger Bands, and analyze support/resistance levels.
- Set confirmation rules (e.g., positive sentiment aligns with a support bounce).
- **Confirmation Logic**:
- Only proceed with trades if technical indicators align with sentiment (e.g., RSI reversal confirming bullish sentiment).
### Step 6: Trade Execution Decision Module
**Objective**: Use combined insights to make trade decisions and select options contracts.
- **Price Projection**: Combine sentiment, volatility, historical patterns, and technical confirmation.
- **Options Selection**:
- Assess risk and profitability using criteria like delta, theta, strike price, and expiration.
- **Risk Management**:
- Set dynamic stop-loss and take-profit levels based on volatility predictions.
### Step 7: Trade Monitoring and Exit Strategy
**Objective**: Monitor ongoing trades and exit based on real-time market conditions.
- **Monitoring**:
- Track real-time sentiment, price movements, and technical indicators.
- Set alerts for mid-day sentiment changes or volatility spikes.
- **Exit Criteria**:
- Profit Target: Sell at a pre-defined profit percentage.
- Stop Loss: Exit if a maximum loss threshold is met.
- Trend Reversal: Adjust or exit positions if technical indicators show reversals.
---
## Implementation Timeline
| Week | Task |
|------|------|
| Weeks 1-2 | Develop news scraper and sentiment analysis system |
| Weeks 3-4 | Implement confidence scoring and pre-market volatility module |
| Weeks 5-6 | Develop historical pattern matching and technical confirmation modules |
| Weeks 7-8 | Build decision-making and trade execution modules |
| Weeks 9-10 | Integrate monitoring, alerts, and real-time adjustments |
---
This approach will lead to a robust, modular trading system combining real-time data processing, machine learning, and strategic decision-making capabilities.

186
docs/MidasTechNologiesLLCBylaws.md Normal file
View File

@@ -0,0 +1,186 @@
The bylaws document for **Midas Technologies Inc.** has been converted into a Markdown file and enhanced for clarity and readability. Here’s the enhanced and fully structured Markdown file:
---
# Bylaws of Midas Technologies Inc.
**Virginia S Corporation**
## Table of Contents
1. [Corporate Offices](#corporate-offices)
2. [Shareholders](#shareholders)
3. [Board of Directors](#board-of-directors)
4. [Officers](#officers)
5. [Shares of Stock](#shares-of-stock)
6. [Distributions and Dividends](#distributions-and-dividends)
7. [Fiscal Year](#fiscal-year)
8. [Amendments](#amendments)
9. [Indemnification](#indemnification)
10. [Miscellaneous Provisions](#miscellaneous-provisions)
11. [Adoption of Bylaws](#adoption-of-bylaws)
---
## Corporate Offices
### Principal Office
The corporation’s principal office is located at:
**1407 Jennifer Dr, Blacksburg, Virginia**
### Registered Office
The registered office of the corporation is maintained at the same address. Changes to the location may be made at the discretion of the Board of Directors.
---
## Shareholders
### Annual Meeting
- Held on **October 30th at 9:00 pm** at the corporation’s principal office or another location as determined by the Board.
- Purpose: **Election of directors** and transaction of other business.
### Special Meetings
- Can be called by the **President, Board of Directors, or shareholders holding at least 30% of shares**.
- May be held virtually if necessary.
### Notice of Meetings
Written notice, specifying location, date, and time, will be sent to each shareholder at least **seven days** before the meeting date.
### Quorum and Voting
- A **quorum** requires **50% plus one** of the voting shares.
- Decisions require a **majority vote** of the shareholders present, unless otherwise stated by law or these bylaws.
### Proxies
Shareholders may vote by **proxy**, which must be in writing and signed by the shareholder or their authorized representative.
---
## Board of Directors
### General Powers
The Board of Directors is responsible for managing the **business and affairs** of the corporation.
### Structure and Tenure
- **Three directors** on the Board, elected at the annual shareholders’ meeting.
- Directors serve until the next annual meeting or until their successors are elected.
### Meetings
- **Regular Meetings**: No notice is required; times and places are determined by the Board.
- **Special Meetings**: May be called by the President or directors, with at least **seven days’ notice**.
### Quorum and Decision-Making
A **majority of directors** is required for a quorum, and a majority vote is needed for decisions unless otherwise specified.
### Compensation
Directors may receive **reasonable compensation** for their services, aligned with market rates.
### Shareholder Agreement
**Substantial changes**, such as a sale of the company, require **unanimous consent** from both the Board and shareholders to protect founders’ interests.
---
## Officers
### Corporate Officers and Responsibilities
1. **Chief Data Officer (CDO)**
- Oversees data management, analysis, and research for trading algorithms.
- **Duties**:
- Lead data collection and interpretation for strategic insights.
- Collaborate with the CTO to integrate data streams.
- Conduct market trend research and model evaluations.
- Ensure data security, compliance, and accuracy.
2. **Chief Technical Officer (CTO)**
- Manages technological infrastructure and software development for trading programs.
- **Duties**:
- Lead software platform development and maintenance.
- Manage technical infrastructure, including API integrations.
- Collaborate on data-driven strategy with the CDO.
- Implement cybersecurity measures.
3. **Chief Operations Officer (COO)**
- Oversees operations, compliance, and investment strategy.
- **Duties**:
- Manage administrative, financial, and regulatory aspects.
- Ensure regulatory compliance.
- Oversee company-wide policies and procedures.
- Coordinate with CTO and CDO to align technical and data initiatives.
### Collaboration
The CDO, CTO, and COO collaborate on major initiatives, requiring **consensus** on decisions affecting the company’s direction or strategic assets.
### Election and Term
Officers are elected by the Board at the annual meeting and serve a **one-year term** or until successors are elected.
### Removal and Vacancies
Officers may be removed by a majority vote if deemed necessary, and any vacancies are filled by the Board.
---
## Shares of Stock
### Issuance of Shares
The Board has the authority to **issue shares** and set terms for stock issuance.
### Stock Certificates
Shares can be represented by **certificates or electronically**. Certificates display the corporation’s name, shareholder’s name, and number of shares.
### Transfer of Shares
Shareholders can transfer shares on the corporation’s books with proper authorization.
### Restrictions on Transfer
To maintain S Corporation status, any share transfer must first be offered to the corporation or other shareholders before outside parties.
---
## Distributions and Dividends
### Distributions
The Board of Directors determines shareholder distributions, following state and federal regulations.
### Dividends
Dividends may be declared at the Board’s discretion, adhering to S Corporation rules and the corporation’s financial status.
---
## Fiscal Year
The corporation’s fiscal year aligns with the **calendar year**, subject to change by the Board of Directors.
---
## Amendments
The bylaws can be **amended or repealed** by either the Board of Directors or shareholders during regular or special meetings. Amendments require a **majority vote**.
---
## Indemnification
Directors, officers, and agents of the corporation are indemnified against liabilities incurred in performing their duties, as permitted by **Virginia law**.
---
## Miscellaneous Provisions
1. **Corporate Records**: Records of corporate activities are maintained at the principal office.
2. **Corporate Seal**: A corporate seal may be adopted, though not required for document validity.
3. **Right of Inspection**: Shareholders have the right to inspect records with prior written request.
4. **Intellectual Property**: Proprietary algorithms, data models, and software developed for the corporation belong to the corporation.
5. **Conflict Resolution**: The corporation seeks mediation or arbitration before litigation in case of internal disputes.
---
## Adoption of Bylaws
These bylaws were adopted by the Board of Directors of **Midas Technologies Inc.** on **November 11, 2024**.
---
**Signatures:**
Chief Operations Officer
Chief Technical Officer
Chief Data Officer
---
This enhanced version provides clear formatting and structure for readability and accessibility. Let me know if you need further adjustments or additional files processed!

245
docs/PoliciesAndStandards/CodingStandards.md Normal file
View File

@@ -0,0 +1,245 @@
# MiadTechnologies Coding Standards
This document details the coding standards and practices for maintaining consistency, readability, and quality in the codebase for all contributors. These guidelines apply across programming languages and environments used within the project, focusing primarily on Python and any related languages used for interoperability.
---
## Table of Contents
1. [Python Coding Standards](#python-coding-standards)
2. [Virtual Environments and Dependency Management](#virtual-environments-and-dependency-management)
3. [Interfacing with Other Languages](#interfacing-with-other-languages)
4. [Documentation Standards for Code](#documentation-standards-for-code)
---
## Python Coding Standards
Our primary codebase is in Python, and we adhere strictly to **PEP8** guidelines with additional standards to ensure clarity and consistency.
### PEP8 Guidelines and Best Practices
- **Naming Conventions**:
- **Variables and functions**: Use `snake_case` for readability.
- **Classes**: Use `PascalCase`.
- **Constants**: Use `ALL_CAPS`.
- **Line Length**: Limit lines to **79 characters** for readability.
- **Indentation**: Use **4 spaces per indentation level**.
- **Docstrings**: Follow [PEP 257](https://www.python.org/dev/peps/pep-0257/) conventions.
- Use docstrings for all public modules, classes, and functions.
- Structure them using the [Google docstring style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
- **Comments**: Add comments as needed to clarify code functionality, especially around complex logic. Avoid redundant comments.
### Jupyter Notebook Usage
While Jupyter notebooks are valuable for experimentation, they should not be submitted directly to the repository unless absolutely necessary. Instead:
1. **Convert the notebook to a `.py` file** before adding it to the repo.
- In Jupyter, navigate to `File > Download as > Python (.py)` to obtain a `.py` version of the notebook.
2. **Document the Python file** properly and integrate it with the existing codebase standards.
### Python Best Practices Quick Reference
Follow these essential Python best practices to ensure code consistency across the project:
- **Use List Comprehensions**: Prefer list comprehensions over traditional loops for concise code.
```python
# Recommended
squares = [x**2 for x in range(10)]
```
* Avoid Global Variables: Limit the use of global variables, especially in modules intended for import.
* String Formatting: Use f-strings (formatted string literals) for improved readability in Python 3.6 and above.
```python
name = "Alice"
print(f"Hello, {name}!")
```
* Error Handling: Use specific exceptions where possible. Avoid catching all exceptions with except Exception.
* PEP8 Line Length: Adhere to a line length of 79 characters, and use 4 spaces per indentation level.
* Docstrings: Use Google-style docstrings to document functions, modules, and classes.
>Refer to PEP8 and Google Python Style Guide for detailed information on Python coding standards.
### Recommended Tools
- **Flake8**: Enforces PEP8 standards.
- **Black**: Automatic formatter for consistent styling.
- **isort**: Automatically organizes imports.
These tools can be added to your development environment for smoother compliance with coding standards.
---
## Virtual Environments and Dependency Management
Using a virtual environment isolates dependencies and keeps the project environment consistent.
### Setting Up a Virtual Environment
1. **Create the virtual environment** in the project root:
```bash
python -m venv venv
```
2. **Activate the environment**:
- On macOS/Linux:
```bash
source venv/bin/activate
```
- On Windows:
```bash
.\venv\Scripts\activate
```
3. **Install dependencies** from `requirements.txt`:
```bash
pip install -r requirements.txt
```
### Managing Dependencies with `requirements.txt`
All project dependencies should be added to `requirements.txt`. When new packages are added:
1. Install the package using `pip`.
2. Update `requirements.txt` by freezing the environment:
```bash
pip freeze > requirements.txt
```
### Important Note
- **Do not push the `venv` directory** to the repository. The virtual environment is a local development tool and should remain excluded in `.gitignore`.
---
Here's a more detailed and enhanced section for the **Interfacing with Other Languages** area, incorporating standards and industry best practices across each language, file format, and tool.
---
## Interfacing with Other Languages
Python’s flexibility allows it to integrate with other languages, databases, and formats, which is particularly beneficial for high-performance tasks, front-end functionality, data exchange, and efficient file handling. Below are the industry standards, best practices, and interfacing guidelines for each language or format commonly used with Python.
### 1. C (CPython and C Extensions)
C is often used in Python projects for performance-critical modules and low-level operations.
- **Coding Standards**: Follow the [GNU Coding Standards](https://www.gnu.org/prep/standards/).
- Use `snake_case` for variable and function names.
- Avoid global variables, and encapsulate functions within modules.
- **Documentation**: Use comments within `.c` and `.h` files, explaining complex logic and including a description of each function.
- Follow structured comment headers for each function, detailing parameters, expected return values, and purpose.
- **Interfacing with Python**:
- Use `ctypes` or `cffi` for interfacing.
- **Example**: Use `ctypes` to call a C function from Python:
```c
// function.c
int add(int a, int b) {
return a + b;
}
```
- Use `setup.py` with `distutils` to compile C extensions for easy distribution.
### 2. TypeScript and JavaScript
TypeScript, a typed superset of JavaScript, should be used for type safety and maintainability on the front-end.
- **Coding Standards**: Follow the [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
- Use `camelCase` for variables and function names.
- Prefer `const` and `let` over `var`.
- **Documentation**: Comment functions and classes with JSDoc.
- Use TypeScript's type annotations to document data types explicitly.
- **Interfacing**:
- Use `pyodide` or REST APIs to communicate between Python and JavaScript.
- When possible, separate concerns by keeping Python back-end tasks independent of TypeScript front-end logic, communicating only through defined APIs.
### 3. Go
Go is efficient for concurrent tasks, and is often used alongside Python for backend services or tasks needing efficient multithreading.
- **Coding Standards**: Follow [Effective Go](https://golang.org/doc/effective_go.html).
- Use `PascalCase` for exported (public) identifiers and `camelCase` for private ones.
- Format code with `go fmt` to maintain consistency.
- **Documentation**:
- Add a comment above each function explaining its functionality, parameters, and expected return values.
- **Interfacing**:
- Use `cgo` to call C functions from Go if needed, or implement a REST API to interact with Python.
### 4. Rust
Rust is a high-performance language with strong memory safety guarantees, making it suitable for secure, efficient modules in Python.
- **Standards**: Follow the [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/).
- Use `snake_case` for function and variable names, and `CamelCase` for structs and enums.
- Use `clippy` for linting and `rustfmt` for consistent formatting.
- **Documentation**:
- Use triple slashes (`///`) for documentation comments on functions and modules.
- Each public function should explain parameters, return values, and potential errors.
- **Interfacing**:
- Use `pyo3` for embedding Rust code in Python or `maturin` for building and publishing Python packages containing Rust code.
### 5. JSON
JSON is a lightweight data-interchange format and is frequently used in Python projects for configuration and data exchange.
- **Format**: Follow strict schema validation to ensure data consistency.
- Use lowercase keys in `snake_case`.
- Avoid deeply nested structures; keep depth manageable for readability.
- **Best Practices**:
- Validate JSON against a schema using tools like `jsonschema`.
- Use consistent encoding (UTF-8) and 4-space indentation.
### 6. CSV
CSV files are widely used for tabular data storage and exchange.
- **Format**: Always include headers as the first row, and use commas (`,`) as delimiters.
- **Best Practices**:
- Handle missing data by filling with placeholders or removing empty rows if appropriate.
- Use Python’s `csv` library, and include headers in the file for clarity.
- Ensure data types are consistent across columns (e.g., dates, numbers).
### 7. SQL (Database Standards)
SQL databases are essential for structured data storage and querying.
- **Naming Conventions**:
- Use `snake_case` for table and column names.
- Avoid special characters and reserved keywords in table or column names.
- **Standards**: Follow [SQL Style Guide](https://www.sqlstyle.guide/).
- Use constraints and foreign keys for data integrity.
- Normalize data as needed, but consider denormalization for performance in specific cases.
- **Indexing**: Index frequently queried columns for faster retrieval.
- **Transactions**: Wrap changes in transactions to ensure data consistency, and roll back on errors.
### 8. Docker
Docker standardizes development environments and deployment by containerizing applications.
- **Dockerfile Standards**:
- Use multi-stage builds to optimize image size.
- Only include production dependencies in the final image.
- Use environment variables for configuration rather than hardcoding values.
- **Directory Structure**:
- Place Docker-related files in a `docker/` directory.
- Use `docker-compose.yml` for multi-container setups.
- **Best Practices**:
- Use `.dockerignore` to exclude unnecessary files, like logs and local configuration.
- Always use stable tags for dependencies instead of `latest`.
### 9. Binary Building for Python
For performance-critical Python code, consider building binaries.
- **Tools**:
- Use `Cython` to compile Python code into C, then build as a binary.
- Alternatively, use `PyInstaller` to package Python scripts as standalone executables.
- **Best Practices**:
- Ensure binaries are compatible with target deployment environments.
- Document the binary build process for reproducibility.
### 10. Makefiles
**Makefiles** provide a standardized way to compile and manage dependencies, particularly for non-Python code.
- **Structure**:
- Place the `Makefile` in the root of the project.
- Organize commands for easy readability, grouping related commands together.
- **Common Targets**:
- `build`: Compile code, if needed.
- `clean`: Remove compiled files and dependencies.
- `test`: Run test suites.
- `install`: Set up dependencies or environment configurations.
---
## Documentation Standards for Code
Clear and concise documentation is essential for long-term project maintainability.
### Docstring and In-Code Documentation
- **Functions and Classes**: Use [Google Style Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
- Each docstring should describe what the function does, input parameters, return values, and any exceptions raised.
- **In-Line Comments**: Only add comments where needed to explain non-obvious parts of the code.
- **Module-Level Documentation**: Provide a brief overview at the top of each file explaining its purpose and any key dependencies.
### README.md for Each Module
Each root module should contain a `README.md` file covering:
- **Overview**: High-level description of the module’s functionality.
- **Setup**: Dependencies, pip installs, libraries, and setup instructions.
- **Usage**: Sample commands or code for running the module.
- **API Documentation**: If applicable, list available functions, classes, or endpoints.

125
docs/PoliciesAndStandards/CommunicationStandards.md Normal file
View File

@@ -0,0 +1,125 @@
# Collaboration and Communication
## Table of Contents
1. [Purpose](#purpose)
2. [Communication Channels](#communication-channels)
- [GitHub Issues](#github-issues)
- [Pull Requests (PRs)](#pull-requests-prs)
- [Team Meetings](#team-meetings)
- [Direct Messaging (DMs)](#direct-messaging-dms)
3. [Collaborative Coding Practices](#collaborative-coding-practices)
4. [Documentation Requirements](#documentation-requirements)
5. [Conflict Resolution](#conflict-resolution)
6. [File-Path Standards and Naming Conventions](#file-path-standards-and-naming-conventions)
7. [Labor Distribution and Task Assignment](#labor-distribution-and-task-assignment)
---
## Purpose
This document outlines collaboration and communication guidelines for our team, ensuring alignment, productivity, and clarity as we work on projects. Effective use of these practices will help streamline progress and minimize misunderstandings.
---
## Communication Channels
1. **GitHub Issues**
- **Purpose**: Use GitHub Issues for bug tracking, feature requests, and all development-related discussions.
- **Best Practices**:
- Assign labels (e.g., `bug`, `enhancement`, `documentation`) to categorize each issue.
- Assign issues to relevant team members and add milestones where applicable.
- Keep all discussions regarding the issue within its thread to retain context.
2. **Pull Requests (PRs)**
- **Purpose**: PRs facilitate code reviews and collaborative discussions on changes before merging.
- **Best Practices**:
- Link each PR to the corresponding issue.
- Use the provided **PR Template** to give detailed context and link to relevant resources.
- Use **GitHub Reviews** to comment on specific code sections or suggest improvements.
- Ensure all discussions are resolved before finalizing the merge.
3. **Team Meetings**
- **Purpose**: Conduct periodic meetings to discuss project updates, roadblocks, and future priorities.
- **Frequency**: Weekly, or as needed based on project milestones.
- **Agenda**: Each member should come prepared with updates, questions, and any roadblocks requiring group input.
4. **Direct Messaging (DMs)**
- **Purpose**: Use text messaging for quick, urgent issues.
- **Future Option**: A company Discord or similar platform may be established for more structured and real-time communication, enabling different channels for topics like bugs, general updates, and discussions.
- **Note**: Text messaging or direct messages are meant for time-sensitive issues and should not replace documented discussions crucial to the project.
---
## Collaborative Coding Practices
1. **Code Reviews**
- Open a PR for any code that is ready for review.
- Assign relevant team members as reviewers, tagging specific people for feedback on particular areas.
- Provide constructive feedback with explanations to clarify your suggestions.
2. **Issue Assignment and Management**
- Assign each issue to one or more contributors.
- Regularly update the issue status by changing labels or closing it when complete.
- For large tasks, break down the issue into smaller, manageable sub-tasks and assign them accordingly.
3. **Pair Programming and Knowledge Sharing**
- For complex features or debugging, consider pair programming with another team member.
- Document insights gained from these sessions, especially any solutions for particularly challenging issues or bugs.
### Task Ownership and Assignment Changes
To ensure transparency and accountability within the team, follow these guidelines for task ownership:
- **Task Ownership**: Each issue should have a clearly assigned owner responsible for its completion. If you are assigned a task, regularly update the issue with your progress.
- **Reassignment Protocol**: If you are unable to complete a task or require assistance, reassign it to a relevant team member or reach out to the project maintainer.
- **Ownership Transfer**: When transferring ownership, add a comment to the GitHub issue explaining the reason and notify the new owner directly. Ensure the transition is smooth to maintain workflow continuity.
Maintaining clear task ownership helps keep the project organized and reduces overlap or duplicated effort.
---
## Documentation Requirements
- Each project module should contain a `README.md` with setup instructions, usage examples, and module-specific details.
- Follow **Documentation Standards.md** for consistency in all documentation.
- Comment complex or non-obvious code to enhance clarity for all team members.
---
## Conflict Resolution
1. **Technical Disagreements**
- Address technical disagreements within the PR or issue thread.
- If unresolved, escalate to a team meeting where a consensus can be reached.
2. **Responsibilities and Expectations**
- Document each team member’s responsibilities and ensure clarity on roles to prevent misunderstandings.
- If conflicts arise regarding tasks, discuss openly in team meetings or escalate to the project maintainer.
---
## File-Path Standards and Naming Conventions
- Adhere to the **File-Path Standards** for directory structures and file naming conventions.
- Following consistent naming conventions helps streamline navigation and allows the team to understand the project structure quickly.
---
## Labor Distribution and Task Assignment
**GitHub Project Boards and Issues** provide a structured method for distributing tasks across the team:
1. **Create Project Boards**
- **Purpose**: Use GitHub Project Boards to organize issues into columns such as `To Do`, `In Progress`, and `Completed`.
- **Best Practices**:
- Ensure each task or issue is visible on the board.
- Regularly update the status of each issue by moving it to the relevant column as work progresses.
2. **Assigning Issues and Tasks**
- For each feature or task, create an issue in GitHub and assign it to the responsible contributor.
- Use tags like `priority`, `in-progress`, and `review-needed` for clarity on the status and urgency of each task.
3. **Milestones**
- Define **milestones** for specific project phases (e.g., `v1.0 Launch`, `Feature Complete`).
- Assign issues to milestones to maintain a timeline and prioritize critical tasks.
- Each milestone should have an estimated completion date and a list of issues to be resolved before the milestone is considered complete.

170
docs/PoliciesAndStandards/DocumentationStandards.md Normal file
View File

@@ -0,0 +1,170 @@
# Documentation Standards
## Table of Contents
1. [Overview](#overview)
2. [Global Documentation Structure](#global-documentation-structure)
3. [Module-Specific Documentation](#module-specific-documentation)
4. [Documentation Format and Naming Conventions](#documentation-format-and-naming-conventions)
5. [File Requirements for Python Modules](#file-requirements-for-python-modules)
6. [Code Documentation Practices](#code-documentation-practices)
---
## Overview
This document defines the standards for documenting business, technical, and code-related affairs within the repository. It ensures that all contributors understand how and where to document essential aspects of the project, including code structure, usage, and business elements.
**Footnote:** While the overarching program is under active development, documentation must be updated with each pull request or addition to maintain consistency and clarity as the project grows.
---
## Global Documentation Structure
All global documentation is stored under the `/docs` directory and is organized into the following key areas:
1. **Business Documentation**:
- Contains non-technical documents that relate to company operations, legal compliance, project plans, business strategies, and any necessary licenses or contracts.
- **Directory**: `/docs/business`
- **Examples**: Business plans, contracts, project outlines, licenses.
2. **Policies and Standards**:
- Contains files outlining the coding, review, and workflow standards.
- **Directory**: `/docs/policies-and-standards`
- **Examples**: `GitAndGitHubStandards.md`, `BranchNamingConventions.md`, `CodingStandards.md`.
3. **Man Pages**:
- Stores all program-related documentation for the entire codebase.
- **Directory**: `/docs/manpages`
- **Examples**: README files detailing how to use, deploy, and modify the overarching program.
Each sub-directory should contain a README.md that outlines its purpose and lists the contents within.
---
## Module-Specific Documentation
All **root modules** within the overarching program should contain their own `README.md` files. These files should act as module-specific documentation, providing:
1. **Overview**:
- A brief explanation of the module’s functionality and its purpose in the larger program.
2. **Installation and Setup**:
- Instructions for setting up the module, including any dependencies not covered in the global requirements file.
3. **Usage**:
- How to run and utilize the module, including examples of inputs, expected outputs, and special configurations.
4. **Development Guidelines**:
- If applicable, detail any specific guidelines for contributing to the module, such as coding standards, testing guidelines, or branch usage specific to the module.
5. **Version and Dependencies**:
- Each module should have its own `requirements.txt` file that lists the dependencies required for it to function. This file will be merged into the main program’s `requirements.txt` by the admins.
---
## Documentation Format and Naming Conventions
### Format
- **Markdown** (`.md`) or **Plain Text** (`.txt`) formats are acceptable for all documentation.
- The language should be formal yet accessible, avoiding technical jargon where possible to ensure clarity for all team members and future collaborators.
### Naming Conventions
- **Documentation files** must be in **Capitalized Case** with no spaces, using only letters and alphanumeric characters.
- **Examples**: `DocumentationStandards.md`, `GitAndGitHubStandards.md`
- **Code files** should follow **lowercase with underscores** for Python, with no spaces or special characters.
- **Examples**: `data_processing.py`, `config_handler.py`
---
## File Requirements for Python Modules
### Main `requirements.txt`
A main `requirements.txt` file will exist in the root directory of the program. This file aggregates all module-specific dependencies to provide a comprehensive list of requirements for the entire program.
### Module-Specific `requirements.txt`
- Each root module in Python must include its own `requirements.txt` file, specifying only the dependencies necessary for that module.
- Upon review, the admins will incorporate module-specific requirements into the main `requirements.txt`.
---
## Code Documentation Practices
### General Code Documentation Guidelines
Documentation within code should provide clarity and context without redundancy. Focus on documenting the **why** and **how** rather than the **what**.
- **Functions and Methods**:
- Include docstrings for all public functions and methods. These should follow the [Google Docstring Style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for consistency and readability.
- **Classes**:
- Each class should have a docstring explaining its purpose and any unique attributes or methods. This docstring should summarize the role of the class in the module.
### Specific Documentation Guidelines
1. **Function-Level Documentation**:
- Include a brief docstring at the beginning of each function that explains:
- **Parameters**: List and explain the function’s input parameters.
- **Returns**: Describe the data returned by the function.
- **Raises**: Detail any exceptions that the function might raise.
- **Example**:
```python
def process_data(data: list) -> dict:
"""
Processes input data and returns a dictionary of results.
Args:
data (list): List of data points to be processed.
Returns:
dict: Processed results including mean and standard deviation.
Raises:
ValueError: If data is not a list of numbers.
"""
```
2. **Class-Level Documentation**:
- Use class-level docstrings to summarize the purpose and usage of the class.
- **Example**:
```python
class DataProcessor:
"""
Class for processing and analyzing data.
This class provides methods for statistical analysis and
data transformation. Suitable for numerical data inputs.
Attributes:
data (list): List of numerical data.
"""
```
3. **In-Line Comments**:
- Use in-line comments sparingly and only to clarify complex logic or non-standard decisions in the code.
- Avoid obvious comments; instead, focus on why something is done rather than what is being done.
### API Documentation Standards
For code that interfaces with external services or shared modules, follow these standards for documenting APIs:
- **Endpoints**: Clearly list each endpoint and its purpose in the API documentation.
- **Parameters**: Define all required and optional parameters, including data types and default values.
- **Response Format**: Describe the structure and data types returned by each endpoint.
- **Error Handling**: Document possible error codes or messages and recommended solutions for common issues.
- **Usage Examples**: Provide examples showing both requests and responses to illustrate expected usage.
API documentation should be added to the `docs/ManPages/api` directory. Where possible, maintain consistency with other project documentation.
### Documentation Updates with Pull Requests
Whenever a pull request (PR) introduces new features, refactors existing code, or modifies functionality, relevant documentation files must be updated accordingly. Contributors are responsible for ensuring that:
- All impacted `README.md` files, both module-specific and global, reflect the latest changes.
- Necessary updates to docstrings, function comments, and inline comments are made to maintain clarity and usability.
*Footnote: This process is currently noted for future enforcement once the overarching program is complete.*

176
docs/PoliciesAndStandards/FilePathStandards.md Normal file
View File

@@ -0,0 +1,176 @@
# File Path Standards
## Table of Contents
1. [Purpose](#purpose)
2. [General Directory Structure](#general-directory-structure)
3. [Naming Conventions](#naming-conventions)
4. [Special Conventions](#special-conventions)
5. [Example Directory Structure](#example-directory-structure)
6. [Guidelines for Adding New Files](#guidelines-for-adding-new-files)
---
## Purpose
This document establishes the standards for organizing, naming, and structuring files and directories across all projects within **MidasTechnologies**. Following these guidelines ensures a clean, predictable file layout, making it easy for team members to navigate, understand, and maintain the repository. Clear structure contributes to project scalability, maintainability, and a smoother development experience.
---
## General Directory Structure
The project root directory, **MidasTechnologies**, includes key folders for code, tests, configuration, documentation, and other resources. The layout below provides an organized structure for optimal project navigation and resource management.
```
MidasTechnologies/
│
├── src/ # Source code for the entire project
│ ├── neural-network/ # Neural network-related code
│ ├── data-collection/ # Code and data processing tools for data collection
│ │ ├── tests/ # Contains unit tests, integration tests, and test resources
│ │ └── ... # Additional data collection code modules
│ ├── sentiment-analysis/ # Sentiment analysis-related code
│ ├── frontend/ # Frontend-related code and assets
│ └── ... # Additional modules or features as needed
│
├── docs/ # All project documentation
│ ├── BusinessDocumentation/ # Business-related documentation
│ ├── ManPages/ # Global code documentation
│ └── PoliciesAndStandards/ # Documentation standards, policies, and guidelines
│
├── config/ # Configuration files and environment settings
├── data/ # Static data files for the entire project
├── scripts/ # Utility and setup scripts (e.g., deployment scripts)
├── examples/ # Examples and sample code for demonstrating project usage
└── assets/ # Static assets (images, icons, etc.) for frontend or docs
```
---
## Naming Conventions
1. **File Names**
- All file names should be in **lowercase** and use **underscores** to replace spaces (e.g., `data_loader.py`).
- Avoid any whitespace, special characters, or symbols. Stick to letters, numbers, and underscores.
- If a file is specific to a particular module or feature, use a descriptive prefix or suffix to clarify its purpose, such as `user_model.py`.
2. **Directory Names**
- Directory names should be in **all lowercase** and use hyphens (`-`) to replace spaces (e.g., `user-auth`).
- Avoid whitespace and special characters to maintain consistency.
- **src/ Directories**: Organize files by functionality, such as `api`, `models`, `services`, `data-collection`, and `utils`.
3. **Document Files**
- **Documentation** should be in **Markdown (.md)** or **Plain Text (.txt)** format.
- Documentation filenames should follow a capitalized naming convention (e.g., `README.md` or `GitAndGithubStandards.md`).
4. **Environment Variables**
- Use **all uppercase** with underscores (e.g., `DATABASE_URL`).
5. **Configuration Files**
- Use `.yaml` or `.json` for configuration files to maintain readability and consistency.
6. **Classes**
- Class names should follow **PascalCase** (e.g., `UserService`).
### GitHub File Naming and Directory Limitations
When creating or modifying file names and directories, keep in mind GitHub's limitations and best practices:
- **Character Limit**: File and directory names should not exceed 255 characters.
- **Special Characters**: Avoid using special characters (e.g., `@`, `!`, `$`, `%`) as they may cause compatibility issues across different operating systems.
- **Case Sensitivity**: GitHub is case-sensitive, so `FilePathStandards.md` and `filepathstandards.md` are treated as distinct files. Use consistent lowercase naming for all files as per our standards.
- **Path Depth**: Aim to keep directory nesting shallow to improve readability and reduce navigation complexity.
Adhering to these guidelines will ensure compatibility across different development environments and maintain uniformity within the repository.
---
## Special Conventions
1. **Documentation Directories**
- Documentation directories in `docs/` are an exception to general naming conventions. Documentation files use **Capitalized Names** (e.g., `ManPages`, `BusinessDocumentation`).
2. **README Files**
- Each root module in the project should contain its own `README` file, which provides context and instructions for the specific module.
- The `README` file must be in Markdown (`README.md`), Plain Text (`README.txt`), or have no extension (simply `README`).
- **Global documentation** for the entire project is held in the `docs/ManPages` directory.
3. **Test Directories**
- All root modules should contain a `tests` directory, located one level deep within the main module folder (e.g., `src/data-collection/tests`). This folder will house unit tests, integration tests, and other test resources relevant to the module.
4. **Data Directories**
- A `data/` directory in the project root holds static data files used across the entire project.
- If a `data/` directory exists within a `src` module, it may have specific functionality. Refer to the module’s `README` file for further clarification.
---
## Example Directory Structure
```
MidasTechnologies/
│
├── src/
│ ├── neural-network/
│ │ ├── models.py # Neural network models
│ │ ├── training_script.py # Training scripts
│ │ └── ...
│ │
│ ├── data-collection/
│ │ ├── data_sources.py # Sources for data collection
│ │ ├── process_data.py # Data processing scripts
│ │ ├── tests/ # Contains unit tests, integration tests, and test resources
│ │ └── ...
│ │
│ ├── sentiment-analysis/
│ │ ├── analyze_sentiment.py # Sentiment analysis script
│ │ └── ...
│ │
│ ├── frontend/
│ │ ├── app.js # Frontend application code
│ │ └── ...
│ │
│ └── ...
│
├── docs/
│ ├── README.md # Project overview documentation
│ ├── BusinessDocumentation/ # Legal and business-related documentation
│ ├── ManPages/ # Global code documentation
│ └── PoliciesAndStandards/ # Markdown files on standards, policies, and guidelines
│
├── config/
│ ├── config.yaml # Main project configuration file
│ └── dev_config.yaml # Development-specific configuration
│
├── data/
│ └── sample_data.csv # Static data file example
│
├── scripts/
│ ├── setup.sh # Script to initialize the project setup
│ └── deploy.sh # Deployment script
│
├── examples/
│ ├── usage_example.py # Example usage of main project features
│ └── ...
│
└── assets/
├── logo.png # Project logo
└── favicon.ico # Icon for frontend
```
---
## Guidelines for Adding New Files
1. **Check the Existing Structure**
- Review the current directory structure before adding a new file to ensure you place it in the most relevant folder.
- Avoid creating redundant or deeply nested directories without a strong rationale.
2. **Follow Naming Conventions**
- Ensure that all files and directories follow the naming conventions specified above, keeping the structure consistent and predictable.
3. **Document New Directories**
- When adding a new folder that doesn’t fit existing patterns, include a `README.md` file or entry in the main project documentation within `docs/` to explain its purpose.
4. **Requirements for Documentation**
- All documentation files should be placed in the appropriate subdirectory within `docs/`.
- Markdown or text files should be used for documentation purposes, avoiding other file formats where possible.

846
docs/PoliciesAndStandards/GitAndGithubStandards.md Normal file
View File

@@ -0,0 +1,846 @@
[#](#) Git and GitHub Standards
## Table of Contents
1. [Overview](#overview)
2. [Understanding Git and GitHub](#understanding-git-and-github)
3. [Branching Strategy](#branching-strategy)
4. [Branch Naming Conventions](#branch-naming-conventions)
5. [Commit Message Standards](#commit-message-standards)
6. [Code Review Policy](#code-review-policy)
7. [Best Practices for Using Git](#best-practices-for-using-git)
8. [Working with Pull Requests](#working-with-pull-requests)
9. [File-Path Standards](#file-path-standards)
---
## Overview
This document provides a comprehensive set of standards and best practices for using Git and GitHub within our development team. It covers foundational topics, including the branching strategy, branch naming conventions, commit message guidelines, code review policies, and collaboration workflows. The goal is to maintain a consistent and organized approach to version control, improve collaboration, ensure code quality, and streamline the development process.
The guidelines in this document are designed to help both new and experienced team members align with the company's coding and collaboration standards, facilitating smoother project management and code integrity.
---
# Git and GitHub: A Comprehensive Guide
## Table of Contents
1. [Introduction](#introduction)
2. [Understanding Version Control](#understanding-version-control)
3. [Git Basics](#git-basics)
- [What is Git?](#what-is-git)
- [Core Concepts of Git](#core-concepts-of-git)
4. [Getting Started with Git](#getting-started-with-git)
- [Installing Git](#installing-git)
- [Configuring Git](#configuring-git)
5. [Git Essentials](#git-essentials)
- [Repositories](#repositories)
- [Staging and Committing](#staging-and-committing)
- [Branches and Merging](#branches-and-merging)
6. [Introduction to GitHub](#introduction-to-github)
- [What is GitHub?](#what-is-github)
- [Key Features of GitHub](#key-features-of-github)
7. [Working with Repositories on GitHub](#working-with-repositories-on-github)
8. [Git and GitHub Workflow](#git-and-github-workflow)
- [Forking and Cloning](#forking-and-cloning)
- [Pull Requests and Code Reviews](#pull-requests-and-code-reviews)
- [GitHub Issues and Project Management](#github-issues-and-project-management)
9. [Git Commands in Depth](#git-commands-in-depth)
10. [Advanced Git Techniques](#advanced-git-techniques)
- [Rebasing](#rebasing)
- [Cherry-Picking](#cherry-picking)
11. [Common Mistakes and How to Avoid Them](#common-mistakes-and-how-to-avoid-them)
---
## Introduction
Git and GitHub are essential tools in the modern development landscape, allowing developers to manage changes, work collaboratively, and maintain robust codebases. Git is a distributed version control system that tracks code history, while GitHub enhances this by offering a platform for hosting, reviewing, and managing projects.
This guide delves into both Git and GitHub, providing an extensive overview that covers everything from beginner concepts to advanced techniques and command usage.
---
## Understanding Version Control
**Version Control** is the backbone of any collaborative software development project. It allows teams to track code changes, collaborate seamlessly, and maintain a history of modifications to revert to previous versions when needed.
### Types of Version Control
1. **Local Version Control**: Simple, single-machine control, not suitable for team environments.
2. **Centralized Version Control (CVCS)**: Stores all file versions on a central server (e.g., SVN).
3. **Distributed Version Control (DVCS)**: Each team member has a full copy of the history and the latest version of the project, with Git being the most prominent DVCS.
Git is distributed, so it allows every developer to maintain a complete copy of the codebase on their own system, making collaboration more resilient and flexible.
---
## Git Basics
### What is Git?
Git is a **distributed version control system** (DVCS) designed to handle projects of all sizes efficiently. It tracks changes to files, enabling developers to manage, review, and revert code.
### Core Concepts of Git
1. **Repository**: A collection of files, folders, and their complete revision history.
2. **Commit**: A snapshot of changes with a unique identifier (hash).
3. **Branch**: A separate line of development within a repository.
4. **Merge**: Combines changes from one branch into another, either to incorporate new features or resolve conflicts.
5. **Pull Request (PR)**: A request to merge changes from one branch into another with a code review.
---
## Getting Started with Git
### Installing Git
To start using Git, install it on your local system:
- **Linux**: `sudo apt-get install git`
- **macOS**: `brew install git`
- **Windows**: Download from [Git’s website](https://git-scm.com/).
### Configuring Git
Set up your name and email, which will be attached to your commits:
```bash
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
```
To verify configurations:
```bash
git config --list
```
---
## Git Essentials
### Repositories
A **repository** (repo) is the core structure of any Git project. It includes all project files, a history of changes, and branch information.
### Staging and Committing
1. **Staging**: The process of adding files to the staging area to prepare them for a commit.
2. **Committing**: Saves a snapshot of the staged changes in the repository with a unique identifier and message.
Basic workflow:
```bash
git add <filename> # Stage changes
git commit -m "Add description of changes" # Commit staged changes
```
### Branches and Merging
Branches let you create separate environments for development, allowing you to work on features without affecting the main codebase. Merging incorporates changes from one branch into another.
```bash
git branch <branch-name> # Create a new branch
git checkout <branch-name> # Switch to that branch
git merge <branch-name> # Merge branch into current branch
```
---
## Introduction to GitHub
### What is GitHub?
GitHub is a cloud-based platform for Git repositories, providing tools for collaboration, code review, and project management.
### Key Features of GitHub
- **Pull Requests**: Propose and discuss changes before merging.
- **Issues**: Track bugs and feature requests.
- **GitHub Actions**: Automate workflows for CI/CD.
- **Project Boards**: Visual task management using Kanban-style boards.
---
## Working with Repositories on GitHub
1. **Creating a Repository**: Go to GitHub and create a new repository for your project.
2. **Cloning a Repository**: Copy a repository to your local machine with `git clone <repo-url>`.
3. **Syncing with Remote**: Use `git pull` to fetch and merge changes from the remote repo and `git push` to upload changes.
---
## Git and GitHub Workflow
### Forking and Cloning
**Forking** allows you to create a copy of another user’s repository, letting you make changes without affecting the original. **Cloning** copies a remote repository to your local machine.
### Pull Requests and Code Reviews
- **Opening a PR**: After pushing changes to a branch, create a PR on GitHub to propose merging them into the main branch.
- **Code Reviews**: Collaborators can provide feedback, request changes, or approve the PR.
### GitHub Issues and Project Management
GitHub offers **Issues** to track development tasks and **Project Boards** to organize these issues visually.
---
## Git Commands in Depth
### Working with Commits
- **View Commit History**: `git log` shows a detailed history of commits.
- **Viewing Differences**: `git diff` displays changes between commits or branches.
- **Amending a Commit**: Modify the last commit with `git commit --amend`.
### Branch Management
- **List Branches**: `git branch` shows all branches.
- **Delete a Branch**: `git branch -d <branch-name>` removes a local branch.
- **Rename a Branch**: `git branch -m <new-name>` renames the current branch.
### Merging Branches
Merging integrates changes from one branch to another. Use `git merge <branch-name>` to combine changes into the current branch.
### Rebasing
Rebasing applies commits from one branch onto another, maintaining a linear history:
```bash
git rebase <branch-name>
```
### Resetting and Reverting
- **Resetting**: Moves the repository to a previous state.
```bash
git reset --hard <commit-hash> # Discards all changes
git reset --soft <commit-hash> # Keeps changes in staging
```
- **Reverting**: Undoes a commit by creating a new commit.
```bash
git revert <commit-hash>
```
### Stashing
Stashing lets you save changes temporarily without committing:
```bash
git stash # Save changes
git stash apply # Restore stashed changes
```
### Cherry-Picking
Cherry-picking applies a specific commit from one branch onto another:
```bash
git cherry-pick <commit-hash>
```
### Synchronizing with Remotes
- **Fetch**: `git fetch` downloads updates from the remote repository.
- **Pull**: `git pull` combines `fetch` and `merge`.
- **Push**: `git push` uploads local changes to the remote repository.
---
## Advanced Git Techniques
### Git Aliases
Aliases can simplify complex Git commands:
```bash
git config --global alias.st status
git config --global alias.cm commit
```
### Interactive Rebase
Interactive rebasing allows you to reorder, squash, or edit commits:
```bash
git rebase -i <base-commit>
```
---
## Common Mistakes and How to Avoid Them
### Forgetting to Stage Changes
If you forget to `git add` your changes, they won’t be included in your commit. Always check with `git status` before committing.
### Overwriting History with Rebase
Rebasing can rewrite history, so it’s recommended to avoid it on branches shared with others. Only rebase
branches that haven’t been pushed or that you’re working on independently.
### Ignoring Merge Conflicts
When merging branches, conflicts may arise. Don’t skip or ignore these! Use a merge tool or manually resolve conflicts, and make sure to commit the resolved changes.
### Accidental Commits to the Wrong Branch
Switching branches without committing or stashing changes can result in accidental commits. Always check your branch with `git branch` before committing and use `git stash` to save uncommitted changes if you need to switch.
### Pushing Sensitive Information
Never commit sensitive data like passwords, API keys, or credentials. Use a `.gitignore` file to exclude sensitive files and directories:
```bash
echo "config.json" >> .gitignore
```
### Force Pushing
Using `git push --force` can overwrite others' work. Only use `--force` when absolutely necessary, and communicate with your team beforehand. I have removed `--force` capabilitys on the github
---
# Branching Structure and Naming Conventions
## Purpose
This document establishes standards for creating, naming, and managing branches within our repository. Following these guidelines will ensure a clean, organized codebase, making it easier for the team to manage code changes, facilitate collaboration, and maintain clarity across multiple projects.
## Table of Contents
1. [Branch Structure](#branch-structure)
- [Main Branch](#main-branch)
- [Development Branch](#development-branch)
- [Feature and Ad-Hoc Branches](#feature-and-ad-hoc-branches)
2. [Branch Naming Conventions](#branch-naming-conventions)
- [Prefixes](#prefixes)
- [Examples](#examples)
3. [File Naming Standards](#file-naming-standards)
4. [Workflow for Contributors](#workflow-for-contributors)
---
## Branch Structure
Our repository follows a structured branching system with two main branches, `main` and `dev`, along with various **feature** and **ad-hoc branches** off `dev` for specific tasks. **All branches off `dev` should be named according to the conventions defined in this document.**
### 1. `main` Branch
- **Purpose**: The `main` branch contains **production-ready code**. This is where stable, tested code resides and reflects the latest release version of the codebase.
- **Access**: Only project maintainers can directly merge code into `main`.
- **Merges**: Code merges into `main` should always come from `dev` after passing code reviews and tests.
- **Protection**: This branch is protected by branch rules, requiring code reviews and successful checks before merging.
### 2. `dev` Branch
- **Purpose**: The `dev` branch is a **staging branch for testing** new features, bug fixes, and documentation updates before they reach `main`.
- **Access**: All contributors can create branches off `dev` for their work. Contributors are not allowed to push directly to `dev`; all changes must be submitted via pull requests.
- **Merges**: All feature, bugfix, documentation, and test branches should be merged back into `dev` after review and testing.
### 3. Feature and Ad-Hoc Branches
- **Purpose**: Branches off `dev` are used for specific features, bug fixes, testing updates, and documentation changes. These branches must follow the naming conventions detailed in the following section.
- **Lifecycle**: Feature and ad-hoc branches are created for individual tasks and are short-lived. Once their purpose is completed, they are merged into `dev` and deleted.
- **Permissions**: Contributors create, work on, and manage these branches off `dev` but **must submit pull requests (PRs) for all changes to `dev`**.
> **Note**: Only the GitHub repository manager may deviate from these conventions.
---
## Branch Naming Conventions
To maintain organization and readability, all branches off `dev` must follow these naming conventions. Standard prefixes indicate the branch's purpose and scope, providing clarity to other contributors.
### General Rules
- **Lowercase Only**: Branch names must be in lowercase.
- **Hyphens for Separation**: Use hyphens (`-`) to separate words within a branch name.
- **Descriptive Names**: Branch names should indicate the purpose of the branch (e.g., feature, bugfix) and include an identifier if relevant.
- **Reference to Issue/Feature Numbers**: When applicable, include a reference to the GitHub issue number.
### Prefixes
| Prefix | Purpose | Example |
|--------------|-------------------------------------------|-------------------------------------------|
| `feature/` | For new features or enhancements | `feature/user-authentication` |
| `bugfix/` | For fixing known bugs or issues | `bugfix/1023-login-error` |
| `docs/` | For documentation updates and additions | `docs/api-endpoints-documentation` |
| `test/` | For changes or additions to tests | `test/add-unit-tests` |
| `hotfix/` | For critical fixes that need immediate attention in `dev` or `main` | `hotfix/production-fix-login-error` |
> **Note**: All prefixes indicate branches off `dev` and should not directly branch from `main` without repository manager approval.
### Branch Names, Scenarios and Examples
| Purpose | Branch Name | Description |
|-------------------|------------------------------------|--------------------------------------------|
| New Feature | `feature/user-registration` | Adds user registration functionality |
| Bug Fix | `bugfix/215-api-authorization` | Fixes authorization issue on API requests |
| Documentation | `docs/setup-instructions` | Adds setup instructions to documentation |
| Testing | `test/integration-test-api` | Adds integration tests for API endpoints |
| Hotfix | `hotfix/cache-issue` | Urgent fix for cache-related issue |
When working on specific aspects of the project, contributors should use designated branches to ensure consistency and organization. **All branches, unless specified, must be created off the `dev` branch**. Below are common scenarios and the appropriate branches for each task:
#### 1. **Adding a Web Scraper**
- **Branch**: `DataCollection` (branch off `dev`)
- **Process**:
- Begin by switching to the `dev` branch:
```bash
git checkout dev
git pull origin dev
```
- Check out the `DataCollection` branch:
```bash
git checkout DataCollection
```
- If `DataCollection` does not exist, create it off `dev`:
```bash
git checkout -b DataCollection dev
git push -u origin DataCollection
```
#### 2. **Adding Documentation**
- **Branch**: `docs` (branch off `dev`)
- **Process**:
- Switch to the `dev` branch and pull the latest updates:
```bash
git checkout dev
git pull origin dev
```
- Check out the `docs` branch:
```bash
git checkout docs
```
- If `docs` does not exist, create it off `dev`:
```bash
git checkout -b docs dev
git push -u origin docs
```
#### 3. **Adding Business Files**
- **Branch**: `businessfiles` (branch off `dev`)
- **Process**:
- Ensure you’re working from the latest `dev` updates:
```bash
git checkout dev
git pull origin dev
```
- Check out the `businessfiles` branch:
```bash
git checkout businessfiles
```
- If `businessfiles` does not exist, create it off `dev`:
```bash
git checkout -b businessfiles dev
git push -u origin businessfiles
```
#### 4. **Bug Fixes**
- **Branch**: `bugfix` (branch off `dev`)
- **Process**:
- Start from the latest `dev` updates:
```bash
git checkout dev
git pull origin dev
```
- Check out the `bugfix` branch:
```bash
git checkout bugfix
```
- If `bugfix` does not exist, create it:
```bash
git checkout -b bugfix dev
git push -u origin bugfix
```
#### 5. **Hotfixes**
- **Branch**: `hotfix` (branch off `dev`)
- **Process**:
- Ensure your local `dev` branch is up to date:
```bash
git checkout dev
git pull origin dev
```
- Check out the `hotfix` branch:
```bash
git checkout hotfix
```
- If `hotfix` does not exist, create it:
```bash
git checkout -b hotfix dev
git push -u origin hotfix
```
#### 6. **Testing**
- **Branch**: `testing` (branch off `dev`)
- **Process**:
- Start from the latest `dev` branch:
```bash
git checkout dev
git pull origin dev
```
- Check out the `testing` branch:
```bash
git checkout testing
```
- If `testing` does not exist, create it:
```bash
git checkout -b testing dev
git push -u origin testing
```
#### 7. **Feature Development**
- **Branch**: `feature/feature-name` (branch off `dev`)
- **Process**:
- Before starting, always check if a specific feature branch exists.
- If no specific branch exists, create a new feature branch off `dev`:
```bash
git checkout dev
git pull origin dev
git checkout -b feature/your-feature-name dev
git push -u origin feature/your-feature-name
```
- **Note**: Follow the naming conventions for all feature branches and verify it branches off `dev`.
---
## Handling Merge Conflicts
Merge conflicts can occur when changes in two branches affect the same lines of code. Here are best practices and commands to resolve them effectively.
### Steps to Resolve Merge Conflicts
1. **Identify the Conflict**:
- When attempting to merge, Git will notify you of conflicts. Use the `git status` command to identify files with conflicts:
```bash
git status
```
2. **Open and Review Conflicting Files**:
- Open the conflicting files in an editor. Git marks conflicts with `<<<<<<<`, `=======`, and `>>>>>>>`.
- Manually review the changes, decide which version to keep, or combine changes where necessary.
3. **Mark Conflicts as Resolved**:
- After resolving conflicts in each file, mark it as resolved:
```bash
git add <file-name>
```
4. **Complete the Merge**:
- Once all conflicts are resolved, commit the merge:
```bash
git commit
```
5. **Push the Resolved Branch**:
- After committing, push the branch to the remote repository:
```bash
git push
```
### Best Practices for Conflict Resolution
- **Resolve Locally**: If possible, resolve conflicts on your local machine to minimize errors and ensure all changes are reviewed.
- **Communicate with Team Members**: If the conflict is complex or affects significant code, communicate with the involved team members for clarity and to avoid overwriting important changes.
- **Use Git Tools for Assistance**: Tools like `git diff` and `git log` are helpful for understanding changes in context. Additionally, many IDEs offer merge tools that visualize conflicts.
---
## File Naming Standards
To maintain a consistent and organized structure, file names should follow these standards based on file type.
### Documentation Files
- **Capitalized Case**: Use Capitalized Case for documentation files (e.g., `GitAndGitHubStandards.md`).
- **Avoid Special Characters**: Do not use spaces or special characters.
- **Location**: Documentation related to each project should be stored within a `docs/` or `documentation/` directory in the root of each project.
### Code Files
- **Lowercase with Underscores**: Use lowercase names with underscores (e.g., `user_authentication.py`).
- **No Spaces or Special Characters**: Avoid spaces or special characters in code file names.
- **Descriptive Names**: Name files according to their primary function or feature (e.g., `data_processing.py` for data processing functions).
### Directory Naming
- **Organization by Function**: Directories should be organized by functionality (e.g., `models/`, `controllers/`, `tests/`).
- **Standard Directory Names**: Keep directory names simple and standardized to make navigation intuitive.
> **Example Directory Structure**:
```
project_root/
│
├── docs/
│ └── README.md
├── src/
│ ├── models/
│ ├── controllers/
│ ├── utils/
│ └── main.py
└── tests/
├── test_data_processing.py
└── test_user_authentication.py
```
---
## Workflow for Contributors
This workflow ensures consistent practices across contributors for setting up branches, working locally, and pushing changes.
### Step 0: Clone the Repository
Clone the repository to your local environment if you haven’t already.
```bash
git clone git@github.com:MiadTechnologiesLCC/MidasTechnologies.git
cd MidasTechnologies
```
### Step 1: Set Up Branch Tracking
Ensure you have the latest branches set up locally:
```bash
git fetch origin
```
### Step 2: Check Out `dev` for New Work
Always base new work off the `dev` branch:
```bash
git checkout dev
git pull origin dev # Ensure dev is up to date
```
### Step 3: Create a New Branch Off `dev`
Create a new branch for your work based on the type of work you’re doing (feature, bugfix, docs, etc.). Follow the branch naming conventions.
```bash
git checkout -b feature/new-feature-name dev
```
### Step 4: Make and Commit Changes
As you work, make regular commits with clear, descriptive messages following our commit message standards:
```bash
git add .
git commit -m "feat: add feature description"
```
### Step 5: Push the Branch to GitHub
When ready, push your branch to GitHub:
```bash
git push -u origin feature/new-feature-name
```
### Step 6: Create a Pull Request
- **Create PR**: Go to GitHub and create a pull request (PR) from your feature branch into `dev`.
- **Review Request**: Assign reviewers as necessary and respond to feedback.
- **Ensure Compliance**: Confirm that the PR adheres to all required tests, checks, and naming conventions before approval and merging.
---
## Common Mistakes to Avoid
1. **Directly Branching Off `main`**: All branches should be created off `dev` unless given explicit permission from the repository manager.
2. **Inconsistent Naming**: Stick to prefix conventions and lowercase names with hyphens to maintain clarity.
3. **Forgetting to Pull `dev` Updates**: Always pull the latest changes from `dev` to avoid conflicts.
4. **Pushing to `dev` Without a PR**: Changes should never be pushed directly to `dev`; submit all changes via a pull request.
5. **Improper File Naming**: Follow naming standards strictly, with documentation files in Capitalized Case and code files in lowercase with underscores.
---
# Code Review Policy
## Table of Contents
1. [Code Review Workflow](#code-review-workflow)
- [Opening a Pull Request](#opening-a-pull-request)
- [Review Assignment and Timeline](#review-assignment-and-timeline)
2. [Working with Pull Requests](#working-with-pull-requests)
- [Create a PR for Each Feature](#create-a-pr-for-each-feature)
- [Resolve All Conversations Before Merging](#resolve-all-conversations-before-merging)
- [Merge Protocol](#merge-protocol)
3. [Code Review Focus Areas](#code-review-focus-areas)
- [Code Quality and Consistency](#code-quality-and-consistency)
- [Functionality and Completeness](#functionality-and-completeness)
- [Testing and Coverage](#testing-and-coverage)
- [Security and Performance](#security-and-performance)
- [Documentation and Commenting](#documentation-and-commenting)
- [File Structure and Organization](#file-structure-and-organization)
4. [Reviewer Responsibilities](#reviewer-responsibilities)
5. [Contributor Responsibilities](#contributor-responsibilities)
6. [Final Approval and Merging Process](#final-approval-and-merging-process)
- [Approval Requirements](#approval-requirements)
- [Merging to Dev or Main](#merging-to-dev-or-main)
- [Final Checks Before Merging](#final-checks-before-merging)
7. [Common Code Review Mistakes to Avoid](#common-code-review-mistakes-to-avoid)
8. [Post-Review Responsibilities](#post-review-responsibilities)
---
## Code Review Workflow
### Opening a Pull Request
When creating a Pull Request (PR), adhere to the following guidelines to ensure a smooth and productive review process:
1. **Branch Source**:
- PRs must originate from designated branches, such as **feature**, **bugfix**, **hotfix**, or **docs**, following the [Branch Naming Conventions](./Branch%20Naming%20Conventions.md).
- PRs should generally target the `dev` branch, while only production-ready PRs may target the `main` branch. Merges to `main` are restricted to project maintainers to maintain code quality.
2. **Title & Description**:
- Use a clear and concise title for each PR.
- Provide a thorough description, covering context, scope, and any relevant issues or implementation details.
- Clearly indicate any special requirements for deployment, breaking changes, or additional dependencies.
3. **File Organization**:
- Follow the [# file-path standards](#file-path-standards) to ensure all new files and directories are structured for efficient navigation and ease of maintenance.
### Review Assignment and Timeline
- Assign PRs to experienced reviewers in relevant code areas. For complex changes, multiple reviewers may be required.
- Use GitHub tags to notify reviewers, aiming for a 24–48 hour turnaround on PR reviews to support an efficient workflow.
---
## Working with Pull Requests
### Create a PR for Each Feature
- Link the PR to any associated issues or tasks for traceability.
- Request a review from team members knowledgeable about the relevant functionality.
### Resolve All Conversations Before Merging
- Address all reviewer feedback and mark conversations as resolved before final approval.
- If substantial modifications are made in response to feedback, re-request a review to ensure consensus.
### Merge Protocol
- **PRs into `dev`**: These require at least one reviewer’s approval.
- **PRs from `dev` to `main`**: Limited to the project maintainer, with thorough testing and final approval required to ensure the stability of `main`.
---
## Code Review Focus Areas
Reviewers should concentrate on these critical areas to ensure quality, functionality, and maintainability across the codebase:
### Code Quality and Consistency
- Follow our [Coding Standards](./Coding%20Standards.md) for readability, maintainability, and consistency.
- Maintain modularity and avoid redundancy, using existing functions or libraries where appropriate.
- Confirm adherence to language-specific standards (e.g., PEP8 for Python).
### Functionality and Completeness
- Verify that the code performs as intended without regressions.
- Ensure all specified use cases, including edge cases, are covered. Seek clarification from the contributor if requirements are ambiguous.
### Testing and Coverage
- Check for sufficient test coverage, ideally at least 85%, with a preference for automated tests.
- Ensure all tests, including unit, integration, and end-to-end (E2E) tests, pass successfully.
- Confirm compliance with the [# file-path standards](#file-path-standards) for consistency in test file organization.
### Security and Performance
- Assess for potential security vulnerabilities, especially in areas related to data handling, user authentication, or API calls.
- Evaluate performance, suggesting improvements if any bottlenecks or inefficiencies are detected.
### Documentation and Commenting
- All public functions, classes, and methods should have clear docstrings, following our [Documentation Standards](./Documentation%20Standards.md).
- Complex logic should be well-commented to explain non-standard approaches or optimizations.
- Verify updates to user or developer documentation when relevant.
### File Structure and Organization
- Ensure new files and directories align with the [# file-path standards](#file-path-standards) to maintain logical structure.
- Check that file organization is consistent with the established hierarchy, supporting ease of access and maintenance.
---
## Reviewer Responsibilities
Reviewers are accountable for providing timely, constructive, and actionable feedback:
- **Timely Feedback**: Complete PR reviews within 24–48 hours whenever possible.
- **Constructive Feedback**: Offer specific, actionable suggestions for improvements, avoiding vague criticism.
- **Approval Process**:
- Only approve PRs if they meet quality standards and have no outstanding issues.
- Request changes if additional work is needed or standards are not met.
- Ensure compliance with the [# file-path standards](#file-path-standards), naming conventions, and coding guidelines.
- **Professionalism**: Maintain respect and clarity in all feedback, focusing on improvement.
---
## Contributor Responsibilities
Contributors are responsible for ensuring their code is up to standard prior to submission:
1. **Self-Review**: Conduct a thorough self-review, verifying clarity, standards compliance, and testing.
2. **Feedback Response**: Address all reviewer comments and make necessary changes, re-requesting a review if major adjustments are made.
3. **Conversation Resolution**: Mark all feedback conversations as resolved before requesting final approval.
4. **Commit Standards**: Follow [Commit Message Standards](./Commit%20Message%20Standards.md) to keep commit messages informative, consistent, and concise.
---
## Final Approval and Merging Process
### Approval Requirements
- PRs must have at least one reviewer’s approval, with additional reviewers for complex or high-risk changes.
- Only project maintainers or designated personnel may approve and merge PRs into `main`.
### Merging to Dev or Main
- **Merging into `dev`**: Contributors may merge PRs after at least one review and approval.
- **Merging into `main`**: Restricted to maintainers; requires extensive testing to confirm production readiness.
### Final Checks Before Merging
- Ensure all tests pass and the latest code changes are integrated into the PR.
- Verify the [# file-path standards](#file-path-standards) are followed and the directory structure is organized.
- Update the PR description with any final notes or additional context.
---
## Common Code Review Mistakes to Avoid
1. **Skipping Self-Review**: Self-review reduces back-and-forth and helps identify issues preemptively.
2. **Insufficient Test Coverage**: Lack of comprehensive tests can lead to unexpected bugs. Aim to cover all use cases and edge scenarios.
3. **Premature Approval**: Ensure understanding of the PR’s purpose and functionality before approving.
4. **File and Path Non-Compliance**: Files should adhere to naming and path standards as detailed in [# file-path standards](#file-path-standards).
---
## Post-Review Responsibilities
### Continuous Improvement
- Identify opportunities for process improvement based on challenges encountered during the review.
- Record valuable lessons, significant changes, or patterns in a shared knowledge base for future use.
### Follow-up Tasks
- Log any remaining issues or future improvements as GitHub issues for future sprints.
- Update documentation when significant changes impact user guides, API references, or other project docs.
### Retrospective and Feedback
- Periodically evaluate the review process's effectiveness, gathering feedback to refine workflow, collaboration, and code quality practices.

83
docs/PoliciesAndStandards/README.md Normal file
View File

@@ -0,0 +1,83 @@
# Policies and Standards
Welcome to the **Policies and Standards** directory! This section contains critical documentation outlining the standards, practices, and workflows that guide our team’s development and collaboration processes. Adhering to these policies ensures consistency, quality, and efficient collaboration within the project.
## Table of Contents
1. [Overview](#overview)
2. [File Descriptions](#file-descriptions)
- [CodingStandards.md](#codingstandardsmd)
- [CommunicationStandards.md](#communicationstandardsmd)
- [DocumentationStandards.md](#documentationstandardsmd)
- [FilePathStandards.md](#filepathstandardsmd)
- [GitAndGitHubStandards.md](#gitandgithubstandardsmd)
3. [Using this Documentation](#using-this-documentation)
---
## Overview
This directory serves as the central reference point for all policies and standards governing our project’s development practices. Each document is purpose-built to address specific facets of our workflow, from coding conventions to GitHub management. Contributors should familiarize themselves with each section to ensure their work aligns with our established standards.
## File Descriptions
### 1. CodingStandards.md
**Purpose**: Defines the coding standards for our primary language, Python, along with additional guidelines for languages that interact with Python (e.g., C, JSON, Rust).
**Key Points**:
- **Python Coding Standards**: Emphasizes PEP8 adherence, docstrings, naming conventions, and version control with `venv`.
- **Interface Language Standards**: Guidance on C extensions, Rust integration, TypeScript, JSON, and SQL standards.
- **Virtual Environments**: Explanation of `venv` management, `.gitignore` configurations, and best practices for `requirements.txt`.
**Useful for**: Any team member involved in writing or reviewing code across languages, especially those needing to understand Python-centric practices.
### 2. CommunicationStandards.md
**Purpose**: Provides guidelines for communication, task assignment, and collaboration methods, ensuring smooth project coordination and prompt issue resolution.
**Key Points**:
- **Communication Channels**: Standards for using GitHub Issues, Pull Requests, and team meetings.
- **Collaborative Practices**: Code review protocols, issue assignments, and conflict resolution strategies.
- **Labor Distribution**: Suggested systems for assigning and managing tasks effectively within GitHub.
**Useful for**: Contributors and project managers coordinating workflow, code reviews, and project task assignments.
### 3. DocumentationStandards.md
**Purpose**: Outlines best practices for documenting code, project functionality, and business-related information, maintaining accessible and comprehensive documentation.
**Key Points**:
- **README and Inline Documentation**: Standards for writing and organizing README files for each module, docstrings, and inline comments.
- **Documentation File Naming**: Instructions on file naming, Markdown use, and placement of documentation within the directory structure.
- **Documentation for Modular Code**: Guidelines on modular documentation, where root-level modules should contain individual `README.md` files.
**Useful for**: Anyone writing documentation, comments, or README files to support the codebase and clarify business practices.
### 4. FilePathStandards.md
**Purpose**: Establishes naming conventions and directory structures to ensure consistency across the entire codebase.
**Key Points**:
- **Directory Structure**: Suggested layout for primary directories (`src/`, `docs/`, `tests/`, etc.) and subdirectories for functionality-specific code.
- **File Naming Conventions**: Rules for lowercase, underscored, and hyphenated naming styles to avoid ambiguity.
- **Special Conventions**: Specific guidelines for the `docs/` directory structure, README file formats, and `data` directory usage.
**Useful for**: Contributors adding or reorganizing files, ensuring all files and directories comply with standard naming and structure guidelines.
### 5. GitAndGitHubStandards.md
**Purpose**: Provides a thorough explanation of Git and GitHub practices, branch naming conventions, and commit message formatting, ensuring effective version control and collaboration.
**Key Points**:
- **Git Overview and Workflows**: Explains the basics of Git, including branch structure, merging practices, and handling merge conflicts.
- **Commit Messages**: Detailed formatting for clear and useful commit messages.
- **Branch Naming Conventions**: Guidelines on naming branches based on purpose (e.g., `feature/`, `bugfix/`) to keep the repository organized.
**Useful for**: Contributors managing version control through Git and GitHub, particularly when creating branches or preparing for merges.
---
## Using this Documentation
- **Navigation**: Each document can be navigated using the Table of Contents above. For users with VimWiki enabled in Vim or Neovim, Markdown links will automatically convert into navigable wiki-style links.
- **Before Making Changes**: Always review the relevant standards document before adding or modifying files, writing documentation, or altering code.
- **Updating Documentation**: If your code contributions impact an existing policy or standard, consult with the project maintainer to ensure documentation is updated accordingly.
By following the practices outlined in these files, you’ll help maintain the quality, readability, and organization of our project, benefiting both current contributors and future collaborators.

69
docs/README.md Normal file
View File

@@ -0,0 +1,69 @@
# Documentation Directory
Welcome to the **Documentation** directory for the project. This directory is divided into three primary sections: **Business Documentation**, **Policies and Standards**, and **Man Pages**. Each subdirectory has a unique purpose and serves to organize our project’s documentation comprehensively. Please follow the structure and guidelines below when adding new documents.
---
## Directory Structure
```
docs/
│
├── business_docs/
│ ├── business_plan.md
│ ├── lcc_documentation.md
│ └── legal_license.md
│
├── policies_standards/
│ ├── coding_standards.md
│ ├── code_review_policy.md
│ ├── documentation_standards.md
│ └── file_path_standards.md
│
└── man_pages/
└── overall_code_documentation.md
```
---
## Sections
### 1. Business Documentation
- **Purpose**: Contains all relevant business-related documentation, legal filings, and operational plans. This section helps ensure that we keep a clear record of our company’s structural and strategic information.
- **Contents**:
- `business_plan.md`: Outlines our company’s mission, vision, target market, competitive analysis, and growth strategies.
- `lcc_documentation.md`: Contains LLC formation details, ownership structure, and any legal requirements.
- `legal_license.md`: Provides a summary of licenses, terms, and legal disclaimers for our software products.
### 2. Policies and Standards
- **Purpose**: This section includes all coding, collaboration, and workflow guidelines to maintain consistency and quality across the project. It also contains standard operating procedures (SOPs) for code quality and collaboration, fostering a productive and unified development environment.
- **Contents**:
- `coding_standards.md`: Outlines coding conventions and best practices for this project.
- `code_review_policy.md`: Details our policies for reviewing code and handling pull requests.
- `documentation_standards.md`: Specifies standards for documenting code and creating README files.
- `file_path_standards.md`: Establishes naming conventions and organization standards for files and directories.
### 3. Man Pages
- **Purpose**: Acts as an accessible, high-level guide to overall code structure, intended to assist both new and existing team members in understanding the project’s architecture. This section contains **man pages** for broader code documentation, while specific functionality and module-level details can be found in `src/` README files.
- **Contents**:
- `overall_code_documentation.md`: Offers a high-level overview of the codebase, including descriptions of major components, workflows, and integrations within the project.
---
## Guidelines for Adding Documentation
1. **Check the Directory**:
- Ensure you are adding files to the correct subdirectory according to the document’s purpose.
2. **Naming Conventions**:
- Use clear, concise, and descriptive file names for new documents.
- File names should be lowercase and use underscores instead of spaces (e.g., `new_policy_doc.md`).
3. **Update Section Summaries**:
- When adding new files, briefly update this `README.md` to reflect any changes within each section.
---
Each contributor should refer to this directory and structure before adding or modifying documentation to maintain clarity and organization throughout the project. For specific questions on policies or code documentation, refer to the relevant files in **Policies and Standards** or **Man Pages**.

65
idealstructure.md
View File

@@ -1,65 +0,0 @@
To maintain a clean and organized GitHub repository structure, particularly with multiple documentation files, it’s essential to have a structured hierarchy. Here’s a layout that will keep your project files organized and accessible for contributors:
### Suggested Repository Structure
```plaintext
MidasTechnologies/
├── .github/ # GitHub-specific files
│ ├── ISSUE_TEMPLATE/ # GitHub issue templates
│ ├── PULL_REQUEST_TEMPLATE.md # Pull request template
│ └── workflows/ # CI/CD workflow files
│ └── ci.yml # Example CI configuration (e.g., GitHub Actions)
├── docs/ # Documentation directory
│ ├── README.md # Overview of documentation contents
│ ├── setup/ # Setup-related docs
│ │ ├── installation.md # Installation instructions
│ │ └── configuration.md # Configuring the environment or application
│ ├── guides/ # Guide files for team collaboration
│ │ ├── branching.md # Branching strategy guide (from previous step)
│ │ ├── code_style.md # Code style and formatting standards
│ │ ├── contributing.md # Contribution guidelines
│ │ └── testing.md # Testing and CI/CD setup guide
│ ├── reference/ # Technical references or design documentation
│ │ ├── architecture.md # Project architecture
│ │ └── data_structures.md # Key data structures and algorithms used
│ └── API/ # API documentation, if applicable
│ └── api_overview.md # Overview of APIs used or exposed by the project
├── src/ # Source code directory
│ ├── main/ # Main branch source code
│ └── dev/ # Development branch source code
├── tests/ # Testing suite and files
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── README.md # Overview of testing guidelines
├── .gitignore # Git ignore file
├── LICENSE # License file for the repository
└── README.md # Main README for the repository
```
### Directory Explanation
1. **`.github/`:** Contains GitHub-specific configuration files, such as issue and pull request templates, as well as workflows for automated testing and CI/CD.
2. **`docs/`:** All documentation files, organized into meaningful subdirectories.
- **`setup/`:** For setup-related documentation like installation, configuration, and environment setup.
- **`guides/`:** Team collaboration guides, including the branching guide, contribution guidelines, and code style documents.
- **`reference/`:** More technical references, project architecture, and specific implementations for future reference.
- **`API/`:** Documentation for APIs if your project has them.
3. **`src/`:** Contains all source code, organized into the `main` and `dev` branches or modules if needed.
4. **`tests/`:** For all testing-related files, including subdirectories for unit and integration tests, plus a README outlining test protocols.
5. **Project Root Files:**
- **`.gitignore`:** For files and directories to ignore in the repository.
- **`LICENSE`:** Licensing information for the repository.
- **`README.md`:** Main project overview, including how to get started, major features, and basic setup steps.
### Additional Tips
- **Keep Documentation Centralized:** The `docs/` directory keeps all documentation in one place, easy to locate and update.
- **Standardize Documentation Files:** Use markdown (`.md`) for all documentation to ensure readability on GitHub and other markdown-rendering platforms.
- **Use Templates in `.github/`:** Issue and pull request templates help streamline contributions and feedback.
- **README.md Clarity:** The main README file should serve as a quick start guide and overview for the repository. This document should also link to relevant documentation files within `docs/`.
This structure will make the repository accessible and organized, simplifying onboarding, documentation, and collaboration among team members.

0
API/API_1.ipynb → src/API/API_1.ipynb
View File

0
API/API_2 (1).ipynb → src/API/API_2 (1).ipynb
View File

0
API/Trading_Bot_Development_Strategy (1).docx → src/API/Trading_Bot_Development_Strategy (1).docx
View File

0
Data-Collection/.gitignore → src/Data-Collection/.gitignore vendored
View File

0
Data-Collection/WebScraper/README.md → src/Data-Collection/WebScraper/README.md
View File

0
Data-Collection/WebScraper/assets/oil_key_words.txt → src/Data-Collection/WebScraper/assets/oil_key_words.txt
View File

0
Data-Collection/WebScraper/data/oil_news.json → src/Data-Collection/WebScraper/data/oil_news.json
View File

0
Data-Collection/WebScraper/data/preprocessed_oil_news.json → src/Data-Collection/WebScraper/data/preprocessed_oil_news.json
View File

0
Data-Collection/WebScraper/main.py → src/Data-Collection/WebScraper/main.py
View File

0
Data-Collection/WebScraper/main.py.bak → src/Data-Collection/WebScraper/main.py.bak
View File

0
Data-Collection/WebScraper/scrapers/__pycache__/oil_news_preprocessor.cpython-311.pyc → src/Data-Collection/WebScraper/scrapers/__pycache__/oil_news_preprocessor.cpython-311.pyc
View File

0
Data-Collection/WebScraper/scrapers/__pycache__/oil_news_scraper.cpython-311.pyc → src/Data-Collection/WebScraper/scrapers/__pycache__/oil_news_scraper.cpython-311.pyc
View File

0
Data-Collection/WebScraper/scrapers/backups/oil_news_preprocessor.py.bak → src/Data-Collection/WebScraper/scrapers/backups/oil_news_preprocessor.py.bak
View File

0
Data-Collection/WebScraper/scrapers/backups/oil_news_scraper.py.bak → src/Data-Collection/WebScraper/scrapers/backups/oil_news_scraper.py.bak
View File

0
Data-Collection/WebScraper/scrapers/oil_news_preprocessor.py → src/Data-Collection/WebScraper/scrapers/oil_news_preprocessor.py
View File

0
Data-Collection/WebScraper/scrapers/oil_news_scraper.py → src/Data-Collection/WebScraper/scrapers/oil_news_scraper.py
View File

0
Data-Collection/WebScraper/scrapers/tests/author_info.json → src/Data-Collection/WebScraper/scrapers/tests/author_info.json
View File

0
Data-Collection/WebScraper/scrapers/tests/author_scraper_test.py → src/Data-Collection/WebScraper/scrapers/tests/author_scraper_test.py
View File

0
Data-Collection/WebScraper/scrapers/tests/author_scraper_test.py.bak → src/Data-Collection/WebScraper/scrapers/tests/author_scraper_test.py.bak
View File

0
Data-Collection/WebScraper/scrapers/tests/selenium_webdriver_test.py → src/Data-Collection/WebScraper/scrapers/tests/selenium_webdriver_test.py
View File

0
Data-Collection/WebScraper/setup.py → src/Data-Collection/WebScraper/setup.py
View File

0
GUSHTradingBotV1.0.py → src/GUSHTradingBotV1.0.py
View File