- New Titano.Tools.Tests program (CI and release run it): the warning annotation escapes workflow-command characters, and a missing fixture fails the command unless --allow-missing is given. - ARCHITECTURE, STATUS, CHANGELOG and README describe the portable update package, resumable and cancellable download, the release ordering, the rebuild gate in the §1.1 shape and the new numbers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
16 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,
how data moves and how it is written. Decisions behind the shapes described here are in docs/DECISIONS.md.
1. Projects
| Project | TFM | Purpose |
|---|---|---|
src/Titano.Core |
net10.0 | Engine shared by every program: metadata, codecs, imaging, analysis, advisor, motion, render, video containers and managed encoders, archive format, naming, import planning, packaging, localization runtime, diagnostics, brand mark |
src/Titano.Core.Windows |
net10.0-windows | WIC decoders and codec inventory, Media Foundation encoders, DXGI adapters, removable devices, DPAPI, shell launcher, window chrome, power (P/Invoke/COM only) |
src/Titano.Data |
net10.0 | IDatabase, SQLite binding, PostgreSQL wire client, migrations, repositories, the job engine, the archive engine (Archiving) and the analysis/render engine (Processing) |
src/Titano.Protocol |
net10.0 | API v1 DTOs, source-generated JSON context, typed TitanoClient with certificate pinning and bandwidth limiting |
src/Titano.Server |
net10.0 (Web SDK) | ASP.NET Core minimal API, auth, uploads, sync, jobs, render nodes, events, embedded admin panel, Windows service host |
src/Titano.Ui |
net10.0-windows (WPF) | Theme (DESIGN tokens), icons, standard and custom controls, visuals (charts, filmstrip, preview, curve editor, virtualizing grid), Loc markup extension, MVVM helpers |
src/Titano.App |
WPF exe Titano.exe |
Desktop client |
src/Titano.Uploader |
WPF exe | Uploader (tray, watch folders, resumable queue) |
src/Titano.Setup |
WPF exe | In-house installer/uninstaller (TPK1 payload) |
src/Titano.Tools |
net10.0 exe | CLI: make-icon, i18n (check, export, missing, import), xaml-lint, package-guard, changelog, pack-installer, selftest, diagnose, fixtures |
tests/Titano.Testing |
net10.0 | In-house test framework ([Test], [Theory]+[Case], [Category], [RequiresEnvironment], [WindowsOnly], [Serial], Assert, TestContext, JUnit) |
tests/Titano.*.Tests |
exe | One test program per area; dotnet run --project tests/X -- --junit out.xml |
Dependencies point one way: Core ← Core.Windows, Data, Protocol ← Server; Ui ← App, Uploader, Setup.
Core, Data, Protocol and Server never reference Windows-only code (Linux CI builds and tests them).
2. Module map
2.1 Titano.Core namespaces
| Folder / namespace | Content |
|---|---|
Imaging (+ Decoders, Geometry, Thumbnails) |
ImageBuffer (planar float, linear light), IImageDecoderProvider, DecoderFactory (decode tiers: native → embedded preview), ManagedDecoderProvider, FrameWindow (read-ahead, memory budget, float32 spill), resampler, thumbnail cache |
Metadata (+ Tiff, Jpeg, Bmff, Raf, Riff, Png, Xmp, MakerNotes) |
Signature sniffing, Exif/GPS/XMP/MakerNotes, ISO-BMFF (HEIF, CR3), MetadataReader, MetadataBuilder (all fallback chains), ExifWriter |
Codecs (Jpeg, Png, Tiff, Dng, Raw, Gif, Apng, Ico) |
Pure managed codecs; native RAW development (DNG, CR2, NEF, ARW, PEF, RAF) |
Analysis (+ Deep) |
Luminance statistics, deflicker, regions, holy grail, white balance, colour temperature, light analysis, streaming deep analysis with checkpoints |
Advice |
Advisor: recommendations with localisable reasons, apply/optimise, sequence presets |
Motion |
FFT, phase correlation, pyramids, optical flow, motion blur, stabiliser, virtual camera, interpolation, stacking |
Math (namespace Titano.Core.Mathematics) |
Splines, LOWESS, statistics, solar position, 3×3 colour matrices |
Project |
ProjectSettings (Auto/manual values), export presets |
Render |
Render plan (timing modes), preparation pass, geometry, RenderPipeline, self-test suite |
Export |
Preset resolution, encoder selection with fallbacks, output naming |
Video (+ Mp4, Avi, Bitstream, Yuv, Managed) |
IVideoEncoderProvider, MP4 muxer and inspector, AVI-MJPEG, NV12/P010, managed encoders (MJPEG-AVI, GIF, APNG, image sequences) |
Archiving |
Archive layout and paths, sidecars (sequence.json, project.json), scanner, index snapshot, leases, thumbnail packs, verify, adopt, rename plans |
Import |
Card scan, session detection, import plan, hash-verified copy, card eraser (re-hash before delete) |
Naming |
Folder/file templates and tokens |
Model |
Domain entities and enums (§5) shared by Data, Server and clients |
Packaging |
TPK1 installer payload writer/reader, staged install transaction |
Diagnostics |
Log, file sink, synthetic sequences, SecretScrubber, DiagnosticsArchive (scrubbed diagnostics zip) |
Localization, IO, Hashing, Branding |
Loc/plural rules, AtomicFile, CRC-32/SHA helpers, brand mark geometry |
2.2 Titano.Data
| Folder | Content |
|---|---|
Sqlite, Postgres |
SQLite P/Invoke binding (winsqlite3 / libsqlite3), in-house PostgreSQL wire protocol v3 client with pool and LISTEN |
Migrations/{sqlite,postgres}/NNNN_name.sql |
Embedded, applied in one transaction at open (MigrationRunner) |
Repositories |
TitanoDatabase facade: archives, sequences, frames, tags, renders, jobs, cards, users, tokens, uploads, render nodes, settings, audit |
Jobs |
JobEngine, IJobHandler, IJobHandlerProvider, JobContext (progress, checkpoints, follow-up jobs) |
Archiving |
ArchiveService (create/adopt/open), ArchiveIndexer (scan, rebuild), ArchiveIngest (uploads and imports), ImportService, ArchiveVerifier, ArchiveImages, ArchiveMaintenance, MassRenamer, job handlers |
Processing |
ProcessingService, SequenceAnalyser, SequenceRender, ProjectStore, RenderNodeClient, job handlers |
2.3 Hosts
| Host | Composition root | What it runs |
|---|---|---|
| Titano (desktop) | App/Infrastructure/AppServices |
SQLite index in %LOCALAPPDATA%\Titano (or .\data when portable); ArchiveService with WIC first, then managed decoders; ProcessingService with Media Foundation, then managed encoders; one JobEngine with the handlers of both; thumbnails; ServerSession; the render node while opted in and signed in; update check and download (About/UpdateCheck, About/UpdateDownload, About/UpdateFlow: the setup, or the portable zip for a portable copy, verified against SHA256SUMS, resumable, cancellable, failing after 60 s without data); diagnostics bundle |
| Titano Server | Server/Hosting/ServerHost.Build |
Options from server.json + TITANO_*; PostgreSQL (or SQLite on Windows); ArchiveModule then ProcessingModule register job handler providers; JobEngineHost (never claims renders); RenderNodeService/RenderNodeMonitor; UploadService; EventHub (WebSocket); embedded admin panel; LAN discovery beacon; Windows service host |
| Titano Uploader | Uploader/App.xaml.cs |
TitanoClient, persisted queue, watch folders; no database |
| Titano Setup | Setup/Program |
TPK1 payload extraction, registry, shortcuts, silent mode, uninstaller |
2.4 Job kinds and their handlers
JobKind |
Handler (Titano.Data) | Desktop | Server |
|---|---|---|---|
Scan, Rebuild |
Archiving/Jobs/ScanJobHandler (via ArchiveService.CreateJobHandlers) |
yes | yes |
Verify |
Archiving/Jobs/VerifyJobHandler |
yes | yes |
Import |
Archiving/Jobs/ImportJobHandler |
yes | yes |
Thumbs, Proxies |
Archiving/Jobs/ImageJobHandler |
yes | yes |
Maintenance |
Archiving/Jobs/MaintenanceJobHandler |
yes | yes |
LightAnalyse, DeepAnalyse |
Processing/Jobs/AnalyseJobHandler (via ProcessingService.CreateJobHandlers) |
yes | yes |
Render |
Processing/Jobs/RenderJobHandler |
yes | no: render nodes claim them (Server/Jobs/RenderNodeService) |
UploadCommit, Duplicates, Orphans, Adopt, Move |
none: done synchronously (upload completion, ArchiveService queries and actions) |
— | — |
A job engine claims only kinds it has handlers for. Light analysis is queued by the engine (JobContext follow-up)
after an import or a scan that indexed something; screens never queue it again.
3. Data flow
card / folder ──► Core.Import (plan, sessions) ──► ImportService ─┐
Uploader / client ──► POST /uploads, chunks ──► UploadService ────┤ hash verified
▼
ArchiveIngest: temp → fsync → rename into originals/,
sidecar (sequence.json, journalled) → index rows
│
┌────────────────────────────────────────────────────┼─────────────────────────┐
▼ ▼ ▼
LightAnalyse (metadata) Thumbs / Proxies (thumbs.pack) events: sequenceChanged
DeepAnalyse (pixels, checkpoints)
│
▼
Advice.Advisor → ProjectSettings (Auto values with reasons) → project.json
│
▼
Render job: RenderPlan → RenderPipeline (FrameWindow, motion, deflicker…) → IVideoEncoderProvider
│ desktop: Media Foundation → managed; server: render node (GPU PC)
▼
output file (temp → rename) + renders row
The sidecars are the truth; the index is derived and can always be rebuilt (ScanMode.Rebuild, using the index
snapshot when fresh). Writers coordinate through lease files, so a desktop and a server may share an archive.
4. Extension points
| To add | Implement / register |
|---|---|
| An image format or decoder | IImageDecoderProvider (managed in Core/Imaging/Decoders or Codecs, WIC in Core.Windows); chained by DecoderFactory |
| A video encoder | IVideoEncoderProvider (Core/Video/Managed, Core.Windows/MediaFoundation); list it in the host's ProcessingOptions.Encoders |
| A background operation | a JobKind, an IJobHandler (in Data/Archiving/Jobs or Data/Processing/Jobs) returned by the service's CreateJobHandlers; the job engine, Jobs screen, admin and API pick it up |
| A server feature | a static XxxEndpoints.Map(api) in Server/Api with .Requires(Permissions…), called from ServerHost.ConfigurePipeline; DTOs in Titano.Protocol with the JSON context |
| A server storage backend | IArchiveIngest, IFrameAssetLocator through the ServerHost.Build registration callback |
| A schema change | Data/Migrations/{sqlite,postgres}/NNNN_topic.sql (never edit an applied one) |
| An advisor rule | Core/Advice with a localised reason key in Advisor |
| A UI string | i18n/en/<Area>.resx + i18n/it/<Area>.it.resx (other languages via i18n missing/import) |
| An admin page | ES module in Server/Admin/web/pages, strings in the Admin area |
| A CLI command | ICommand in Tools/Commands, listed in Tools/Program.cs |
5. 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.
- Never name a namespace
Archive(it would shadow the entity): the archive code lives inArchiving. Inside Titano.Core never write an unqualifiedMath.: useSystem.Mathordouble.Max. - 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>or theJobContext. - Libraries use
ConfigureAwait(false). Noasync voidexcept WPF event handlers. Heavy work and I/O never run on the UI thread. - Logging through
Titano.Core.Diagnostics.Login Core and Data;ILoggeron the server. Anything that leaves the machine (diagnostics bundles) passes throughSecretScrubber. - 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); originals are never modified. - IDs are UUIDv7 (
Guid.CreateVersion7()); timestamps UTC; capture times are camera wall-clock with an optional offset. - The only OS actions the programs perform are those of BRIEF §8.6: open a URL and show a folder or file in Explorer
(
ShellActionsin the App), the format-volume dialog (Core.Windows/Devices). Downloaded updates (the setup, or the portable zip for a portable copy) are shown in Explorer, never started.
6. Tests
- Framework:
Titano.Testing. Test classes arepublic sealed; constructor may takeTestContext(temp directories, cancellation, log).[WindowsOnly]for OS-specific tests,[RequiresEnvironment("TITANO_TEST_PG")]for PostgreSQL integration tests. - Put tests under
tests/Titano.<Area>.Tests/<Folder>/<Thing>Tests.cs, mirroring the source folder. Titano.App.Teststargets net10.0-windows and runs on Windows CI only: keep logic in plain classes.- Fixtures are synthetic and generated in code wherever possible; tiny binary fixtures may go in
tests/fixtures/(< 50 KB each). CC0 RAW samples are fetched byTitano.Tools fixturesintotests/fixtures/external/(not committed); tests depending on them skip when absent and CI shows a warning per missing sample. - Fuzz tests: truncate and corrupt valid inputs at many offsets; assert no exception escapes.
- Performance gates (
tests/Titano.Data.Tests/Perf,[Category("perf")], run only withTITANO_PERF=1): the 500,000-photo library (Library open < 1 s on a new connection pool, filters < 200 ms; the OS cache is warm from building it) and the 100,000-frame rebuild from sidecars (400 sequences of 250 real photos, every column compared, < 120 s), each on SQLite and PostgreSQL..github/workflows/perf.ymlruns them weekly against PostgreSQL 17. Titano.Tools.Testscovers the tools whose output CI relies on (fixtures annotations and exit codes).
7. Localization
- Keys:
Area.Group.Name; area = file name. Areas: About, Admin, Advisor, Archive, Common, Editor, Errors, Export, Import, Jobs, Library, Server, Settings, Setup, Shell, Tooltips, Uploader. enis the source (i18n/en/<Area>.resx),itis mandatory (i18n/it/<Area>.it.resx); other languages are machine-translated throughi18n missing/i18n importwithi18n/GLOSSARY.mdand a per-language glossary.- 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).
8. Build, checks and CI
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
dotnet format whitespace Titano.slnx --verify-no-changes
| Workflow | Trigger | Does |
|---|---|---|
ci.yml |
push to main, pull requests |
Windows + Linux build and tests, guards, i18n, XAML lint, format, fixtures (warnings when missing), screenshots, PostgreSQL 16/17, Docker smoke test |
release.yml |
tag v* (or manual re-publish) |
Tests, self-contained publish, optional signing, installers, portable and server zips, SHA256SUMS, release notes, multi-arch GHCR image, public releases repository update and GitHub release |
docker.yml |
nightly | ghcr.io/<owner>/titano-server:nightly |
perf.yml |
weekly, manual | Performance gates (SQLite, PostgreSQL 17) with timings in the job summary |