Files
Chronos/docs/ARCHITECTURE.md
T
Claude 83a54fb57b chore: bootstrap repository foundation
Solution layout, build rules with zero-package guard, in-house test
framework, localization runtime, brand mark rasteriser with ICO/PNG
generation, Core contracts (imaging, video, domain model, TIFF reader),
Titano.Tools (make-icon, i18n, xaml-lint, package-guard) and docs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-02 08:59:40 +00:00

89 lines
6.1 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* 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` | Splines (Fritsch–Carlson, Catmull-Rom, Bézier), robust local regression, statistics, solar position |
| `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<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>`.
- 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.<Area>.Tests/<Folder>/<Thing>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/<Area>.resx`), `it` is mandatory (`i18n/it/<Area>.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
```