Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
89 lines
6.2 KiB
Markdown
89 lines
6.2 KiB
Markdown
# 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<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
|
||
```
|