# 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.