3.4 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Project Overview
This is "SkyContour" (project/code name: sfzenith), a Flutter application targeting iOS, Android, macOS, Linux, Windows, and web platforms. It is a horizon-profiling tool for astrophotography: the user pans the phone camera around the horizon to record azimuth→altitude points and exports them for N.I.N.A. (.hrz) and Stellarium (360° panorama landscape). The authoritative spec is the designer handoff in docs/ — read docs/README.md first (then SPEC.md, ARCHITECTURE.md, FORMATS.md, design/tokens.json). docs/SPECIFICATION.md tracks project-level decisions, current status and the roadmap. The functional prototype is the pure Rust core (core/), the wasm-bindgen adapter (wasm/src/lib.rs) and the React frontend (wasm/frontend/); the Flutter app is a thin native shell that runs the web build in a WebView. App ID on both platforms: com.sagifer.skycontour (never change it once published); the visible name comes from wasm/frontend/src/lib/app.js (APP_NAME), iOS Info.plist CFBundleDisplayName and Android android:label.
Common Commands
# Run the app
flutter run
# Run tests
flutter test
# Run a single test file
flutter test test/widget_test.dart
# Analyze code (lint)
flutter analyze
# Get dependencies
flutter pub get
# Build the Rust WASM engine (from wasm/)
wasm-pack build --target web
# Run Rust core tests incl. golden tests against docs/examples (from core/)
cargo test
# Build web bundle into assets/web/ for the Flutter shell
./scripts/build_web.sh
# Run the web prototype (from wasm/frontend/)
npm run dev
Architecture
- core/ (
sfzenith-core): pure Rust, no I/O, no web-sys — profile, projection, fov, hrz, stellarium, zip, session. All math and file generation belongs here. - wasm/: thin wasm-bindgen adapter (camera, canvas, orientation glue) + JS-facing wrappers of the core exporters. Profiles cross the boundary as a 360-value Float64Array (index = azimuth degree, measured frame); exporters apply the north offset.
- wasm/frontend/: Vite + React UI —
src/screens/(Sites, Setup, Capture, Review, Export, Settings, Calibrate),src/lib/(wasm loader, store = localStorage + IndexedDB strips, camera/sensors, survey = capture session + cached wasmHorizonSurvey, files = save/share incl. Flutter handlers). Desktop testing: open with?simfor a keyboard-driven fake compass (arrow keys),?skipWelcometo skip the first-run screen. - i18n (
wasm/frontend/src/i18n/): every UI string goes throught('key', params); English (locales/en.js) is the source and fallback; es, ar (RTL), de, hu, pl, fr, it, sk follow the system language, overridable in Settings. Plurals are objects keyed by Intl.PluralRules category. Add a key to all locale files and runnpm run i18n:check(from wasm/frontend/). Native shell strings: tab labels come from the web app; iOS permission prompts live inios/Runner/<lang>.lproj/InfoPlist.strings. Exported files (.hrz, landscape.ini) stay English. - lib/main.dart: Flutter Android shell — serves
assets/web/on localhost:8080 in an InAppWebView, grants camera, saves PNGs to the gallery - test/: Widget tests using
flutter_testpackage - Uses
flutter_lintsfor static analysis (configured inanalysis_options.yaml) - SDK requirement: Dart ^3.11.1