Files
Chronos/docs/ARCHITECTURE.md
T
Claude a9e37c95a2 docs: phases 3-8 status, changelog for the desktop workflows, module map of sync, app and UI
STATUS records the finished Library, Archive manager, Import, editor, sync, translation, RTL and
accessibility work and what each gate rests on; what remains is the release test. CHANGELOG lists the
desktop workflows, localization and accessibility, admin changes and fixes. ARCHITECTURE maps the
Sync engine, SequenceTrash, the App areas, Titano.Ui and Titano.Server, the sync data flow, the
server's managed render fallback, and the desktop UI rules (direction, radio groups, logical
children, live regions, failure sentences, dry runs).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
2026-10-11 23:28:24 +00:00

23 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, 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), the analysis/render engine (Processing) and the client sync engine (Sync)
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, SequenceTrash (delete into the archive's hidden trash with a dry run, restore; the folder moves back when the index step fails), job handlers
Processing ProcessingService, SequenceAnalyser, SequenceRender, ProjectStore, RenderNodeClient, job handlers
Sync SyncService (sync table of one server: compare, link by content, settle conflicts, enqueue transfers), SyncRules (status, settings merge and differences, no I/O), SyncLinkStore (sync_links, sync_state), SyncTransfers and SyncJobHandler (resumable, hash-verified uploads and downloads as jobs; downloads commit through the archive ingest), SyncAgent (background comparison, server events, backoff, offline proxies), ProxyCache and RemoteSequence (server sequences opened with proxies), ISyncRemote (the server calls; TitanoSyncRemote over TitanoClient)

2.3 Titano.App areas

Folder Content
Shell MainWindow, ShellViewModel (rail, sections, first run), dialogs, ErrorText (the sentence of an error toast), ScreenCapture (--capture scenes), SectionTemplates.xaml (view model → view)
Sections One XxxView.xaml + XxxViewModel per screen: Welcome, Library, Sequence (editor), Import, Archive, Jobs, Server, Settings, About
Library Filter, facets, pager, timeline, saved views, quick and mass actions, remote cards and thumbnails, thumbnail cache, list export
Editor EditorSession (project, undo/redo, saving, merges), ISequenceSource (LocalSequenceSource, RemoteSequenceSource), tabs (Frames, Exposure, Camera, Motion, Export), PreviewRenderer, ExportPlanner, ExportSync, SavedCopies, SequenceJobs
Import CardPool (inserted cards, remembered cards, folders), camera profiles, plans and choices, destinations (archive, folder, server through ServerImportSink), card actions (verified delete, format, eject)
Archive CurrentArchive, ArchiveTree, figures for the charts, maintenance reports, mass rename and move, delete and trash dialogs (SequenceDeletion, DeletePlans), ArchiveFailures
Server ServerSession, ConnectFlow (trust on first use), SyncHost (sync engine, agent, metered hold, editor connections, Export Sync), sync table, RemoteSequenceApi
Jobs, Settings, About Job list and buffering; settings rows, encoder inventory, language catalog, naming preview; update check and download
Infrastructure AppServices (composition root), AppSettings, AppEnvironment (installed or portable), UiLanguage, LiveRegion, RenderNodeHost, DiagnosticsBundle, ShellActions (BRIEF §8.6), device monitor
DesignTime SampleData: the archive, jobs and server the screenshots and smoke tests run on

2.4 Titano.Ui and Titano.Server

Folder Content
Ui/Themes, Ui/Theming DESIGN tokens (light, dark), typography, control styles, ThemeManager
Ui/Controls TitanoWindow (chrome, language direction), NavRail, JobBar, ToastHost, Field (placeholder, icon, error), Chip, AutoSlider, StatusGlyph, EmptyState, Icon, Bidi (right-to-left rules)
Ui/Visuals DrawingElement (hover readout, item keyboard and activation) and its charts (BarChart, SeriesChart, StackedBar, HeatmapStrip, TimelineBands), Filmstrip, PreviewViewport, CurveEditor, SequenceCard, VirtualizingWrapPanel, SegmentedControl, SplitButton
Server/Api, Server/Events Endpoint groups (XxxEndpoints.Map), API errors, the WebSocket EventHub
Server/Security Accounts, password hashing, tokens, session cookies, login guard, access rules, audit log
Server/Storage, Server/Jobs Archive and processing modules, uploads, render store; JobEngineHost, render node service, monitor and availability
Server/Hosting, Server/Admin/web ServerHost, certificates, discovery beacon, embedded static files, Windows service; the admin panel (ES modules, one per page)

2.5 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; SyncHost while signed in (sync engine and agent, upload and download handlers, metered hold, editors of server sequences); 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 (renders only managed formats and MP4 jobs no render node can take, BRIEF §14.7); 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.6 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 managed formats, and MP4 jobs no render node can take (RenderNodeAvailability); render nodes claim the others (Server/Jobs/RenderNodeService)
UploadCommit, Download Sync/SyncJobHandler (via SyncService.CreateJobHandlers): this PC's uploads to and downloads from its server yes no: an upload completes synchronously on the server
Duplicates, Orphans, Adopt, Move none: done synchronously (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) → managed
              ▼
   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.

Sync (desktop ↔ server, BRIEF §14.5) reuses the same paths: SyncService compares the local index with the server's listing (settings and tags carry version counters), uploads go through the chunked protocol into the server's ArchiveIngest, downloaded originals are verified and committed through the local ArchiveIngest, and proxies land in the ProxyCache. A server sequence opens in the editor as a RemoteSequence through RemoteSequenceSource: settings are saved with the version they were made from, a 409 merges or asks the user, and analyses and renders run as server jobs whose progress comes from the events.

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
A desktop screen Sections/XxxView.xaml + XxxViewModel, its DataTemplate in Shell/SectionTemplates.xaml, the property and rail entry in ShellViewModel, a scene in Shell/ScreenCapture with sample data, a smoke test in Titano.App.Tests/Windows

5. 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.
  • Never name a namespace Archive (it would shadow the entity): the archive code lives in Archiving. Inside Titano.Core never write an unqualified Math.: use System.Math or double.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>/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> or the JobContext.
  • Libraries use ConfigureAwait(false). No async void except WPF event handlers. Heavy work and I/O never run on the UI thread.
  • Logging through Titano.Core.Diagnostics.Log in Core and Data; ILogger on the server. Anything that leaves the machine (diagnostics bundles) passes through SecretScrubber.
  • 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 (ShellActions in 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.

5.1 Desktop UI (WPF)

  • Every string comes from the catalog (Loc.L, {l:Loc}); labels ≤ 3 words, explanations only in tooltips. Every actionable control has a tooltip, and an icon-only one a two-word accessible name: the screen smoke tests check both on every screen.
  • Windows derive from TitanoWindow, which takes the UI language's direction at creation and on every switch; screens never set FlowDirection for the language. Photos, charts, numbers, paths and templates are left-to-right islands on the smallest element holding them; directional icons mirror by themselves (IconData.IsDirectional, overridden per subtree with Bidi.IsDirectional); left-to-right fragments inside a right-to-left sentence go through BidiText.
  • Radio buttons group by their parent panel. GroupName is shared by every window whose visual root is not known yet, so it is used only where the bindings are one-way (chips generated by item templates, the rail).
  • Content a control presents through its template from a dependency property other than Content is made a logical child of the control (AddLogicalChild and LogicalChildren), so it inherits the data context and resolves ElementName and ancestor bindings (PreviewViewport.ToolsContent).
  • Status lines that change are live regions (LiveRegion.Text with AutomationProperties.LiveSetting); inputs without a validating binding show errors with Field.Error; failure toasts set Toast.IsError, which screen readers hear as important. Charts expose their items to automation and take the keyboard only when an item can be activated.
  • Failures reach the user as one sentence chosen by cause (ErrorText, ArchiveFailures, ImportFailures) with one action; the exception text goes to the tooltip and the log only.
  • Destructive actions show their dry run first; irreversible ones ask for a typed confirmation and keep Cancel as the default button. An explicit dry run stops any debounced one still pending.

6. Tests

  • Framework: Titano.Testing. Test classes are public sealed; constructor may take TestContext (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.Tests targets 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 by Titano.Tools fixtures into tests/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 with TITANO_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.yml runs them weekly against PostgreSQL 17.
  • Titano.Tools.Tests covers 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.
  • en is the source (i18n/en/<Area>.resx), it is mandatory (i18n/it/<Area>.it.resx); other languages are machine-translated through i18n missing / i18n import with i18n/GLOSSARY.md and 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 by Loc.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