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

galaxis-agent (`~/workspace/quant/galaxis-agent/`)

galaxis-po를 자율적으로 개발하는 SWE 에이전트 (별도 Gitea 리포: quant/galaxis-agent).

agent/ — 핵심 모듈: dispatcher, task_queue, cost_guard, task_history, recovery, auto_merge
agent/integrations/ — Discord bot, sandbox backends
agent/tools/ — 에이전트 도구 (gitea_comment, discord_reply)
agent/utils/ — 유틸리티 (gitea_client, discord_client, git_utils)
tests/ — 테스트 (139개, Phase 1-4)
설계 스펙: docs/superpowers/specs/, 구현 플랜: docs/superpowers/plans/

Development Rules

Check docs/plans/ and docs/superpowers/plans/ for relevant design documents before implementing features
All API endpoints go under backend/app/api/ as routers
DB schema changes require an alembic migration — autogenerate 후 반드시 리뷰하고 즉시 alembic upgrade head
Do not modify .env or docker-compose.prod.yml (.env 설정 안내는 허용, 자동 수정은 금지)
Python: snake_case; TypeScript: camelCase
External APIs: pykrx (한국 거래소 데이터, 백테스트/시그널 주력), KIS (실시간 매매), DART (재무제표)
커밋은 논리 단위별로 개별 생성. 커밋 전 관련 테스트 실행 필수
Frontend 변경 후 cd frontend && npx tsc --noEmit 필수

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.

4.4 KiB Raw Permalink Blame History