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

6.1 KiB
Raw Blame History

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