galaxis-po/CLAUDE.md

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

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