QuantEngineByItz/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

QuantEngine v0.1 — A comprehensive quantitative analysis and data collection system for retirement asset portfolio management.

• Architecture: .NET 9 + C# (web UI + APIs), Python (legacy data collection/analysis)
• Web UI: Blazor WebAssembly (Fluent UI Blazor v5) + ASP.NET Core Web API
• Database: PostgreSQL (Npgsql 8.0), single unified database
• Data Source: KIS Open API (quotations/ranking read-only), with fallbacks
• Key Runtimes: .NET 9, Python 3.9+, Node.js 16+

Current Status (2026-06-29)

• ✅ Python codebase operational (1,140 files)
• ✅ .NET 9 migration in progress (Phase 1: Web UI)
• ✅ Blazor WASM with Fluent UI v5 RC baseline
• ✅ ASP.NET Core API endpoints operational
• ✅ PostgreSQL migration complete

Deployment & Operations

Production Server: Hetzner Cloud 178.104.200.7 (kjh2064@178.104.200.7)

Projects on server:

1. TaxBaik (홈페이지) — Nginx location /taxbaik
2. QuantEngine (데이터 수집/분석) — Nginx location /quantengine

See Temp/DEPLOYMENT_GUIDE.md for deployment procedures.

Quick Deploy (QuantEngine)

ssh kjh2064@178.104.200.7
systemctl status quantengine-api
journalctl -u quantengine-api -f
sudo systemctl restart quantengine-api

Git Repository

Gitea Server (동일 호스트):

• HTTP: http://178.104.200.7/kjh2064/QuantEngineByItz.git
• SSH: git@178.104.200.7:2222/...

UI Design Principles (2026-06-29)

Framework & Design System

• Primary Framework: Fluent UI Blazor v5
• Design System: Microsoft Fluent Design System (WCAG 2.1 AA)
• Deprecation: MudBlazor is deprecated. Migrate all existing pages to Fluent UI v5 progressively.

Component Development Rules

1. All UI Development (New + Refactored):

   • Use Fluent UI Blazor v5 components exclusively
   • Fall back to pure HTML/CSS if Fluent v5 doesn't provide
   • Never introduce MudBlazor components (deprecated)
   • Progressively migrate existing MudBlazor to Fluent v5

2. Loading States (Priority order):

   • <FluentSkeleton> — Default for lists, cards, dashboards, detail pages
   • Pure HTML <div class="skeleton"> — For custom layouts
   • MudProgressCircular / MudProgressLinear — Exception only (existing legacy)
   • Blocking spinners — Avoid

3. Data Rendering Pattern:

   • First render: Skeleton placeholders only
   • On data arrival: Replace skeleton with actual UI
   • Never show blank states while loading

4. Component Mapping (Fluent UI v5):

UI Element	Fluent UI Component	Alternative
Button	<FluentButton>	-
Input field	<FluentTextField>	HTML <input>
Dropdown	<FluentSelect>	HTML <select>
Data grid	<FluentDataGrid>	HTML <table>
Card	<FluentCard>	HTML <div class="card">
Badge/Status	<FluentBadge>	HTML <span>
Layout container	<FluentStack>	HTML <div>
Accordion	<FluentAccordion>	HTML <details>
Navigation	<FluentNavMenu>	HTML <nav>
Loading	<FluentSkeleton>	CSS skeleton animation
Icons	<FluentIcon>	SVG inline

Development Commands

# NPM / Python validation
npm install
npm run ops:validate

# .NET Development (if dotnet/ folder exists)
cd dotnet
dotnet restore
dotnet build
dotnet watch run --project src/DataFeed.Api

API Endpoints

All endpoints prefixed with /api/:

Route	Purpose
GET /state	Full UI state snapshot
GET /tables	Browsable tables list
GET /table-rows	Paginated rows
POST /settings/save	Save settings
POST /account-snapshot/save	Save snapshots
POST /bootstrap	Seed DB from JSON
POST /account-snapshot/import-tsv	Import TSV
POST /autofix	Auto-correct data

Notes for Contributors

• SQL Safety: Whitelist-only table access (enum switch)
• KIS API: Read-only quotations/ranking; no order/trade endpoints
• Blazor WASM: No direct SQLite access; API-only
• Database: PostgreSQL contract maintained during migration
• Release Authority: Python gates (full-gate, prepare-upload-zip) remain authority until .NET fully operational