87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
Galaxis-Po is a quant portfolio management application for DC pension (퇴직연금) investing. It implements the Kim Jong-bong (김종봉) strategy for backtesting, signal generation, and portfolio management. The strategy logic is defined in `quant.md` — do not modify it without explicit instruction.
|
||
|
|
|
||
|
|
## Tech Stack
|
||
|
|
|
||
|
|
- **Backend:** FastAPI, Python 3.12, SQLAlchemy, PostgreSQL, uv (package manager)
|
||
|
|
- **Frontend:** Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS v4, shadcn/ui (Radix primitives)
|
||
|
|
- **Infrastructure:** Docker Compose, PostgreSQL 18
|
||
|
|
|
||
|
|
## Common Commands
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Backend dev server (from repo root)
|
||
|
|
cd backend && uv run uvicorn app.main:app --reload
|
||
|
|
|
||
|
|
# Frontend dev server
|
||
|
|
cd frontend && npm run dev
|
||
|
|
|
||
|
|
# Run all backend tests
|
||
|
|
cd backend && uv run pytest
|
||
|
|
|
||
|
|
# Run a single test file
|
||
|
|
cd backend && uv run pytest tests/unit/test_kjb_signal.py -v
|
||
|
|
|
||
|
|
# Run e2e tests
|
||
|
|
cd backend && uv run pytest tests/e2e/ -v
|
||
|
|
|
||
|
|
# DB migration
|
||
|
|
cd backend && uv run alembic upgrade head
|
||
|
|
|
||
|
|
# Create new migration
|
||
|
|
cd backend && uv run alembic revision --autogenerate -m "description"
|
||
|
|
|
||
|
|
# Frontend lint
|
||
|
|
cd frontend && npm run lint
|
||
|
|
|
||
|
|
# Frontend type check
|
||
|
|
cd frontend && npx tsc --noEmit
|
||
|
|
|
||
|
|
# Start all services via Docker
|
||
|
|
docker-compose up -d
|
||
|
|
```
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
### Backend (`backend/`)
|
||
|
|
|
||
|
|
- `app/main.py` — FastAPI app with lifespan manager (seeds admin user, starts APScheduler)
|
||
|
|
- `app/api/` — Route handlers (routers): auth, admin, portfolio, strategy, market, backtest, snapshot, data_explorer, signal
|
||
|
|
- `app/models/` — SQLAlchemy ORM models: user, stock, portfolio, signal, backtest
|
||
|
|
- `app/schemas/` — Pydantic request/response schemas
|
||
|
|
- `app/services/` — Business logic layer:
|
||
|
|
- `collectors/` — Market data collectors (pykrx for Korean stock data, DART API for financials)
|
||
|
|
- `strategy/` — Kim Jong-bong strategy implementation (signal generation, factor calculation)
|
||
|
|
- `backtest/` — Backtesting engine
|
||
|
|
- `rebalance.py` — Portfolio rebalancing logic
|
||
|
|
- `price_service.py`, `factor_calculator.py`, `returns_calculator.py` — Quant utilities
|
||
|
|
- `app/core/` — Config (pydantic-settings from `.env`), database (SQLAlchemy), security (JWT/bcrypt)
|
||
|
|
- `jobs/` — APScheduler background jobs: data collection, signal generation, portfolio snapshots
|
||
|
|
- `alembic/` — Database migrations
|
||
|
|
- `tests/` — `unit/` and `e2e/` test directories
|
||
|
|
|
||
|
|
### Frontend (`frontend/`)
|
||
|
|
|
||
|
|
- Next.js App Router at `src/app/` with pages: portfolio, strategy, signals, backtest, admin, login
|
||
|
|
- `src/components/` — UI components organized by domain (portfolio, strategy, charts, layout, ui)
|
||
|
|
- `src/lib/api.ts` — Backend API client
|
||
|
|
- Uses lightweight-charts for financial charts, recharts for other visualizations
|
||
|
|
|
||
|
|
## Development Rules
|
||
|
|
|
||
|
|
1. Check `docs/plans/` for relevant design documents before implementing features
|
||
|
|
2. All API endpoints go under `backend/app/api/` as routers
|
||
|
|
3. DB schema changes require an alembic migration
|
||
|
|
4. Do not modify `.env` or `docker-compose.prod.yml`
|
||
|
|
5. Python: snake_case; TypeScript: camelCase
|
||
|
|
6. External APIs: KIS (Korea Investment & Securities) for market data, DART for financial statements, pykrx for Korean exchange data
|
||
|
|
|
||
|
|
## Environment
|
||
|
|
|
||
|
|
Backend config is loaded via pydantic-settings from environment variables / `.env` file. Key variables: `DATABASE_URL`, `JWT_SECRET`, `KIS_APP_KEY`, `KIS_APP_SECRET`, `KIS_ACCOUNT_NO`, `DART_API_KEY`. See `.env.example` for reference.
|