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)

# 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

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