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
6.1 KiB
6.1 KiB
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,
sealedby default, nullable on, warnings are errors. No#pragma warning disableexcept 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>/Vector256where it measurably pays, no LINQ. Parallelise per row/tile withParallel.Foronly 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
CancellationTokenand reports progress throughIProgress<T>. - Libraries use
ConfigureAwait(false). Noasync voidexcept WPF event handlers. - Logging through
Titano.Core.Diagnostics.Login Core;ILoggeron 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 arepublic sealed; constructor may takeTestContext(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 byTitano.Tools fixturesintotests/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. enis the source (i18n/en/<Area>.resx),itis 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 byLoc.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