# Adding Alphapoly Features

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

- Skill: `chainstacklabs/adding-alphapoly-features` (Agent Skill)
- Install (CLI): `npx skillmds@latest add chainstacklabs/adding-alphapoly-features`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chainstacklabs/adding-alphapoly-features/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: chainstacklabs (https://skillmd.com/u/chainstacklabs)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/chainstacklabs/adding-alphapoly-features

---


# 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

1. **Implement** — follow patterns in neighboring files; see Common Touch Points below
2. **Lint** — `make lint` auto-fixes backend (ruff) and frontend (prettier + eslint)
3. **Typecheck** — `cd frontend && npm run typecheck` (report-only; fix all errors before committing)
4. **Verify** — start `make dev` and manually test the feature works (check API responses, UI renders, WebSocket connects)
5. **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