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

Paper-CAD is a web-based CAD tool for creating 3D building models and converting them to 2D papercraft templates (展開図/unfold diagrams).

• Frontend: TypeScript monorepo with Web Components, Three.js, Cesium 3D Tiles, and WebAssembly CAD kernel
• Backend: FastAPI (Python) with OpenCASCADE for STEP file processing and unfolding

npm install              # Install dependencies (run from workspace root)
npm run dev              # Dev server on http://localhost:8080
npm run build            # Production build
npm run demo             # Production build served locally (for demos)
npm run build:wasm       # Build C++ WebAssembly module
npm test                 # Run Jest tests
npm run testc            # Tests with coverage
npm run format           # Prettier + clang-format

# Run single test file
npm test -- packages/chili-core/test/observer.test.ts

# Deployment (Cloudflare Pages)
npm run deploy:production

conda activate paper-cad
python main.py           # API server on http://localhost:8001
ENV=demo python main.py  # Demo mode

pytest                   # Run all tests
pytest -v tests/citygml/streaming/test_parser.py  # Single test file
pytest -k "test_name"    # Run tests matching pattern

# API docs: http://localhost:8001/docs (Swagger UI)

# Backend
cd backend && conda env create -f environment.yml && conda activate paper-cad

# Frontend
cd frontend && npm install

Build: Rspack (rspack.config.js), env vars in .env.development/.env.demo

C++ Kernel (/frontend/cpp/src): OpenCASCADE operations compiled to WebAssembly

Core Pipeline (core/):

• file_loaders.py → geometry_analyzer.py → unfold_engine.py → layout_manager.py → svg_exporter.py/pdf_exporter.py

API Routes (api/routers/):

• step.py: POST /api/step/unfold, POST /api/step/unfold-pdf
• citygml.py: POST /api/citygml/to-step
• plateau.py: POST /api/plateau/search-by-address

CityGML Service (services/citygml/): Modular 27-module architecture across 7 layers:

• core/ → utils/ → parsers/ → geometry/ → transforms/ → lod/ → pipeline/
• Entry point: pipeline/orchestrator.py::export_step_from_citygml()

Critical CityGML Execution Order:

1. PHASE:0 Coordinate recentering (transforms/recentering.py) - prevents precision loss
2. PHASE:1 XLink index building (utils/xlink_resolver.py) - required before geometry extraction
3. PHASE:2-6 LOD extraction → geometry build → validation
4. PHASE:7 STEP export

1. OpenCASCADE everywhere: Frontend (WebAssembly) + Backend (pythonOCC)
2. LOD fallback: LOD3 → LOD2 → LOD1 priority for maximum detail
3. Conversion methods: solid (default), sew, extrude, auto (fallback chain)

Modifying unfold algorithm: Edit backend/core/unfold_engine.py, test via Swagger UI

Adding UI component: Create in frontend/packages/chili-ui/src/, use CSS modules

Modifying 3D ops: WebAssembly (frontend/cpp/) for client-side, backend for server-side

PLATEAU/Cesium work:

• Backend: services/plateau_fetcher.py, services/citygml/
• Frontend: packages/chili-cesium/src/cesiumBuildingPicker.ts

• Frontend: Cloudflare Pages (npm run deploy)
• Backend: Docker/Podman (docker compose up -d)
• Production: https://paper-cad.soynyuu.com (frontend), https://backend-paper-cad.soynyuu.com (backend)