# 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](Temp/DEPLOYMENT_GUIDE.md) for deployment procedures.

### Quick Deploy (QuantEngine)

```powershell
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](https://v5.fluentui-blazor.net/)
- **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

```powershell
# 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