198 lines
12 KiB
Markdown
198 lines
12 KiB
Markdown
|
# 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
|