invest-copilot/docs/01-architecture.md

Invest Copilot — Architecture

Tech Stack

Frontend (SPA + Mobile-First PWA)

Layer	Choice	Why
Framework	Next.js 15 (App Router)	SSR for SEO, API routes for BFF, mature ecosystem
Language	TypeScript 5	Type safety across all layers
Styling	TailwindCSS + Radix UI	Design system foundation, accessible primitives
State	Zustand	Lightweight, no boilerplate, perfect for PWA
Charts	Lightweight Charts (TradingView)	Professional-grade financial charts
Real-time	Server-Sent Events (SSE)	Push alerts to browser, simpler than WebSockets
PWA	next-pwa	Offline support, installable, service worker
AI/LLM	OpenAI GPT-4o / Claude Sonnet	Context-aware copilot, SEC filing analysis

Backend (Node.js + Python Microservices)

Service	Language	Why
API Gateway / BFF	Node.js + Fastify	TypeScript, fast, handles auth + routing
Data Pipeline	Python 3.12+	yfinance, SEC EDGAR, sentiment analysis, ML
Strategy Engine	Python 3.12+	Backtesting, signal generation, portfolio analytics
Alert Agent	Python + APScheduler	Scheduled monitoring, notification dispatch
Cache	Redis	Session store, rate limiting, hot data cache

Data Layer

Source	Storage	Purpose
Market data (OHLCV)	PostgreSQL + TimescaleDB	Time-series price data, efficient queries
SEC filings	PostgreSQL (JSONB)	Structured filing data, full-text search
Alternative data	PostgreSQL	Sentiment scores, insider trades, institutional data
User data	PostgreSQL	Watchlists, strategies, screeners, preferences
Cache/realtime	Redis	Session state, rate limiting, real-time alerts
File storage	S3-compatible (MinIO)	SEC filing PDFs, backtest reports, exports

Infrastructure

Component	Choice	Why
Container	Docker Compose (dev), K8s (prod)	Dev simplicity, prod scalability
CI/CD	GitHub Actions	Free, mature, integrates with everything
Monitoring	Prometheus + Grafana	Metrics, alerting, dashboards
Logging	Loki (via Docker Compose)	Structured logs, queryable
Domain	Self-hosted	Full control, no vendor lock-in

Architecture Diagram (Text)

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐ │
│  │  Web App │  │  Mobile  │  │  Tablet  │  │  Desktop (PWA)  │ │
│  │  (PWA)   │  │  (PWA)   │  │  (PWA)   │  │   (installable) │ │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬────────┘ │
│       │              │              │                  │         │
│       └──────────────┴──────────────┴──────────────────┘         │
│                            │ HTTPS / SSE                         │
├──────────────────────────────────────────────────────────────────┤
│                     API GATEWAY (Node.js + Fastify)              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐ │
│  │  Auth    │  │  Routing │  │  Rate    │  │  Request        │ │
│  │  (JWT)   │  │          │  │  Limit   │  │  Validation     │ │
│  └──────────┘  └──────────┘  └──────────┘  └─────────────────┘ │
├──────────────────────────────────────────────────────────────────┤
│                     SERVICE LAYER                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────────┐  │
│  │  Stock       │  │  Strategy    │  │  Watchlist & Alert    │  │
│  │  Service     │  │  Engine      │  │  Agent Service        │  │
│  │  (Node.js)   │  │  (Python)    │  │  (Python + APSched)   │  │
│  └──────┬───────┘  └──────┬───────┘  └──────────┬────────────┘  │
│         │                  │                      │               │
│  ┌──────┴──────────────────┴──────────────────────┴──────────┐  │
│  │                     DATA ACCESS LAYER                       │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌───────────┐  │  │
│  │  │PostgreSQL│  │ Timescale│  │  Redis   │  │  MinIO    │  │  │
│  │  │(user)    │  │ (prices) │  │ (cache)  │  │ (files)   │  │  │
│  │  └──────────┘  └──────────┘  └──────────┘  └───────────┘  │  │
│  └───────────────────────────────────────────────────────────┘  │
├──────────────────────────────────────────────────────────────────┤
│                     DATA SOURCE LAYER                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐  │
│  │  Massive │  │ Finnhub  │  │  SEC     │  │  Alternative    │  │
│  │  /       │  │          │  │  EDGAR   │  │  Data Sources   │  │
│  │  Polygon │  │  (free)  │  │          │  │  (Reddit,       │  │
│  └──────────┘  └──────────┘  └──────────┘  │   GDELT,        │  │
│                                            │   yfinance)     │  │
│                                            └─────────────────┘  │
├──────────────────────────────────────────────────────────────────┤
│                     AI / LAYER                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────────┐  │
│  │  SEC     │  │  Sentiment│ │  Copilot │  │  Sector         │  │
│  │  Filing  │  │  Analysis │ │  Chat    │  │  Rotation       │  │
│  │  Parser  │  │  (NLP)    │  │  Agent  │  │  Detection      │  │
│  └──────────┘  └──────────┘  └──────────┘  └─────────────────┘  │
└──────────────────────────────────────────────────────────────────┘

Data Flow

Stock Search & Profile

User searches "AAPL"
  → API Gateway validates request
  → Stock Service checks Redis cache (TTL: 5 min)
  → If miss: fetches from Massive/Polygon API
  → Enriches with:
      - SEC filings (last 4 quarters)
      - Insider trades (last 90 days)
      - Institutional ownership
      - News + sentiment (Finnhub)
      - Peer group relative strength
  → Returns to frontend
  → AI Copilot generates summary analysis

Watchlist Monitoring

User creates watchlist "AI Winners" with 10 stocks
  → Alert Agent subscribes to each ticker
  → Every 5 minutes:
      - Check price vs strategy triggers
      - Scan for new SEC filings (8-K, 4)
      - Check news sentiment shift
      - Check options unusual activity
  → If trigger fires:
      - Generate alert message via AI
      - Push via SSE to frontend
      - Store alert in DB
      - Optional: email/push notification

Sector Rotation Detection

Every 24 hours at 6:00 AM UTC:
  → Fetch OHLCV for 11 sector ETFs
  → Compute: 20-day, 50-day, 200-day momentum
  → Rank sectors by relative strength vs SPY
  → Compare to previous day's ranking
  → If rank change ≥ 3: rotation detected
  → Generate analysis:
      - What sector entered/rotated out
      - Macro context (yield curve, inflation)
      - Recommended ETF allocations
  → Store rotation event
  → Push to users with active sector rotation alerts

Migration Strategy (Design → TDD → DDD)

Phase 1: Design-Driven (Weeks 1-3)

• Use Open Design to generate UI mockups and visual directions
• Build frontend shell with static data
• Define API contracts (OpenAPI/Swagger)
• Set up CI/CD pipeline
• Deliverable: Clickable prototype, API spec, deployed pipeline

Phase 2: Backend Foundation (Weeks 4-6)

• Implement data ingestion pipeline (Python)
• Build PostgreSQL + TimescaleDB schema
• Implement core API (Node.js/Fastify)
• Set up Redis cache layer
• Deliverable: Working data pipeline, REST API with real data

Phase 3: TDD Frontend (Weeks 7-10)

• Implement stock search + profile (with tests)
• Implement watchlist management (with tests)
• Implement charting (with tests)
• Implement strategy engine (with tests)
• Deliverable: Functional SPA with 80%+ test coverage

Phase 4: DDD Domain Layer (Weeks 11-14)

• Define domain models (Stock, Watchlist, Strategy, Screener)
• Implement aggregate roots and bounded contexts
• Implement domain events (RotationDetected, AlertTriggered)
• Implement CQRS for read/write separation
• Deliverable: Clean architecture with DDD primitives

Phase 5: AI Integration (Weeks 15-18)

• SEC filing parser + NLP analysis
• Copilot chat interface
• Sentiment analysis pipeline
• Alternative data fusion
• Deliverable: AI-powered analysis on every stock page

Phase 6: Alert Engine (Weeks 19-22)

• Watchlist monitoring agents
• Strategy trigger evaluation
• SSE notification system
• Email/push notification dispatch
• Deliverable: Real-time intelligent alerts

Phase 7: Polish & Scale (Weeks 23-26)

• Performance optimization
• Load testing
• Security hardening
• UX polish
• Mobile PWA optimization
• Deliverable: Production-ready invest-copilot