sqa 0.0.32 → 0.0.38

data/docs/assets/images/getting-started-workflow.svg

@@ -0,0 +1,88 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1400 450" width="1400" height="450">
+  <defs>
+    <style>
+      .box { stroke: #ffffff; stroke-width: 3; }
+      .text { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 15px; font-weight: 600; text-anchor: middle; }
+      .small-text { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 13px; font-weight: 500; text-anchor: middle; }
+      .arrow { stroke: #ffffff; stroke-width: 2.5; fill: none; marker-end: url(#arrowhead); }
+      .diamond { stroke: #ffffff; stroke-width: 3; }
+      .label { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 14px; font-weight: 500; }
+    </style>
+    <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#ffffff" />
+    </marker>
+  </defs>
+
+  <!-- Install SQA -->
+  <rect x="30" y="180" width="150" height="70" rx="8" class="box" fill="#2E86DE"/>
+  <text x="105" y="210" class="text">Install</text>
+  <text x="105" y="230" class="text">SQA</text>
+
+  <!-- Configure API Keys -->
+  <rect x="220" y="180" width="150" height="70" rx="8" class="box" fill="#3867D6"/>
+  <text x="295" y="210" class="text">Configure</text>
+  <text x="295" y="230" class="text">API Keys</text>
+
+  <!-- Load Stock Data -->
+  <rect x="410" y="180" width="150" height="70" rx="8" class="box" fill="#10AC84"/>
+  <text x="485" y="210" class="text">Load Stock</text>
+  <text x="485" y="230" class="text">Data</text>
+
+  <!-- Calculate Indicators -->
+  <rect x="600" y="180" width="150" height="70" rx="8" class="box" fill="#EE5A6F"/>
+  <text x="675" y="210" class="text">Calculate</text>
+  <text x="675" y="230" class="text">Indicators</text>
+
+  <!-- Apply Strategies -->
+  <rect x="790" y="180" width="150" height="70" rx="8" class="box" fill="#F368E0"/>
+  <text x="865" y="210" class="text">Apply</text>
+  <text x="865" y="230" class="text">Strategies</text>
+
+  <!-- Analysis Type Diamond -->
+  <g transform="translate(1030, 215)">
+    <polygon points="0,-50 70,0 0,50 -70,0" class="diamond" fill="#FD79A8"/>
+    <text x="0" y="-5" class="small-text">Analysis</text>
+    <text x="0" y="12" class="small-text">Type</text>
+  </g>
+
+  <!-- Run Backtest -->
+  <rect x="1155" y="50" width="150" height="70" rx="8" class="box" fill="#FF9F43"/>
+  <text x="1230" y="80" class="text">Run</text>
+  <text x="1230" y="100" class="text">Backtest</text>
+
+  <!-- Stream Real-Time -->
+  <rect x="1155" y="180" width="150" height="70" rx="8" class="box" fill="#FFA502"/>
+  <text x="1230" y="210" class="text">Stream</text>
+  <text x="1230" y="230" class="text">Real-Time</text>
+
+  <!-- Explore in Console -->
+  <rect x="1155" y="310" width="150" height="70" rx="8" class="box" fill="#FF6348"/>
+  <text x="1230" y="333" class="text">Explore in</text>
+  <text x="1230" y="353" class="text">Console</text>
+
+  <!-- Review Results -->
+  <rect x="1155" y="420" width="150" height="50" rx="8" class="box" fill="#26DE81"/>
+  <text x="1230" y="450" class="text">Review Results</text>
+
+  <!-- Arrows - Main flow -->
+  <path d="M 180 215 L 220 215" class="arrow"/>
+  <path d="M 370 215 L 410 215" class="arrow"/>
+  <path d="M 560 215 L 600 215" class="arrow"/>
+  <path d="M 750 215 L 790 215" class="arrow"/>
+  <path d="M 940 215 L 960 215" class="arrow"/>
+
+  <!-- Arrows from diamond -->
+  <path d="M 1030 165 L 1030 85 L 1155 85" class="arrow"/>
+  <path d="M 1100 215 L 1155 215" class="arrow"/>
+  <path d="M 1030 265 L 1030 345 L 1155 345" class="arrow"/>
+
+  <!-- Arrows to Review Results -->
+  <path d="M 1230 120 L 1230 420" class="arrow"/>
+  <path d="M 1230 250 L 1230 420" class="arrow"/>
+  <path d="M 1230 380 L 1230 420" class="arrow"/>
+
+  <!-- Labels on decision paths -->
+  <text x="1090" y="115" class="label">Backtest</text>
+  <text x="1120" y="210" class="label">Live</text>
+  <text x="1090" y="305" class="label">Research</text>
+</svg>

data/docs/assets/images/strategy-flow.svg

@@ -0,0 +1,78 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 650" width="800" height="650">
+  <defs>
+    <style>
+      .box { stroke: #ffffff; stroke-width: 3; }
+      .text { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 16px; font-weight: 600; text-anchor: middle; }
+      .arrow { stroke: #ffffff; stroke-width: 2.5; fill: none; marker-end: url(#arrowhead); }
+      .diamond { stroke: #ffffff; stroke-width: 3; }
+      .label { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 14px; font-weight: 500; }
+    </style>
+    <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#ffffff" />
+    </marker>
+  </defs>
+
+  <!-- Price Data -->
+  <rect x="300" y="30" width="200" height="70" rx="8" class="box" fill="#2E86DE"/>
+  <text x="400" y="70" class="text">Price Data</text>
+
+  <!-- Technical Indicators -->
+  <rect x="300" y="150" width="200" height="70" rx="8" class="box" fill="#EE5A6F"/>
+  <text x="400" y="182" class="text">Technical</text>
+  <text x="400" y="202" class="text">Indicators</text>
+
+  <!-- Strategy Vector -->
+  <rect x="300" y="270" width="200" height="70" rx="8" class="box" fill="#10AC84"/>
+  <text x="400" y="302" class="text">Strategy</text>
+  <text x="400" y="322" class="text">Vector</text>
+
+  <!-- Trading Strategy -->
+  <rect x="300" y="390" width="200" height="70" rx="8" class="box" fill="#F368E0"/>
+  <text x="400" y="422" class="text">Trading</text>
+  <text x="400" y="442" class="text">Strategy</text>
+
+  <!-- Signal Diamond -->
+  <g transform="translate(400, 540)">
+    <polygon points="0,-50 70,0 0,50 -70,0" class="diamond" fill="#FD79A8"/>
+    <text x="0" y="5" class="text">Signal</text>
+  </g>
+
+  <!-- Buy Action -->
+  <rect x="50" y="580" width="150" height="60" rx="8" class="box" fill="#26DE81"/>
+  <text x="125" y="615" class="text">Buy Action</text>
+
+  <!-- Sell Action -->
+  <rect x="325" y="580" width="150" height="60" rx="8" class="box" fill="#FC5C65"/>
+  <text x="400" y="615" class="text">Sell Action</text>
+
+  <!-- No Action (Hold) -->
+  <rect x="600" y="580" width="150" height="60" rx="8" class="box" fill="#FED330"/>
+  <text x="675" y="615" class="text">No Action</text>
+
+  <!-- Arrows -->
+  <!-- Price Data to Technical Indicators -->
+  <path d="M 400 100 L 400 150" class="arrow"/>
+
+  <!-- Technical Indicators to Strategy Vector -->
+  <path d="M 400 220 L 400 270" class="arrow"/>
+
+  <!-- Strategy Vector to Trading Strategy -->
+  <path d="M 400 340 L 400 390" class="arrow"/>
+
+  <!-- Trading Strategy to Signal -->
+  <path d="M 400 460 L 400 490" class="arrow"/>
+
+  <!-- Signal to Buy -->
+  <path d="M 330 540 L 200 580" class="arrow"/>
+
+  <!-- Signal to Sell -->
+  <path d="M 400 590 L 400 580" class="arrow"/>
+
+  <!-- Signal to Hold -->
+  <path d="M 470 540 L 600 580" class="arrow"/>
+
+  <!-- Labels on arrows to actions -->
+  <text x="260" y="565" class="label">:buy</text>
+  <text x="400" y="575" class="label">:sell</text>
+  <text x="535" y="565" class="label">:hold</text>
+</svg>

data/docs/assets/images/system-architecture.svg

@@ -0,0 +1,150 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 900" width="1200" height="900">
+  <defs>
+    <style>
+      .box { stroke: #ffffff; stroke-width: 3; }
+      .text { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 15px; font-weight: 600; text-anchor: middle; }
+      .small-text { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 13px; font-weight: 500; text-anchor: middle; }
+      .arrow { stroke: #ffffff; stroke-width: 2.5; fill: none; marker-end: url(#arrowhead); }
+      .layer-box { stroke: #ffffff; stroke-width: 2; fill: none; stroke-dasharray: 5,5; opacity: 0.6; }
+      .layer-title { fill: #ffffff; font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; font-size: 18px; font-weight: 700; }
+      .diamond { stroke: #ffffff; stroke-width: 3; }
+    </style>
+    <marker id="arrowhead" markerWidth="10" markerHeight="10" refX="9" refY="3" orient="auto">
+      <polygon points="0 0, 10 3, 0 6" fill="#ffffff" />
+    </marker>
+  </defs>
+
+  <!-- Data Layer -->
+  <rect x="20" y="20" width="1160" height="140" rx="8" class="layer-box"/>
+  <text x="40" y="45" class="layer-title">Data Layer</text>
+
+  <rect x="80" y="70" width="200" height="60" rx="8" class="box" fill="#2E86DE"/>
+  <text x="180" y="97" class="text">Alpha Vantage</text>
+  <text x="180" y="115" class="text">API</text>
+
+  <rect x="350" y="70" width="200" height="60" rx="8" class="box" fill="#3867D6"/>
+  <text x="450" y="97" class="text">Yahoo</text>
+  <text x="450" y="115" class="text">Finance</text>
+
+  <rect x="620" y="70" width="200" height="60" rx="8" class="box" fill="#4B7BEC"/>
+  <text x="720" y="105" class="text">CSV Files</text>
+
+  <rect x="880" y="70" width="200" height="60" rx="8" class="box" fill="#5352ED"/>
+  <text x="980" y="105" class="text">Raw Data</text>
+
+  <!-- Core Layer -->
+  <rect x="20" y="180" width="1160" height="160" rx="8" class="layer-box"/>
+  <text x="40" y="205" class="layer-title">Core Layer</text>
+
+  <rect x="150" y="230" width="180" height="60" rx="8" class="box" fill="#10AC84"/>
+  <text x="240" y="265" class="text">SQA::Stock</text>
+
+  <rect x="400" y="230" width="200" height="60" rx="8" class="box" fill="#1DD1A1"/>
+  <text x="500" y="265" class="text">SQA::DataFrame</text>
+
+  <rect x="670" y="230" width="240" height="60" rx="8" class="box" fill="#00D2D3"/>
+  <text x="790" y="257" class="text">SQA::DataFrame</text>
+  <text x="790" y="275" class="text">::Data</text>
+
+  <rect x="980" y="230" width="180" height="60" rx="8" class="box" fill="#01A3A4"/>
+  <text x="1070" y="257" class="text">Price/Volume</text>
+  <text x="1070" y="275" class="text">Arrays</text>
+
+  <!-- Analysis Layer -->
+  <rect x="20" y="360" width="1160" height="140" rx="8" class="layer-box"/>
+  <text x="40" y="385" class="layer-title">Analysis Layer</text>
+
+  <rect x="350" y="410" width="240" height="60" rx="8" class="box" fill="#EE5A6F"/>
+  <text x="470" y="437" class="text">SQAI/TAI</text>
+  <text x="470" y="455" class="text">Indicators</text>
+
+  <rect x="680" y="410" width="200" height="60" rx="8" class="box" fill="#FF6B6B"/>
+  <text x="780" y="437" class="text">Technical</text>
+  <text x="780" y="455" class="text">Values</text>
+
+  <!-- Strategy Layer -->
+  <rect x="20" y="520" width="1160" height="220" rx="8" class="layer-box"/>
+  <text x="40" y="545" class="layer-title">Strategy Layer</text>
+
+  <rect x="80" y="570" width="200" height="60" rx="8" class="box" fill="#F368E0"/>
+  <text x="180" y="597" class="text">Strategy</text>
+  <text x="180" y="615" class="text">Vector</text>
+
+  <rect x="360" y="570" width="200" height="60" rx="8" class="box" fill="#E056FD"/>
+  <text x="460" y="597" class="text">Trading</text>
+  <text x="460" y="615" class="text">Strategies</text>
+
+  <!-- Diamond for Signal -->
+  <g transform="translate(720, 600)">
+    <polygon points="0,-40 60,0 0,40 -60,0" class="diamond" fill="#FD79A8"/>
+    <text x="0" y="5" class="text">Signal</text>
+  </g>
+
+  <rect x="860" y="570" width="120" height="60" rx="8" class="box" fill="#26DE81"/>
+  <text x="920" y="605" class="text">Buy</text>
+
+  <rect x="860" y="650" width="120" height="60" rx="8" class="box" fill="#FC5C65"/>
+  <text x="920" y="685" class="text">Sell</text>
+
+  <rect x="1010" y="610" width="120" height="60" rx="8" class="box" fill="#FED330"/>
+  <text x="1070" y="645" class="text">Hold</text>
+
+  <!-- Execution Layer -->
+  <rect x="20" y="760" width="1160" height="120" rx="8" class="layer-box"/>
+  <text x="40" y="785" class="layer-title">Execution Layer</text>
+
+  <rect x="250" y="805" width="180" height="60" rx="8" class="box" fill="#FF9F43"/>
+  <text x="340" y="840" class="text">Portfolio</text>
+
+  <rect x="510" y="805" width="180" height="60" rx="8" class="box" fill="#FFA502"/>
+  <text x="600" y="840" class="text">Backtest</text>
+
+  <rect x="770" y="805" width="200" height="60" rx="8" class="box" fill="#FF6348"/>
+  <text x="870" y="832" class="text">Performance</text>
+  <text x="870" y="850" class="text">Metrics</text>
+
+  <!-- Arrows -->
+  <!-- Data Layer -->
+  <path d="M 180 130 L 980 130 L 980 70" class="arrow"/>
+  <path d="M 450 130 L 980 130" class="arrow" stroke-dasharray="5,5"/>
+  <path d="M 720 130 L 980 130" class="arrow" stroke-dasharray="5,5"/>
+
+  <!-- To Core Layer -->
+  <path d="M 980 130 L 980 180 L 240 180 L 240 230" class="arrow"/>
+
+  <!-- Core Layer connections -->
+  <path d="M 330 260 L 400 260" class="arrow"/>
+  <path d="M 600 260 L 670 260" class="arrow"/>
+  <path d="M 910 260 L 980 260" class="arrow"/>
+
+  <!-- To Analysis Layer -->
+  <path d="M 1070 290 L 1070 340 L 470 340 L 470 410" class="arrow"/>
+
+  <!-- Analysis Layer -->
+  <path d="M 590 440 L 680 440" class="arrow"/>
+
+  <!-- To Strategy Layer -->
+  <path d="M 780 470 L 780 500 L 180 500 L 180 570" class="arrow"/>
+
+  <!-- Strategy Layer -->
+  <path d="M 280 600 L 360 600" class="arrow"/>
+  <path d="M 560 600 L 660 600" class="arrow"/>
+  <path d="M 780 600 L 860 600" class="arrow"/>
+  <path d="M 760 640 L 860 680" class="arrow"/>
+  <path d="M 780 600 L 860 600 L 1010 640" class="arrow"/>
+
+  <!-- To Execution Layer -->
+  <path d="M 460 630 L 460 760 L 340 760 L 340 805" class="arrow"/>
+
+  <!-- Execution Layer -->
+  <path d="M 430 835 L 510 835" class="arrow"/>
+  <path d="M 690 835 L 770 835" class="arrow"/>
+
+  <!-- Labels -->
+  <text x="510" y="125" class="small-text">Fetch</text>
+  <text x="665" y="125" class="small-text">Scrape</text>
+  <text x="815" y="125" class="small-text">Import</text>
+  <text x="345" y="255" class="small-text">Contains</text>
+  <text x="635" y="255" class="small-text">Metadata</text>
+  <text x="525" y="435" class="small-text">Calculate</text>
+</svg>

data/docs/concepts/index.md

@@ -4,29 +4,259 @@ Understanding the fundamental building blocks of SQA.
 
 ## Overview
 
-SQA is built around several key concepts that work together to provide a comprehensive stock analysis framework:
+SQA is built around several key concepts that work together to provide a comprehensive stock analysis framework. This page explains the architecture and how all the pieces fit together.
 
-- **Stock Objects** - Represent individual stocks with historical data
-- **DataFrames** - High-performance time series data structures
-- **Technical Indicators** - Mathematical calculations on price/volume data
-- **Trading Strategies** - Rules for generating buy/sell/hold signals
-- **Portfolio Management** - Track positions and calculate P&L
-- **Backtesting** - Simulate strategies on historical data
+## System Architecture
 
-## Architecture Diagram
+![System Architecture](../assets/images/system-architecture.svg)
 
-```mermaid
-graph TB
-    A[Data Source] -->|Fetch| B[Stock Object]
-    B -->|Contains| C[DataFrame]
-    C -->|Calculate| D[Technical Indicators]
-    D -->|Feed| E[Trading Strategies]
-    E -->|Generate| F[Trading Signals]
-    F -->|Execute| G[Portfolio]
-    G -->|Track| H[Trades & P/L]
+## Key Components
+
+### 1. Stock Object (`SQA::Stock`)
+
+The primary domain object representing a stock with all its associated data.
+
+**Responsibilities:**
+- Load and cache historical price data
+- Fetch company overview information
+- Manage data persistence (JSON metadata + CSV prices)
+- Provide access to DataFrame for analysis
+
+**Example:**
+```ruby
+stock = SQA::Stock.new(ticker: 'AAPL')
+
+# Access data
+stock.ticker      # => "aapl"
+stock.name        # => "Apple Inc"
+stock.exchange    # => "NASDAQ"
+stock.df          # => SQA::DataFrame with price/volume
+stock.overview    # => Hash with company details
+```
+
+### 2. DataFrame (`SQA::DataFrame`)
+
+High-performance wrapper around Polars for time series data manipulation.
+
+**Key Features:**
+- Rust-backed Polars engine (30x faster than pure Ruby)
+- Columnar operations for efficiency
+- CSV/JSON import/export
+- Method delegation to Polars
+
+**Standard Columns:**
+| Column | Description |
+|--------|-------------|
+| `timestamp` | Date of trading day |
+| `open_price` | Opening price |
+| `high_price` | Highest price |
+| `low_price` | Lowest price |
+| `close_price` | Closing price |
+| `adj_close_price` | Split/dividend adjusted price |
+| `volume` | Trading volume |
+
+**Example:**
+```ruby
+df = stock.df
+
+# Column operations
+prices = df["adj_close_price"].to_a
+volumes = df["volume"].to_a
+
+# Statistics (via Polars)
+df.data["close_price"].mean
+df.data["volume"].sum
+```
+
+### 3. Technical Indicators (`SQAI` / `SQA::TAI`)
+
+150+ technical indicators provided by the `sqa-tai` gem, which wraps TA-Lib.
+
+**Categories:**
+- **Overlap Studies**: SMA, EMA, Bollinger Bands
+- **Momentum**: RSI, MACD, Stochastic
+- **Volume**: OBV, AD, ADOSC
+- **Volatility**: ATR, NATR, True Range
+- **Cycle**: Hilbert Transform indicators
+- **Pattern**: Candlestick pattern recognition
+
+**Example:**
+```ruby
+prices = stock.df["adj_close_price"].to_a
+
+# Single-value indicators
+sma = SQAI.sma(prices, period: 20)
+rsi = SQAI.rsi(prices, period: 14)
+
+# Multi-value indicators
+macd, signal, histogram = SQAI.macd(prices)
+upper, middle, lower = SQAI.bbands(prices, period: 20)
+```
+
+### 4. Trading Strategies (`SQA::Strategy`)
+
+Framework for creating and executing trading rules.
+
+**Interface:**
+```ruby
+# All strategies implement this interface
+class SQA::Strategy::MyStrategy
+  def self.trade(vector)
+    # Returns :buy, :sell, or :hold
+  end
+end
+```
+
+**Built-in Strategies:**
+- RSI, MACD, SMA, EMA
+- Bollinger Bands, Stochastic
+- Volume Breakout, Mean Reversion
+- KBS (Knowledge-Based System)
+- Consensus (aggregates multiple strategies)
+
+**Example:**
+```ruby
+require 'ostruct'
+
+vector = OpenStruct.new(
+  rsi: { trend: :over_sold, value: 28 },
+  prices: prices
+)
+
+signal = SQA::Strategy::RSI.trade(vector)
+# => :buy
+```
+
+### 5. Portfolio (`SQA::Portfolio`)
+
+Track positions, calculate P&L, and manage trades.
+
+**Features:**
+- Position tracking (shares per ticker)
+- Commission handling
+- Realized/unrealized P&L
+- Trade history
+
+**Example:**
+```ruby
+portfolio = SQA::Portfolio.new(initial_cash: 10_000, commission: 1.0)
+portfolio.buy('AAPL', shares: 10, price: 150.0)
+portfolio.sell('AAPL', shares: 5, price: 160.0)
+
+portfolio.cash        # Remaining cash
+portfolio.positions   # Current holdings
+portfolio.trades      # Trade history
+```
+
+### 6. Backtesting (`SQA::Backtest`)
+
+Simulate strategies on historical data.
+
+**Metrics Generated:**
+- Total return, annualized return
+- Sharpe ratio, Sortino ratio
+- Maximum drawdown
+- Win rate, profit factor
+- Number of trades
+
+**Example:**
+```ruby
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::RSI,
+  initial_cash: 10_000
+)
+
+results = backtest.run
+puts "Return: #{results.total_return}%"
+puts "Sharpe: #{results.sharpe_ratio}"
+```
+
+## Data Flow
+
+Understanding how data flows through SQA:
+
+![Data Flow](../assets/images/data-flow.svg)
+
+## Data Ordering Convention
+
+**Critical**: TA-Lib requires data in **ascending chronological order** (oldest first).
+
+```ruby
+# Correct order
+prices = [100, 102, 105, 103, 108]  # oldest → newest
+#          ^                    ^
+#        index 0            index -1
+
+# Access latest value
+current_price = prices.last  # or prices[-1]
+
+# Calculate indicator
+rsi = SQAI.rsi(prices, period: 14)
+current_rsi = rsi.last  # Most recent RSI value
+```
+
+## Configuration
+
+SQA uses a hierarchical configuration system:
+
+```
+1. Default values (lowest priority)
+2. Environment variables (SQA_* prefix)
+3. Config file (~/.sqa.yml)
+4. Runtime settings (highest priority)
+```
+
+**Key Settings:**
+```yaml
+# ~/.sqa.yml
+data_dir: ~/sqa_data
+log_level: info
+debug: false
+verbose: false
+lazy_update: false
+```
+
+**Environment Variables:**
+```bash
+export AV_API_KEY="your_alpha_vantage_key"
+export SQA_DATA_DIR="~/my_data"
+export SQA_DEBUG=true
+```
+
+## File Storage
+
+SQA stores data in the configured data directory (default: `~/sqa_data`):
+
+```
+~/sqa_data/
+├── aapl.csv              # Price/volume data
+├── aapl.json             # Stock metadata
+├── msft.csv
+├── msft.json
+└── dumbstockapi-*.csv    # Ticker validation data
+```
+
+## Module Structure
 
-    E -->|Test| I[Backtest]
-    I -->|Evaluate| J[Performance Metrics]
+```
+SQA
+├── Stock                 # Primary domain object
+├── DataFrame             # Time series data wrapper
+│   ├── Data              # Stock metadata class
+│   ├── AlphaVantage      # Alpha Vantage adapter
+│   └── YahooFinance      # Yahoo Finance adapter
+├── Strategy              # Strategy framework
+│   ├── RSI               # RSI strategy
+│   ├── MACD              # MACD strategy
+│   ├── BollingerBands    # Bollinger Bands strategy
+│   ├── KBS               # Knowledge-based system
+│   └── ...               # Other strategies
+├── Portfolio             # Position tracking
+├── Backtest              # Historical simulation
+├── Config                # Configuration management
+├── Ticker                # Symbol validation
+└── FPOP                  # Future Period analysis
 ```
 
 ## Learn More
@@ -57,4 +287,47 @@ graph TB
 
     [:octicons-arrow-right-24: Strategies](../strategy.md)
 
+-   :material-briefcase:{ .lg .middle } __Portfolio__
+
+    ---
+
+    Track positions, P&L, and trade history
+
+    [:octicons-arrow-right-24: Portfolio](../advanced/portfolio.md)
+
+-   :material-chart-timeline:{ .lg .middle } __Backtesting__
+
+    ---
+
+    Test strategies on historical data
+
+    [:octicons-arrow-right-24: Backtesting](../advanced/backtesting.md)
+
+-   :material-cog:{ .lg .middle } __Configuration__
+
+    ---
+
+    Set up data directories and API keys
+
+    [:octicons-arrow-right-24: Installation](../getting-started/installation.md)
+
 </div>
+
+## Design Principles
+
+### 1. Plugin Architecture
+Strategies are pluggable modules that follow a common interface. Add new strategies without modifying core code.
+
+### 2. Data Source Abstraction
+Multiple data providers (Alpha Vantage, Yahoo Finance, CSV) share a common interface. Easy to add new sources.
+
+### 3. Performance First
+Polars DataFrame operations are vectorized and Rust-backed. Avoid Ruby loops over data.
+
+### 4. Educational Focus
+Clear documentation, transparent algorithms, and honest risk disclaimers.
+
+### 5. Separation of Concerns
+- Data fetching is separate from analysis
+- Indicators are separate from strategies
+- Strategies are separate from execution