Files
Chronos/docs/ARCHITECTURE.md
T

6.2 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 (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