| name | Adding Alphapoly Features |
| description | Guides feature development in the alphapoly codebase following stack conventions (uv, polars, FastAPI+Next.js). Use whenever adding, building, or modifying any feature — including new API endpoints, pipeline steps, UI pages, WebSocket services, or any other backend/frontend work. If the user says "add X", "build X", "implement X", "make X work", "create an endpoint", "wire up", "hook up", or "connect X to Y", use this skill. For quick prototypes, consider alphapoly-experiment instead. |
Adding Alphapoly Features
Key Conventions
- Backend: Python + FastAPI,
uv only (never pip/conda), polars (never pandas)
- Frontend: Next.js App Router, TypeScript
- Default LLM:
xiaomi/mimo-v2-flash:free via OpenRouter
- Run Python from:
backend/ directory
Workflow
- Implement — follow patterns in neighboring files; see Common Touch Points below
- Lint —
make lint auto-fixes backend (ruff) and frontend (prettier + eslint)
- Typecheck —
cd frontend && npm run typecheck (report-only; fix all errors before committing)
- Verify — start
make dev and manually test the feature works (check API responses, UI renders, WebSocket connects)
- Commit —
type: description (feat/fix/refactor/chore)
Common Touch Points
New API endpoint:
- Add router:
backend/server/routers/<name>.py
- Register in:
backend/server/main.py
- Add TS types:
frontend/types/
- For complex logic, add a service in
backend/server/ (follow portfolio_service.py pattern)
New pipeline step:
- Add to:
backend/core/steps/
- Wire into:
backend/core/runner.py
- For LLM/ML model access: use singletons in
backend/core/models.py
New domain feature (trading, wallet, positions):
- Add subdirectory:
backend/core/<domain>/ with manager.py and/or service.py
- Add router:
backend/server/routers/<domain>.py
- Follow existing pattern in
core/positions/, core/wallet/, core/trading/
New UI page:
- Add:
frontend/app/<page>/page.tsx
- Link from:
frontend/components/Sidebar.tsx
- API/tier config:
frontend/config/ (api-config.ts, tier-config.ts)
WebSocket service:
- Backend:
backend/server/routers/ (follow portfolio_prices.py pattern)
- Frontend hook:
frontend/hooks/
- Note:
frontend/server.js proxies /api/* and /ws/* to the backend
