# Titano — Architecture and code conventions Companion to `docs/BRIEF.md` (scope, behaviour) and `docs/ui/DESIGN.md` (looks). This file says *where code goes* and *how it is written*. ## 1. Projects | Project | TFM | Purpose | |---|---|---| | `src/Titano.Core` | net10.0 | Engine shared by every program: metadata, codecs, imaging, analysis, motion, render, video containers, archive model, naming, import planning, localization runtime, brand mark | | `src/Titano.Core.Windows` | net10.0-windows | WIC decoder, Media Foundation encoder, DXGI, device APIs, shell helpers (P/Invoke/COM only) | | `src/Titano.Data` | net10.0 | `IDatabase`, SQLite binding (winsqlite3 on Windows, system libsqlite3 elsewhere for tests/dev), PostgreSQL wire client, migrations, repositories | | `src/Titano.Protocol` | net10.0 | API DTOs, source-generated JSON contexts, upload/sync/event schemas | | `src/Titano.Server` | net10.0 (Web SDK) | ASP.NET Core minimal API, auth, jobs, storage, admin web panel (embedded) | | `src/Titano.Ui` | net10.0-windows (WPF) | Theme (DESIGN tokens), icons, custom controls, `Loc` markup extension, MVVM helpers | | `src/Titano.App` | WPF exe `Titano.exe` | Desktop client | | `src/Titano.Uploader` | WPF exe | Uploader | | `src/Titano.Setup` | WPF exe | Installer/uninstaller | | `src/Titano.Tools` | net10.0 exe | CLI: make-icon, i18n, xaml-lint, package-guard, selftest, diagnose, fixtures, changelog | | `tests/Titano.Testing` | net10.0 | In-house test framework (`[Test]`, `[Theory]`+`[Case]`, `Assert`, `TestContext`) | | `tests/Titano.*.Tests` | exe | One test program per area; `dotnet run --project tests/X -- --junit out.xml` | ## 2. Namespaces in Titano.Core | Folder / namespace | Content | |---|---| | `Imaging` | `ImageBuffer` (planar float, linear light), `ImageFileFormat`, `IImageDecoderProvider`, `ImageDecoder`, colour/geometry helpers, `FrameWindow` | | `Metadata` (+ `Metadata.Tiff`, `Metadata.Bmff`, …) | Signature sniffing, TIFF/IFD (`TiffReader`), Exif/GPS/XMP/MakerNotes, ISO-BMFF, RIFF, RAF, PNG chunks, `MetadataReader`, `ExifWriter` | | `Codecs` (`Codecs.Jpeg`, `Codecs.Png`, `Codecs.Tiff`, `Codecs.Dng`, `Codecs.Gif`, `Codecs.Ico`) | Pure managed image codecs | | `Video` | `Mp4Muxer`, box writer, Annex-B/OBU parsing, MP4 inspector, AVI-MJPEG writer, managed encoder provider, encoder contracts | | `Analysis` | Luminance statistics, deflicker, regions, holy grail, white balance, colour temperature, light/deep analysis | | `Motion` | FFT, phase correlation, pyramids, optical flow, motion blur, stabilisation, virtual camera, interpolation, stacking | | `Math` (namespace `Titano.Core.Mathematics`, so it never shadows `System.Math`) | Splines (Fritsch–Carlson, Catmull-Rom, Bézier), robust local regression, statistics, solar position, 3×3 colour matrices | | `Render` | Render plan, pipeline, export presets | | `Advisor` | Recommendation rules with localisable reasons, sequence presets | | `Archive` | Archive layout, sidecars (`sequence.json`, `project.json`), scanner, rebuild, verify, duplicates, orphans, adopt | | `Naming` | Folder/file templates and tokens | | `Import` | Card/folder scan, session detection, import plan, hash-verified copy | | `Model` | Domain entities (§5) shared by Data, Server and clients | | `Localization`, `Diagnostics`, `IO`, `Hashing`, `Branding` | Infrastructure | ## 3. 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. - 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`. - Libraries use `ConfigureAwait(false)`. No `async void` except WPF event handlers. - Logging through `Titano.Core.Diagnostics.Log` in Core; `ILogger` on the server. - 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). - IDs are UUIDv7 (`Guid.CreateVersion7()`); timestamps UTC; capture times are camera wall-clock with an optional offset. ## 4. Tests - Framework: `Titano.Testing`. Test classes are `public sealed`; constructor may take `TestContext` (temp directories, cancellation, log). Use `[WindowsOnly]` for OS-specific tests and `[RequiresEnvironment("TITANO_TEST_PG")]` for PostgreSQL integration tests. - Put tests under `tests/Titano..Tests//Tests.cs`, mirroring the source folder. - Fixtures are synthetic and generated in code wherever possible; tiny binary fixtures may go in `tests/fixtures/` (< 50 KB each). Larger CC0 samples are fetched by `Titano.Tools fixtures` into `tests/fixtures/external/` (git-ignored) and tests depending on them skip when absent. - Fuzz tests: truncate and corrupt valid inputs at many offsets; assert no exception escapes. ## 5. Localization - Keys: `Area.Group.Name`; area = file name. Areas: Common, Shell, Library, Editor, Import, Archive, Jobs, Server, Settings, Tooltips, Errors, Advisor, Admin, Uploader, Setup. - `en` is the source (`i18n/en/.resx`), `it` is mandatory (`i18n/it/.it.resx`). - 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)`. ## 6. Build and checks ``` 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 ```