# 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