Files
Chronos/docs/ARCHITECTURE.md
T
Claude 24f5372965 test(tools): fixtures annotations and exit codes; docs for this round
- New Titano.Tools.Tests program (CI and release run it): the warning annotation
  escapes workflow-command characters, and a missing fixture fails the command
  unless --allow-missing is given.
- ARCHITECTURE, STATUS, CHANGELOG and README describe the portable update
  package, resumable and cancellable download, the release ordering, the
  rebuild gate in the §1.1 shape and the new numbers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-03 10:13:58 +00:00

198 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Titano — Architecture and code conventions
Companion to `docs/BRIEF.md` (scope, behaviour) and `docs/ui/DESIGN.md` (looks). This file says *where code goes*,
*how data moves* and *how it is written*. Decisions behind the shapes described here are in `docs/DECISIONS.md`.
## 1. Projects
| Project | TFM | Purpose |
|---|---|---|
| `src/Titano.Core` | net10.0 | Engine shared by every program: metadata, codecs, imaging, analysis, advisor, motion, render, video containers and managed encoders, archive format, naming, import planning, packaging, localization runtime, diagnostics, brand mark |
| `src/Titano.Core.Windows` | net10.0-windows | WIC decoders and codec inventory, Media Foundation encoders, DXGI adapters, removable devices, DPAPI, shell launcher, window chrome, power (P/Invoke/COM only) |
| `src/Titano.Data` | net10.0 | `IDatabase`, SQLite binding, PostgreSQL wire client, migrations, repositories, the job engine, the archive engine (`Archiving`) and the analysis/render engine (`Processing`) |
| `src/Titano.Protocol` | net10.0 | API v1 DTOs, source-generated JSON context, typed `TitanoClient` with certificate pinning and bandwidth limiting |
| `src/Titano.Server` | net10.0 (Web SDK) | ASP.NET Core minimal API, auth, uploads, sync, jobs, render nodes, events, embedded admin panel, Windows service host |
| `src/Titano.Ui` | net10.0-windows (WPF) | Theme (DESIGN tokens), icons, standard and custom controls, visuals (charts, filmstrip, preview, curve editor, virtualizing grid), `Loc` markup extension, MVVM helpers |
| `src/Titano.App` | WPF exe `Titano.exe` | Desktop client |
| `src/Titano.Uploader` | WPF exe | Uploader (tray, watch folders, resumable queue) |
| `src/Titano.Setup` | WPF exe | In-house installer/uninstaller (TPK1 payload) |
| `src/Titano.Tools` | net10.0 exe | CLI: `make-icon`, `i18n` (check, export, missing, import), `xaml-lint`, `package-guard`, `changelog`, `pack-installer`, `selftest`, `diagnose`, `fixtures` |
| `tests/Titano.Testing` | net10.0 | In-house test framework (`[Test]`, `[Theory]`+`[Case]`, `[Category]`, `[RequiresEnvironment]`, `[WindowsOnly]`, `[Serial]`, `Assert`, `TestContext`, JUnit) |
| `tests/Titano.*.Tests` | exe | One test program per area; `dotnet run --project tests/X -- --junit out.xml` |
Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `Server`; `Ui` ← `App`, `Uploader`, `Setup`.
`Core`, `Data`, `Protocol` and `Server` never reference Windows-only code (Linux CI builds and tests them).
## 2. Module map
### 2.1 Titano.Core namespaces
| Folder / namespace | Content |
|---|---|
| `Imaging` (+ `Decoders`, `Geometry`, `Thumbnails`) | `ImageBuffer` (planar float, linear light), `IImageDecoderProvider`, `DecoderFactory` (decode tiers: native → embedded preview), `ManagedDecoderProvider`, `FrameWindow` (read-ahead, memory budget, float32 spill), resampler, thumbnail cache |
| `Metadata` (+ `Tiff`, `Jpeg`, `Bmff`, `Raf`, `Riff`, `Png`, `Xmp`, `MakerNotes`) | Signature sniffing, Exif/GPS/XMP/MakerNotes, ISO-BMFF (HEIF, CR3), `MetadataReader`, `MetadataBuilder` (all fallback chains), `ExifWriter` |
| `Codecs` (`Jpeg`, `Png`, `Tiff`, `Dng`, `Raw`, `Gif`, `Apng`, `Ico`) | Pure managed codecs; native RAW development (DNG, CR2, NEF, ARW, PEF, RAF) |
| `Analysis` (+ `Deep`) | Luminance statistics, deflicker, regions, holy grail, white balance, colour temperature, light analysis, streaming deep analysis with checkpoints |
| `Advice` | `Advisor`: recommendations with localisable reasons, apply/optimise, sequence presets |
| `Motion` | FFT, phase correlation, pyramids, optical flow, motion blur, stabiliser, virtual camera, interpolation, stacking |
| `Math` (namespace `Titano.Core.Mathematics`) | Splines, LOWESS, statistics, solar position, 3×3 colour matrices |
| `Project` | `ProjectSettings` (Auto/manual values), export presets |
| `Render` | Render plan (timing modes), preparation pass, geometry, `RenderPipeline`, self-test suite |
| `Export` | Preset resolution, encoder selection with fallbacks, output naming |
| `Video` (+ `Mp4`, `Avi`, `Bitstream`, `Yuv`, `Managed`) | `IVideoEncoderProvider`, MP4 muxer and inspector, AVI-MJPEG, NV12/P010, managed encoders (MJPEG-AVI, GIF, APNG, image sequences) |
| `Archiving` | Archive layout and paths, sidecars (`sequence.json`, `project.json`), scanner, index snapshot, leases, thumbnail packs, verify, adopt, rename plans |
| `Import` | Card scan, session detection, import plan, hash-verified copy, card eraser (re-hash before delete) |
| `Naming` | Folder/file templates and tokens |
| `Model` | Domain entities and enums (§5) shared by Data, Server and clients |
| `Packaging` | TPK1 installer payload writer/reader, staged install transaction |
| `Diagnostics` | `Log`, file sink, synthetic sequences, `SecretScrubber`, `DiagnosticsArchive` (scrubbed diagnostics zip) |
| `Localization`, `IO`, `Hashing`, `Branding` | `Loc`/plural rules, `AtomicFile`, CRC-32/SHA helpers, brand mark geometry |
### 2.2 Titano.Data
| Folder | Content |
|---|---|
| `Sqlite`, `Postgres` | SQLite P/Invoke binding (winsqlite3 / libsqlite3), in-house PostgreSQL wire protocol v3 client with pool and LISTEN |
| `Migrations/{sqlite,postgres}/NNNN_name.sql` | Embedded, applied in one transaction at open (`MigrationRunner`) |
| `Repositories` | `TitanoDatabase` facade: archives, sequences, frames, tags, renders, jobs, cards, users, tokens, uploads, render nodes, settings, audit |
| `Jobs` | `JobEngine`, `IJobHandler`, `IJobHandlerProvider`, `JobContext` (progress, checkpoints, follow-up jobs) |
| `Archiving` | `ArchiveService` (create/adopt/open), `ArchiveIndexer` (scan, rebuild), `ArchiveIngest` (uploads and imports), `ImportService`, `ArchiveVerifier`, `ArchiveImages`, `ArchiveMaintenance`, `MassRenamer`, job handlers |
| `Processing` | `ProcessingService`, `SequenceAnalyser`, `SequenceRender`, `ProjectStore`, `RenderNodeClient`, job handlers |
### 2.3 Hosts
| Host | Composition root | What it runs |
|---|---|---|
| Titano (desktop) | `App/Infrastructure/AppServices` | SQLite index in `%LOCALAPPDATA%\Titano` (or `.\data` when portable); `ArchiveService` with WIC first, then managed decoders; `ProcessingService` with Media Foundation, then managed encoders; one `JobEngine` with the handlers of both; thumbnails; `ServerSession`; the render node while opted in and signed in; update check and download (`About/UpdateCheck`, `About/UpdateDownload`, `About/UpdateFlow`: the setup, or the portable zip for a portable copy, verified against `SHA256SUMS`, resumable, cancellable, failing after 60 s without data); diagnostics bundle |
| Titano Server | `Server/Hosting/ServerHost.Build` | Options from `server.json` + `TITANO_*`; PostgreSQL (or SQLite on Windows); `ArchiveModule` then `ProcessingModule` register job handler providers; `JobEngineHost` (never claims renders); `RenderNodeService`/`RenderNodeMonitor`; `UploadService`; `EventHub` (WebSocket); embedded admin panel; LAN discovery beacon; Windows service host |
| Titano Uploader | `Uploader/App.xaml.cs` | `TitanoClient`, persisted queue, watch folders; no database |
| Titano Setup | `Setup/Program` | TPK1 payload extraction, registry, shortcuts, silent mode, uninstaller |
### 2.4 Job kinds and their handlers
| `JobKind` | Handler (Titano.Data) | Desktop | Server |
|---|---|---|---|
| `Scan`, `Rebuild` | `Archiving/Jobs/ScanJobHandler` (via `ArchiveService.CreateJobHandlers`) | yes | yes |
| `Verify` | `Archiving/Jobs/VerifyJobHandler` | yes | yes |
| `Import` | `Archiving/Jobs/ImportJobHandler` | yes | yes |
| `Thumbs`, `Proxies` | `Archiving/Jobs/ImageJobHandler` | yes | yes |
| `Maintenance` | `Archiving/Jobs/MaintenanceJobHandler` | yes | yes |
| `LightAnalyse`, `DeepAnalyse` | `Processing/Jobs/AnalyseJobHandler` (via `ProcessingService.CreateJobHandlers`) | yes | yes |
| `Render` | `Processing/Jobs/RenderJobHandler` | yes | no: render nodes claim them (`Server/Jobs/RenderNodeService`) |
| `UploadCommit`, `Duplicates`, `Orphans`, `Adopt`, `Move` | none: done synchronously (upload completion, `ArchiveService` queries and actions) | — | — |
A job engine claims only kinds it has handlers for. Light analysis is queued by the engine (`JobContext` follow-up)
after an import or a scan that indexed something; screens never queue it again.
## 3. Data flow
```
card / folder ──► Core.Import (plan, sessions) ──► ImportService ─┐
Uploader / client ──► POST /uploads, chunks ──► UploadService ────┤ hash verified
▼
ArchiveIngest: temp → fsync → rename into originals/,
sidecar (sequence.json, journalled) → index rows
│
┌────────────────────────────────────────────────────┼─────────────────────────┐
▼ ▼ ▼
LightAnalyse (metadata) Thumbs / Proxies (thumbs.pack) events: sequenceChanged
DeepAnalyse (pixels, checkpoints)
│
▼
Advice.Advisor → ProjectSettings (Auto values with reasons) → project.json
│
▼
Render job: RenderPlan → RenderPipeline (FrameWindow, motion, deflicker…) → IVideoEncoderProvider
│ desktop: Media Foundation → managed; server: render node (GPU PC)
▼
output file (temp → rename) + renders row
```
The sidecars are the truth; the index is derived and can always be rebuilt (`ScanMode.Rebuild`, using the index
snapshot when fresh). Writers coordinate through lease files, so a desktop and a server may share an archive.
## 4. Extension points
| To add | Implement / register |
|---|---|
| An image format or decoder | `IImageDecoderProvider` (managed in `Core/Imaging/Decoders` or `Codecs`, WIC in `Core.Windows`); chained by `DecoderFactory` |
| A video encoder | `IVideoEncoderProvider` (`Core/Video/Managed`, `Core.Windows/MediaFoundation`); list it in the host's `ProcessingOptions.Encoders` |
| A background operation | a `JobKind`, an `IJobHandler` (in `Data/Archiving/Jobs` or `Data/Processing/Jobs`) returned by the service's `CreateJobHandlers`; the job engine, Jobs screen, admin and API pick it up |
| A server feature | a static `XxxEndpoints.Map(api)` in `Server/Api` with `.Requires(Permissions…)`, called from `ServerHost.ConfigurePipeline`; DTOs in `Titano.Protocol` with the JSON context |
| A server storage backend | `IArchiveIngest`, `IFrameAssetLocator` through the `ServerHost.Build` registration callback |
| A schema change | `Data/Migrations/{sqlite,postgres}/NNNN_topic.sql` (never edit an applied one) |
| An advisor rule | `Core/Advice` with a localised reason key in `Advisor` |
| A UI string | `i18n/en/<Area>.resx` + `i18n/it/<Area>.it.resx` (other languages via `i18n missing`/`import`) |
| An admin page | ES module in `Server/Admin/web/pages`, strings in the `Admin` area |
| A CLI command | `ICommand` in `Tools/Commands`, listed in `Tools/Program.cs` |
## 5. Conventions
- File-scoped namespaces, `sealed` by default, nullable on, warnings are errors. No `#pragma warning disable`
except narrowly around interop with a reason.
- No third-party packages, ever. If the BCL lacks it (CRC-32, Adler, JPEG, PNG decode…), write it.
- Never name a namespace `Archive` (it would shadow the entity): the archive code lives in `Archiving`. Inside
Titano.Core never write an unqualified `Math.`: use `System.Math` or `double.Max`.
- Parsers never throw on malformed input: they return partial results plus warnings. Every offset is bounds-checked
against the stream length; recursion and loops are capped.
- Never load a whole RAW to read metadata: windowed reads through `Stream` + `Seek`.
- Hot loops: `Span<T>`, `System.Numerics.Vector<T>`/`Vector256` where it measurably pays, no LINQ. Parallelise per
row/tile with `Parallel.For` only when work per item is large.
- Pixel math in linear light, `float`, Rec.709 primaries. Convert to sRGB/8-bit only at the edges.
- Every long operation takes a `CancellationToken` and reports progress through `IProgress<T>` or the `JobContext`.
- Libraries use `ConfigureAwait(false)`. No `async void` except WPF event handlers. Heavy work and I/O never run on
the UI thread.
- Logging through `Titano.Core.Diagnostics.Log` in Core and Data; `ILogger` on the server. Anything that leaves the
machine (diagnostics bundles) passes through `SecretScrubber`.
- Public types and non-obvious members get a one-line `///` summary. Comments explain *why*, not *what*.
- Disk writes that must survive crashes use `AtomicFile` (temp → fsync → rename); originals are never modified.
- IDs are UUIDv7 (`Guid.CreateVersion7()`); timestamps UTC; capture times are camera wall-clock with an optional
offset.
- The only OS actions the programs perform are those of BRIEF §8.6: open a URL and show a folder or file in Explorer
(`ShellActions` in the App), the format-volume dialog (`Core.Windows/Devices`). Downloaded updates (the setup, or
the portable zip for a portable copy) are shown in Explorer, never started.
## 6. Tests
- Framework: `Titano.Testing`. Test classes are `public sealed`; constructor may take `TestContext` (temp
directories, cancellation, log). `[WindowsOnly]` for OS-specific tests, `[RequiresEnvironment("TITANO_TEST_PG")]`
for PostgreSQL integration tests.
- Put tests under `tests/Titano.<Area>.Tests/<Folder>/<Thing>Tests.cs`, mirroring the source folder.
- `Titano.App.Tests` targets net10.0-windows and runs on Windows CI only: keep logic in plain classes.
- Fixtures are synthetic and generated in code wherever possible; tiny binary fixtures may go in `tests/fixtures/`
(< 50 KB each). CC0 RAW samples are fetched by `Titano.Tools fixtures` into `tests/fixtures/external/` (not
committed); tests depending on them skip when absent and CI shows a warning per missing sample.
- Fuzz tests: truncate and corrupt valid inputs at many offsets; assert no exception escapes.
- Performance gates (`tests/Titano.Data.Tests/Perf`, `[Category("perf")]`, run only with `TITANO_PERF=1`): the
500,000-photo library (Library open < 1 s on a new connection pool, filters < 200 ms; the OS cache is warm from
building it) and the 100,000-frame rebuild from sidecars (400 sequences of 250 real photos, every column compared,
< 120 s), each on SQLite and PostgreSQL. `.github/workflows/perf.yml` runs them weekly against PostgreSQL 17.
- `Titano.Tools.Tests` covers the tools whose output CI relies on (fixtures annotations and exit codes).
## 7. Localization
- Keys: `Area.Group.Name`; area = file name. Areas: About, Admin, Advisor, Archive, Common, Editor, Errors, Export,
Import, Jobs, Library, Server, Settings, Setup, Shell, Tooltips, Uploader.
- `en` is the source (`i18n/en/<Area>.resx`), `it` is mandatory (`i18n/it/<Area>.it.resx`); other languages are
machine-translated through `i18n missing` / `i18n import` with `i18n/GLOSSARY.md` and a per-language glossary.
- Labels ≤ 30 chars, tooltips/errors/advisor reasons ≤ 200 chars (one or two sentences).
- Plurals: `Key.one` / `Key.few` / `Key.many` / `Key.other`, resolved by `Loc.Plural("Key", n)`.
## 8. Build, checks and CI
```
dotnet build Titano.slnx -c Release
dotnet run --project tests/Titano.Core.Tests -c Release -- --junit out/core.xml
dotnet run --project src/Titano.Tools -- package-guard
dotnet run --project src/Titano.Tools -- i18n check
dotnet run --project src/Titano.Tools -- xaml-lint
dotnet format whitespace Titano.slnx --verify-no-changes
```
| Workflow | Trigger | Does |
|---|---|---|
| `ci.yml` | push to `main`, pull requests | Windows + Linux build and tests, guards, i18n, XAML lint, format, fixtures (warnings when missing), screenshots, PostgreSQL 16/17, Docker smoke test |
| `release.yml` | tag `v*` (or manual re-publish) | Tests, self-contained publish, optional signing, installers, portable and server zips, SHA256SUMS, release notes, multi-arch GHCR image, public releases repository update and GitHub release |
| `docker.yml` | nightly | `ghcr.io/<owner>/titano-server:nightly` |
| `perf.yml` | weekly, manual | Performance gates (SQLite, PostgreSQL 17) with timings in the job summary |