The architecture documentation lives in docs/arch/, one topic per file:
- Overview: module layout, dependency direction, and the runtime flow from input to rendered frame.
- skygate-ui module: presentation objects, QML composition, and the catalog/settings subsystem.
- Catalog collection lifecycle: source identity, atomic activation, related data, persistence, migration, and recovery.
- skygate-core module: core types, the projection subsystem, and time abstractions.
- skygate-ephemeris module: catalog and snapshot models, engine implementations, and the high-precision interface layer.
- Catalog composition: schemas and containers, object identity, merge precedence, composition policies, and constellation data.
- Result semantics: coordinate meaning per engine, failures, supported date ranges, and thread safety.
- Caching and performance: the in-memory caches and screen-space star decimation.
- Concurrency and threading: what runs async and what stays on the UI thread.
- Extension points: how to add projections, catalog sources and schemas, and ephemeris engines.
- Testing: where each test suite lives and what it owns.