# 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/.resx` + `i18n/it/.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`, `System.Numerics.Vector`/`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` 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..Tests//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/.resx`), `it` is mandatory (`i18n/it/.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//titano-server:nightly` | | `perf.yml` | weekly, manual | Performance gates (SQLite, PostgreSQL 17) with timings in the job summary |