245 lines
11 KiB
Markdown
245 lines
11 KiB
Markdown
|
# Invest Copilot
|
||
|
|
|
||
|
|
> AI-native stock research and investment copilot. Mobile-first PWA.
|
||
|
|
>
|
||
|
|
> **Status:** Phase 1 Complete — Foundation + Core Features
|
||
|
|
> **Created:** 2025-05-26
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## What Is This
|
||
|
|
|
||
|
|
A single-page application (SPA) that gives retail investors institutional-grade research tools:
|
||
|
|
|
||
|
|
- **Stock research** — prices, fundamentals, SEC filings, institutional ownership, peer comparison
|
||
|
|
- **Watchlists** — create, manage, and apply strategies to lists of stocks/ETFs/index funds
|
||
|
|
- **Sector rotation detection** — monitor ETFs/index funds for market/sector rotation signals
|
||
|
|
- **Strategy builder** — create technical and fundamental strategies, apply to watchlists
|
||
|
|
- **Automated alerts** — agents that watch your watchlists and notify on strategy triggers
|
||
|
|
- **Stock screener** — TradingView-style screening with your custom criteria
|
||
|
|
- **Backtesting** — SMA/RSI signal generation with trade execution and performance metrics
|
||
|
|
- **Real-time streaming** — SSE-based price and alert updates
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────────────────────┐
|
||
|
|
│ Frontend (Next.js) │
|
||
|
|
│ SPA · Mobile-first PWA · Offline support · Push alerts │
|
||
|
|
│ Tailwind CSS · shadcn/ui · TanStack Query · Zustand │
|
||
|
|
└───────────────────────────┬─────────────────────────────────┘
|
||
|
|
│ REST + SSE
|
||
|
|
┌───────────────────────────▼─────────────────────────────────┐
|
||
|
|
│ Backend (FastAPI) │
|
||
|
|
│ API Gateway · Auth (JWT) · Rate Limiting · Real-time │
|
||
|
|
│ Celery workers · Redis broker · Background tasks │
|
||
|
|
└───────────────────────────┬─────────────────────────────────┘
|
||
|
|
│
|
||
|
|
┌───────────────────────────▼─────────────────────────────────┐
|
||
|
|
│ Data Layer │
|
||
|
|
│ PostgreSQL + TimescaleDB (timeseries + relational) │
|
||
|
|
│ Redis (cache + rate limiting) │
|
||
|
|
│ MinIO (file storage: PDFs, transcripts, images) │
|
||
|
|
└─────────────────────────────────────────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## Tech Stack
|
||
|
|
|
||
|
|
| Layer | Technology |
|
||
|
|
|-------|-----------|
|
||
|
|
| Frontend | Next.js 16, React 19, TypeScript |
|
||
|
|
| Styling | Tailwind CSS, shadcn/ui, clsx, tailwind-merge |
|
||
|
|
| State | Zustand (global), TanStack Query (server state) |
|
||
|
|
| Forms | React Hook Form + Zod validation |
|
||
|
|
| Charts | Lightweight Charts (TradingView) |
|
||
|
|
| Backend | FastAPI (Python 3.12+), asyncpg, Pydantic v2 |
|
||
|
|
| Auth | Hand-rolled HS256 JWT, bcrypt password hashing |
|
||
|
|
| Database | PostgreSQL 16 + TimescaleDB (extension) |
|
||
|
|
| Cache | Redis 7 |
|
||
|
|
| Object Storage | MinIO (S3-compatible) |
|
||
|
|
| Task Queue | Celery + Redis broker |
|
||
|
|
| Real-time | Server-sent events (SSE) via sse-starlette |
|
||
|
|
| Container | Docker Compose |
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
invest-copilot/
|
||
|
|
├── AGENT.md # AI agent philosophy & operational rules
|
||
|
|
├── HEART.md # Agent identity & epistemic discipline
|
||
|
|
├── BRAIN.md # Architecture & tech stack mapping
|
||
|
|
├── docker-compose.yml # Full stack orchestration
|
||
|
|
├── init.sql # TimescaleDB initialization script
|
||
|
|
├── .env.example # Environment variable template
|
||
|
|
├── docs/
|
||
|
|
│ ├── data-edge-research.md # Comprehensive data sources & edge analysis
|
||
|
|
│ └── architecture.md # System architecture
|
||
|
|
├── design-systems/
|
||
|
|
│ └── financial/ # Design tokens, components, prototypes
|
||
|
|
├── src/
|
||
|
|
│ ├── backend/
|
||
|
|
│ │ ├── main.py # FastAPI app, lifespan, middleware
|
||
|
|
│ │ ├── config.py # Settings with JWT secret validation
|
||
|
|
│ │ ├── database.py # asyncpg connection pool
|
||
|
|
│ │ ├── cache.py # Redis cache layer
|
||
|
|
│ │ ├── storage.py # MinIO S3 storage
|
||
|
|
│ │ ├── celery_app.py # Celery configuration
|
||
|
|
│ │ ├── seed_data.py # Database seeding script
|
||
|
|
│ │ ├── routers/ # API route handlers (10 modules)
|
||
|
|
│ │ ├── schemas/ # Pydantic v2 request/response models
|
||
|
|
│ │ ├── models/ # SQLAlchemy/asyncpg models
|
||
|
|
│ │ ├── services/ # Business logic (auth, backtest, etc.)
|
||
|
|
│ │ ├── tasks/ # Celery background tasks
|
||
|
|
│ │ ├── Dockerfile
|
||
|
|
│ │ └── requirements.txt
|
||
|
|
│ └── frontend/
|
||
|
|
│ ├── src/
|
||
|
|
│ │ ├── app/ # Next.js App Router pages
|
||
|
|
│ │ ├── components/ # React components
|
||
|
|
│ │ ├── contexts/ # Auth context
|
||
|
|
│ │ ├── hooks/ # Custom React hooks
|
||
|
|
│ │ ├── lib/ # Utils, API client, query client
|
||
|
|
│ │ ├── store/ # Zustand stores
|
||
|
|
│ │ └── types/ # TypeScript type definitions
|
||
|
|
│ ├── Dockerfile
|
||
|
|
│ └── package.json
|
||
|
|
└── README.md
|
||
|
|
```
|
||
|
|
|
||
|
|
## Quick Start
|
||
|
|
|
||
|
|
### Prerequisites
|
||
|
|
|
||
|
|
- Docker & Docker Compose
|
||
|
|
- Node.js 20+ (for local frontend development)
|
||
|
|
- Python 3.12+ (for local backend development)
|
||
|
|
|
||
|
|
### Docker Compose (Recommended)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 1. Clone and configure
|
||
|
|
cd invest-copilot
|
||
|
|
cp .env.example .env
|
||
|
|
# Edit .env with your API keys and secrets
|
||
|
|
|
||
|
|
# 2. Start all services
|
||
|
|
docker compose up -d
|
||
|
|
|
||
|
|
# 3. Seed the database (first time only)
|
||
|
|
docker compose exec backend python seed_data.py
|
||
|
|
|
||
|
|
# 4. Open
|
||
|
|
# Frontend: http://localhost:3000
|
||
|
|
# Backend API docs: http://localhost:8000/docs
|
||
|
|
# MinIO Console: http://localhost:9001
|
||
|
|
```
|
||
|
|
|
||
|
|
### Local Development
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Backend
|
||
|
|
cd src/backend
|
||
|
|
python -m venv .venv
|
||
|
|
source .venv/bin/activate
|
||
|
|
pip install -r requirements.txt
|
||
|
|
# Set environment variables from .env
|
||
|
|
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
||
|
|
|
||
|
|
# Frontend
|
||
|
|
cd src/frontend
|
||
|
|
npm install
|
||
|
|
npm run dev
|
||
|
|
|
||
|
|
# Celery worker (optional, for background tasks)
|
||
|
|
celery -A celery_app worker --loglevel=info --concurrency=4
|
||
|
|
```
|
||
|
|
|
||
|
|
## API Endpoints
|
||
|
|
|
||
|
|
| Method | Path | Description | Auth |
|
||
|
|
|--------|------|-------------|------|
|
||
|
|
| POST | `/api/v1/auth/register` | Register new user | ❌ |
|
||
|
|
| POST | `/api/v1/auth/login` | Login (returns JWT) | ❌ |
|
||
|
|
| GET | `/api/v1/auth/me` | Get current user | ✅ |
|
||
|
|
| POST | `/api/v1/auth/logout` | Logout | ✅ |
|
||
|
|
| GET | `/api/v1/dashboard` | Dashboard summary | ✅ |
|
||
|
|
| GET | `/api/v1/stocks` | List/search stocks | ✅ |
|
||
|
|
| GET | `/api/v1/stocks/{ticker}` | Stock profile | ✅ |
|
||
|
|
| GET | `/api/v1/stocks/{ticker}/prices` | Price history | ✅ |
|
||
|
|
| GET | `/api/v1/stocks/{ticker}/peers` | Peer comparison | ✅ |
|
||
|
|
| GET | `/api/v1/stocks/{ticker}/sentiment` | Sentiment signals | ✅ |
|
||
|
|
| GET | `/api/v1/stocks/{ticker}/filings` | SEC filings | ✅ |
|
||
|
|
| GET | `/api/v1/stocks/{ticker}/insider_trades` | Insider trades | ✅ |
|
||
|
|
| POST | `/api/v1/stocks/search` | Search stocks | ✅ |
|
||
|
|
| GET | `/api/v1/watchlists` | List watchlists | ✅ |
|
||
|
|
| POST | `/api/v1/watchlists` | Create watchlist | ✅ |
|
||
|
|
| GET | `/api/v1/watchlists/{id}` | Watchlist details | ✅ |
|
||
|
|
| POST | `/api/v1/watchlists/{id}/items` | Add item | ✅ |
|
||
|
|
| DELETE | `/api/v1/watchlists/{id}/items/{ticker}` | Remove item | ✅ |
|
||
|
|
| GET | `/api/v1/screeners` | List screeners | ✅ |
|
||
|
|
| POST | `/api/v1/screeners` | Create screener | ✅ |
|
||
|
|
| POST | `/api/v1/screeners/run` | Run screener | ✅ |
|
||
|
|
| GET | `/api/v1/strategies` | List strategies | ✅ |
|
||
|
|
| POST | `/api/v1/strategies` | Create strategy | ✅ |
|
||
|
|
| POST | `/api/v1/strategies/{id}/backtest` | Run backtest | ✅ |
|
||
|
|
| GET | `/api/v1/alerts` | List alerts | ✅ |
|
||
|
|
| POST | `/api/v1/alerts` | Create alert | ✅ |
|
||
|
|
| POST | `/api/v1/alerts/check-all` | Check all alerts | ✅ |
|
||
|
|
| POST | `/api/v1/sync/ticker/{ticker}` | Sync ticker data | ✅ |
|
||
|
|
| POST | `/api/v1/sync/ticker/{ticker}/enrich` | Enrich ticker | ✅ |
|
||
|
|
| GET | `/api/v1/sync/status` | Data source status | ✅ |
|
||
|
|
| POST | `/api/v1/sync/sector-etfs` | Seed sector ETFs | ✅ |
|
||
|
|
| GET | `/api/v1/sectors` | List sectors | ✅ |
|
||
|
|
| GET | `/api/v1/events` | SSE alert stream | ✅ |
|
||
|
|
| GET | `/api/v1/stream/prices` | SSE price stream | ✅ |
|
||
|
|
| GET | `/api/v1/stream/watchlist` | SSE watchlist stream | ✅ |
|
||
|
|
|
||
|
|
## Security
|
||
|
|
|
||
|
|
- **JWT Authentication**: HS256 tokens with configurable secret key (required at startup)
|
||
|
|
- **Rate Limiting**: Sliding window limiter (public: 100/min, auth: 5/min, heavy: 10/min)
|
||
|
|
- **Ownership Verification**: All mutations verify resource ownership via `_require_*_owner` helpers
|
||
|
|
- **SQL Safety**: All queries use parameterized placeholders ($1, $2, ...)
|
||
|
|
- **Password Hashing**: bcrypt with auto-generated salt
|
||
|
|
|
||
|
|
## Phases
|
||
|
|
|
||
|
|
| Phase | Status | Description |
|
||
|
|
|-------|--------|-------------|
|
||
|
|
| **0 — Design** | ✅ Complete | Design system, prototypes, data research |
|
||
|
|
| **1 — Foundation** | ✅ Complete | Database, API scaffold, auth, Docker, rate limiting, JWT validation |
|
||
|
|
| **2 — Data Pipeline** | 🚧 In Progress | API integrations, Celery workers, seed data, backtesting engine |
|
||
|
|
| **3 — Core Features** | ✅ Complete | Stock search, watchlists, strategies, screeners, alerts |
|
||
|
|
| **4 — Strategies & Alerts** | ✅ Complete | Strategy builder, alert engine, backtesting |
|
||
|
|
| **5 — Sector Rotation** | 🚧 In Progress | ETF monitoring, rotation detection |
|
||
|
|
| **6 — Screener** | ✅ Complete | Custom screeners with operator support |
|
||
|
|
| **7 — Polish & PWA** | 📋 Planned | Offline, push notifications, install prompts |
|
||
|
|
|
||
|
|
## Data Sources
|
||
|
|
|
||
|
|
See `docs/data-edge-research.md` for the complete analysis of data sources, APIs, and the "edge" hierarchy.
|
||
|
|
|
||
|
|
### MVP Data (Free Tier)
|
||
|
|
- **Prices/Fundamentals:** yfinance / Finnhub Free
|
||
|
|
- **Macro:** FRED (free, official government)
|
||
|
|
- **SEC Filings:** SEC EDGAR API (free, official)
|
||
|
|
- **Options:** Polygon.io Free tier
|
||
|
|
- **Sentiment:** Alpha Vantage Free
|
||
|
|
|
||
|
|
### Scale Data (Paid)
|
||
|
|
- **Institutional:** Dataroma, InsiderMonkey
|
||
|
|
- **Consumer:** YipitData, Earnest Research
|
||
|
|
- **Supply Chain:** Project44
|
||
|
|
- **Web Traffic:** SimilarWeb
|
||
|
|
|
||
|
|
## Design
|
||
|
|
|
||
|
|
All design tokens, components, and prototypes live in `design-systems/financial/`.
|
||
|
|
The design system follows a dark-first, mobile-first approach with:
|
||
|
|
- OKLch color space for perceptual uniformity
|
||
|
|
- Monospace typography for all numeric data
|
||
|
|
- Progressive disclosure (summary → drill-down)
|
||
|
|
- Color semantics: green=positive, red=negative, blue=accent
|
||
|
|
|
||
|
|
Open the HTML files in a browser to explore the prototypes.
|