# Chronos — 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/Chronos.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/Chronos.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/Chronos.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/Chronos.Protocol` | net10.0 | API v1 DTOs, source-generated JSON context, typed `ChronosClient` with certificate pinning and bandwidth limiting | | `src/Chronos.Server` | net10.0 (Web SDK) | ASP.NET Core minimal API, auth, uploads, sync, jobs, render nodes, events, embedded admin panel, Windows service host | | `src/Chronos.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, notification-area icon | | `src/Chronos.App` | WPF exe `Chronos.exe` | Desktop client | | `src/Chronos.Uploader` | WPF exe | Uploader (tray, watch folders, resumable queue) | | `src/Chronos.Setup` | WPF exe | In-house installer/uninstaller (TPK1 payload) | | `src/Chronos.Tools` | net10.0 exe | CLI: `make-icon`, `i18n` (check, export, missing, import), `xaml-lint`, `package-guard`, `changelog`, `pack-installer`, `selftest`, `diagnose`, `fixtures`, `screenshots` (diff, accept), `zip`, `gitea-release`, `postgres-ci`, `pe-check` | | `tests/Chronos.Testing` | net10.0 | In-house test framework (`[Test]`, `[Theory]`+`[Case]`, `[Category]`, `[RequiresEnvironment]`, `[WindowsOnly]`, `[Serial]`, `Assert`, `TestContext`, JUnit) | | `tests/Chronos.*.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 Chronos.Core namespaces | Folder / namespace | Content | |---|---| | `Imaging` (+ `Decoders`, `Geometry`, `Thumbnails`) | `ImageBuffer` (planar float, linear light), `IImageDecoderProvider`, `DecoderFactory` (decode tiers: native → embedded preview; `ImageDecoder.Probe` names a file's tier without decoding it; `DecodeRequest.PreferPreview` takes an adequate RAW preview by choice for analyses and previews, `DecodedImage.ByChoice`), `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 `Chronos.Core.Mathematics`) | Splines, LOWESS, statistics, solar position, 3×3 colour matrices | | `Project` | `ProjectSettings` (Auto/manual values), export presets, `ProjectBundle` (the `.chronos` project file: sequence reference and settings) | | `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`, `StartupCommand` (sign-in entries of the programs, moved or removed by setup), CRC-32/SHA helpers, brand mark geometry | ### 2.2 Chronos.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` | `ChronosDatabase` facade: archives, sequences, frames, tags, renders, jobs, cards, users, tokens, uploads, render nodes, settings, audit; `DatabaseBackups` (daily `VACUUM INTO` copies of an SQLite index kept ×3, restore staged for the next start and carried out before the index opens, so it also recovers one that no longer opens) | | `Jobs` | `JobEngine` (one job at a time; reviews the priority queue and makes a lower running job yield, requeued with its checkpoint), `JobPriorityQueue` (a level per job kind, the claim order, settings round trip), `IJobHandler`, `IJobHandlerProvider`, `JobContext` (progress, checkpoints, follow-up jobs that never interrupt their parent), `JobThroughput`/`JobEta` (rate and bounded time left) | | `Archiving` | `ArchiveService` (create/adopt/open, archive settings written to `archive.json` then the index), `ArchiveIndexer` (scan, rebuild), `ArchiveIngest` (uploads and imports), `ImportService`, `ArchiveVerifier`, `ArchiveImages` (thumbnail and proxy passes, several photos at once through `OrderedWork`, which hands results back in frame order), `FrameTiers` (decode tier, `PreviewOnly`/`Undecodable` flags and preview size of frames, written to sidecar and index by the light analysis, deep analysis, renders and image passes), `GprCompanions` (the JPEG of each GoPro GPR, found in the index when an import kept it in another sequence), `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`, `DeepReports` (a saved deep report while it still describes the frames), `SequenceRender`, `ProjectStore`, `ProjectBundles` (a `.chronos` file for a sequence, and the sequence a file names), `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), `SyncPositions` (the settings' frame positions translated by photo to the frames of the copy they go to), `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; `ChronosSyncRemote` over `ChronosClient`) | ### 2.3 Chronos.App areas | Folder | Content | |---|---| | `Shell` | `MainWindow` (rail and its shortcuts, taskbar progress), `ShellViewModel` (rail, sections, first run), `OsNotifications` (toasts as Windows notifications while the window is minimised or in the background), 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 (the Edit section: the editor, and `SequencePickerView` choosing the sequence in place), Import, Archive, Jobs, Server, Settings (its last page is 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`), the steps of the Edit path (`EditPath`: their order, each step's state, the step of each finding, the memory of the step shown; tabs Analysis, Frames, Exposure, Motion, Camera, Time, Stack, Export), `PreviewRenderer`, `ExportPlanner`, `ExportSync`, `SavedCopies`, `SequenceJobs`, `ProjectFiles` (save and open `.chronos` project files) | | `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, `JobNotices` (which job endings raise a toast; `JobEndings` lets a batch speak once); settings rows, encoder and format inventories, `ProcessingTuning` (Settings › Rendering and Analysis applied to each job: parallelism, memory budget, quality), `InterfacePriority`, language catalog, naming preview; `AboutViewModel` (owned by the shell, not a section: Settings › About, the update notice of Settings › Updates and the update check on start), update check and download | | `Infrastructure` | `AppServices` (composition root), `AppSettings`, `AppEnvironment` (installed or portable), `AppClock` (today's date, frozen by `--capture`), `StartWithWindows` (this copy's sign-in entry), `UiLanguage`, `LiveRegion`, `RenderNodeHost`, `DiagnosticsBundle`, `ShellActions` (BRIEF §8.6), `SingleInstance` (one Chronos per data folder; a later launch hands its file over a named pipe, or waits for a closing one to exit and starts in its place), device monitor | | `DesignTime` | `SampleData`: the archive, jobs and server the screenshots and smoke tests run on, dated from the fixed `SampleData.Now` | ### 2.4 Chronos.Ui and Chronos.Server | Folder | Content | |---|---| | `Ui/Themes`, `Ui/Theming` | DESIGN tokens (light, dark), typography, control styles, `ThemeManager` | | `Ui/Controls` | `ChronosWindow` (chrome, language direction), `NavRail`, `JobBar`, `ToastHost`, `Field` (placeholder, icon, error), `Chip`, `AutoSlider`, `StatusGlyph`, `EmptyState`, `Icon`, `Bidi` (right-to-left rules), `Motion` (animations off for screenshots) | | `Ui/Interop` | DWM calls of the window chrome; `TrayIcon` (`Shell_NotifyIconW`: the Uploader's tray, the client's Windows notifications) | | `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 (start and stop failures in the Application event log); the admin panel (ES modules, one per page) | ### 2.5 Hosts | Host | Composition root | What it runs | |---|---|---| | Chronos (desktop) | `App/Infrastructure/AppServices` | SQLite index in `%LOCALAPPDATA%\Chronos` (or `.\data` when portable, unless the copy is in a OneDrive folder); `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; daily index backups and the restore staged in Settings › Advanced (`DatabaseBackups`) | | Chronos Server | `Server/Hosting/ServerHost.Build` | Options from `server.json` + `CHRONOS_*`; 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; daily backups of an SQLite index (`DatabaseBackupService`) | | Chronos Uploader | `Uploader/App.xaml.cs` | `ChronosClient`, persisted queue, watch folders; no database | | Chronos Setup | `Setup/Program` | TPK1 payload extraction, registry, shortcuts, file types named in setup's language, silent mode, uninstaller; only what starts a program its log or payload lists is changed: Windows services of those programs stopped once the programs have closed, started again (also after a failure) or deleted through the Service Control Manager (an elevated `/SERVICES … /NAMES` step when needed), sign-in entries of those programs moved to the program an upgrade renamed or removed, shared shortcuts handed to the product that keeps the program; the Server only for all users inside Program Files; "Remove my data" limited to the programs no other installed product uses | ### 2.6 Job kinds and their handlers | `JobKind` | Handler (Chronos.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`: a RAW only through the Raw Image Extension, checked per file); 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 `Chronos.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/.resx` + `i18n/it/.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 `Chronos.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 Chronos.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`, `System.Numerics.Vector`/`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` 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 `Chronos.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 `ChronosWindow`, 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`. Fields of a meta line are joined with `Loc.Separator`, never a literal " · ": in a right-to-left language it holds right-to-left marks, so a number after a Latin field keeps to its own field. Fields shown inside a left-to-right island (the frame data over the preview) use `Loc.IslandSeparator`, which holds left-to-right marks instead. Charts draw digits as European ones, like every text block. - The language switches without restart: computed properties re-read through `LocalizedViewModel`, and a view model that keeps texts in objects (chart series and legends, rows, cached sentences) makes them again in `OnLanguageChanged`. - 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: `Chronos.Testing`. Test classes are `public sealed`; constructor may take `TestContext` (temp directories, cancellation, log). `[WindowsOnly]` for OS-specific tests, `[RequiresEnvironment("CHRONOS_TEST_PG")]` for PostgreSQL integration tests. - Classes run in parallel. A test that changes or observes process-wide state (the UI language, unobserved task exceptions, the managed heap) belongs in a `[Serial]` class; the App and Core test programs fail a test outside one that switches the language away from English, after switching it back (`TestContext.Current`). - Put tests under `tests/Chronos..Tests//Tests.cs`, mirroring the source folder. - `Chronos.App.Tests` targets net10.0-windows and runs on Windows only (the CI job `windows` when a Windows runner is registered, otherwise on a Windows PC): 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 `Chronos.Tools fixtures` into `tests/fixtures/external/` (not committed); tests depending on them skip when absent and the CI log shows a warning per missing sample. - Fuzz tests: truncate and corrupt valid inputs at many offsets; assert no exception escapes. - Performance gates (`tests/Chronos.Data.Tests/Perf`, `[Category("perf")]`, run only with `CHRONOS_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. `.gitea/workflows/perf.yml` runs them weekly against PostgreSQL 17. - `Chronos.Tools.Tests` covers the tools whose output CI relies on (fixtures warning lines and exit codes, the screenshot diff, the PostgreSQL preparation, `pe-check`, `zip`, the Gitea release upload) and the test runner's outcomes. - Visual regression: the CI job `windows` (or a run on a Windows PC) compares the `--capture` screenshots with `tests/visual/baselines` (`Chronos.Tools screenshots diff`; its README says how baselines are added). Once any baseline is committed, a screen without one fails too; before that the step warns that it compared nothing. The capture draws the same pixels on any day: the sample's clock is fixed, formats are English and nothing animates. - Media Foundation output plays back (`Chronos.Core.Windows.Tests`): MediaPlayer opens it where Windows Media Player is installed (skipped, with the reason, where it is not) and a source reader decodes its first frame everywhere. - PostgreSQL: CI prepares the service containers with `Chronos.Tools postgres-ci` (MD5, cleartext and trust roles, TLS; all through SQL as the superuser, because Gitea Actions gives no id of the service container to exec into), so every authentication method and TLS mode of BRIEF §6.3 runs; `CHRONOS_TEST_PG_TLS=1` makes a server without TLS fail the TLS tests. ## 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/.resx`), `it` is mandatory (`i18n/it/.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)`; keys that travel as data (analysis findings, advisor reasons) by `Loc.Text(key, args)`, with the count as their first argument. A text with two or more counts reads as labels ("Frames: 300, warnings: 2", "Copied: 40 · failed: 2"). `i18n check` fails on an English text that puts a number before a counted noun without plural forms, or that tallies two or more counts with participles or adjectives ("40 copied · 2 failed"), which agree with the number in other languages. ## 8. Build, checks and CI ``` dotnet build Chronos.slnx -c Release dotnet run --project tests/Chronos.Core.Tests -c Release -- --junit out/core.xml dotnet run --project src/Chronos.Tools -- package-guard dotnet run --project src/Chronos.Tools -- i18n check dotnet run --project src/Chronos.Tools -- xaml-lint dotnet format whitespace Chronos.slnx --verify-no-changes ``` | Workflow | Trigger | Does | |---|---|---| | `ci.yml` | push to `main`, pull requests, manual | Linux build and tests, guards, i18n, XAML lint, format, fixtures (warnings when missing), the Windows programs cross-compiled for win-x64, packed and checked (`pe-check`), PostgreSQL 16/17 (every authentication method, TLS), Docker smoke test, YAML check of the workflows, issue forms and compose file; with a Windows runner (`WINDOWS_RUNNER`): Windows tests, screenshots and their pixel diff, installer test (install, run, upgrade, uninstall) | | `release.yml` | tag `v*` (or manual re-publish) | Tests, self-contained win-x64 publish cross-compiled on Linux, `pe-check`, optional signing (osslsigncode), installers, portable and server zips, SHA256SUMS, release notes, Gitea release (`gitea-release`), then the linux/amd64 image in the Gitea container registry (`:latest` only for the newest stable release); a separate releases repository is updated only when `RELEASES_REPO` names one | | `docker.yml` | nightly, manual | `gitea.encke-hake.ts.net/balbosoft/chronos-server:nightly` from `main` | | `perf.yml` | weekly, manual | Performance gates (SQLite, PostgreSQL 17) with timings at the end of the log | The workflows live in `.gitea/workflows` (scripts in `.gitea/scripts`) and run on Gitea Actions: an act_runner in Docker mode on the Linux server that hosts Gitea (label `ubuntu-latest`, one job at a time). The .NET jobs run in the `mcr.microsoft.com/dotnet/sdk:10.0` container and check out with plain `git` (the image has no Node.js, so no JavaScript actions); no artifacts or caches are used, and builds use `BUILD_CPUS` cores. Gitea shows no job summary and no annotations: `::warning`/`::error` lines appear in the log only. Pushing images needs the repository secret `REGISTRY_TOKEN` (the workflow's own token is refused by the organisation's registry).