Files
Chronos/docs/ARCHITECTURE.md
T
Alby96andClaude Opus 5.5 3ade4b8d6c docs: document phase 5b, the server as a project home
Phase 5b had only module rows and the review's DECISIONS and CHANGELOG lines.
The brief now describes the server home as the code does after the review
fixes: the projects API, projectChanged, the capability, the settings PATCH
under the lease, renders of a project version, the panel's Projects section,
and the desktop's server projects (open, copy, sync, chip, renders, viewers).

DECISIONS gains the phase's own rows; the 5b rows are dated 2026-10-26 like
the other review-2 phases, and three 5a rows are marked partly superseded.
CHANGELOG, STATUS, the request's 5b row and ARCHITECTURE follow the code
(frames stamp, stored reads, the .thumb marker, followed renames, the
editor's sign-in).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 13:19:55 +01:00

339 lines
69 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 and volume free space, 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, `ChronosAddress` (how both clients read a typed server address) |
| `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`, `release-channels`, `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` (`DevelopsRawAt8Bits`: true for WIC's Raw Image Extension, which a conversion's 16-bit targets never read RAWs through), `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` (`ReadsHeaders`: a conversion's probes read JPEG, PNG and TIFF headers and refuse what the decoders would), `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` (proxies, exports and converted photos; exposure program, metering mode, flash and white balance when known) |
| `Codecs` (`Jpeg`, `Png`, `Tiff`, `Dng`, `Raw`, `Gif`, `Apng`, `Ico`, `Icc`) | Pure managed codecs; native RAW development (DNG, CR2, NEF, ARW, PEF, RAF); header reads that refuse what a decode would (`JpegDecoder.ReadDecodableInfo`, `PngDecoder.MaxPixels`, `TiffImageReader.ReadInfo`; the TIFF reader refuses CMYK, CIELab, palette and other samples it does not render); ICC profiles written into JPEG (APP2) and TIFF (tag 34675); `LinearDngWriter` (exports: clipped linear sRGB; `LinearDngOptions.SceneReferred` for a conversion: linear ProPhoto primaries, up to `MaxHeadroomStops` (4) of headroom in BaselineExposure, matrices that read back as written); `Icc` (`IccProfile`: ICC parser and writer, matrix/TRC and gray curves, sRGB told by the numbers (by the name only without colorant tags), `IsSrgbFor` (the values a DNG takes), `WithSrgbCurve` and `GrayAsRgb` (the profiles a conversion makes), colorants that convert nothing dropped, the in-house Adobe RGB (1998)-compatible and Display P3 profiles; `SourceColor`: the colour space a photo's headers record and whether its samples are linear) |
| `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; members a newer Chronos wrote kept in `Extra` and written back; one of a newer settings format read with `FromJson(json, allowNewer: true)`, `IsNewerFormat`: read-only), export presets, `ProjectBundle` (the `.chronos` project file: sequence reference and settings; format 2 adds the `workspace` section of a workspace's working state: project, name, Main, home, base version, media; a file without it is still written as format 1), `ProjectContent` (the portable form of project versions: every frame position parked by photo with `TranslateFramePositions`, placed back on any copy's frames; canonical text, content hash = SHA-256 of its UTF-8 bytes; `Rebind`/`SameChoices` name each parked photo as the frames hold it now, so a photo hashed or converted since is no change of the choices), `FramePhotos` (the photos of one copy's frames; a photo named by an encoding a conversion replaced, or its undo, is found through `PhotoAlias` links) |
| `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 (a sequence's projects: `.chronos/projects/<id>/project.json` and `versions/000001-<id>.json`, deleted ones in `projects/.trash`), sidecars (`sequence.json`, `project.json`), scanner, index snapshot, leases, thumbnail packs, verify, adopt, rename plans (`RenamePlanner`: folder, title and file templates, `RenameTemplates`, the plan's fingerprint, which pins every file rename by its digest and not the frames version; `FileRenames`: a sequence's new file names; `FileRenameJournal`: two-phase renames through temporary names, `.chronos/rename-files.json`, a recovery safe to run again from wherever it stopped, a new name taken meanwhile sending that photo and its companions back together to their old names or a free `_2`, those that took their new names already with them; `FrameCompanions`: the XMP files that follow a photo, one rule for the trash and Reorganize, matched whatever their case and each folder listed once by `FrameCompanions.Index`) |
| `Import` | Card scan, session detection, import plan (photos named through `FrameNaming` with the camera and lens of their session's first photo), hash-verified copy, card eraser (re-hash before delete) |
| `Conversion` | Mass conversion after import (owner review 2, R7): `ConvertOptions` (target JPEG 4:4:4 / TIFF-16 / linear DNG, the archival one, `ConvertMode` Replace or New sequence, JPEG quality and the quality that counts, the converted name: the archive's file template with the frame's `FrameNaming` context in its sequence, as filing names it, `{ext}` the target's), `FrameConverter` (`Decoders`: the conversion's chain, the managed provider first with its header probes, WIC after it, no RAW at 8 bits for a 16-bit target; native-tier decode only; `Treatment`: what Chronos reads never changes, so the colour space is carried (code values), described by a profile made for the values written (`Describe`: float values as sRGB codes, a gray curve as RGB) or refused (a DNG takes sRGB's values only); pixels that are not numbers fail as damaged; in-house encoders, Exif from the sidecar and the original via `ExifWriter`, hashed as made, written atomically, verified: read back, metadata again, decoded by the server's decoders; `ConversionException` and its `ConversionFailure`, `FailureText`: the job log's sentence by cause), `ConvertPlanner` (per sequence the frames converted and skipped with `ConvertSkip`, each file probed with the conversion's decoders whatever tier was recorded, 8 at a time; `TooLarge`: what the target holds and the server's decoders read back, without overflow; a frame another host flagged undecodable asked again where other decoders (WIC) read it; size estimates per pixel; `ConvertSequencePlan.Digest`, the photos converted with their content; `ConvertPlan` with its space and fingerprint) |
| `Naming` | Folder/file templates and tokens (folder levels scans skip escaped with `_`; `ExpandText` for titles; `ExpandFile` shortens a long file name before its `.{ext}`); `FrameNaming` (the naming context and unique file name of a frame, shared by import, upload, Reorganize and conversion: the sequence's camera and lens, the first frame for folders; `UniqueNames`: `_2`, `_3`… in linear time); `TemplateRules` (what every place a template is typed or sent refuses, the archive engine's new or changed templates included: a folder scans skip, a lost extension, names that repeat) |
| `Model` | Domain entities and enums (§5) shared by Data, Server and clients (`SequenceProject`, `ProjectVersion` and `ProjectVersionKinds`: owner review 2, R8) |
| `Packaging` | TPK1 installer payload writer/reader, staged install transaction |
| `Diagnostics` | `Log` (never throws: a line its sink cannot write is dropped), `FileLogSink` with `LogFileOptions` (level, daily or hourly files, numbered parts past a size, pruning by age and by the total size, never the file being written), 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, schedules (`ScheduleRepository`: system rows seeded without overwriting edits and never deleted, the compare-and-set claim of a run), tombstones of removed photos (`FrameRemovalRepository`, `frame_removals`, written from the sidecar's `removed` list), `SequenceRepository.GetStampAsync` (a digest of what a Reorganize plans from in the index) and `GetConvertStampAsync` (with what a conversion plans from: its photos' count, sizes, formats, pixel sizes and the flags that decide), `JobRepository.ListPendingTargetsAsync` (the targets of pending jobs of a kind, also of those created before a time), `RenderRepository.RebaseFolderAsync` (the export paths that follow a moved folder); projects and their versions (`ProjectRepository`, `projects`, `project_versions`: rows derived from the projects' sidecars, a head advanced by compare-and-set, Main's last mirror); `JobRepository.ListPendingAsync` (the queued, running and paused jobs of a kind and target, full rows); `FrameRepository.CountNamedAsync` (hashed frames and a checksum of their hashes, for a home's frames stamp); `DatabaseBackups` (`VACUUM INTO` copies of an SQLite index into `backups` next to it, every copy keeping as many as the backup schedules keep (`KeptAsync`), the newest copy that seeds the `index-backup` schedule (`Newest`, `SystemSchedule.LastDone`), 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; no history purge, the housekeeping schedule's clean-up does it), `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), `ICancelledJobHandler` (a handler's clean-up after a cancel: `JobEngine.CancelAsync` calls it for a paused or failed job no handler runs, and waits first for a paused job's run that has not ended) |
| `Scheduling` | `Scheduler` (one per host: seeds the host's system schedules, claims due runs by compare-and-set, catch-up, clock changes, create/edit/reset/delete/run now as API v1 DTOs), `ScheduleRecurrence` (the in-house `every:`/`daily:`/`weekly:`/`monthly:` form, wall-clock times across DST), `ScheduleActions` (action names, parameters, availability, the archive jobs a run queues), `IScheduleHost` and `SystemSchedule` (what the server and the desktop supply), `ScheduleOutcome`, `ScheduleMapping` (model ↔ DTO) |
| `Housekeeping` | `BackupJobHandler`, `CleanupJobHandler`, `ICleanupStep` with the shared steps (`CleanupSteps`: job history, audit log, trash report that never deletes); hosts add their own steps through `ArchiveServiceOptions.CleanupSteps` |
| `Archiving` | `ArchiveService` (create/adopt/open, archive settings written to `archive.json` then the index, `ArchiveSettings.CheckTemplates` and `TemplateRuleException` holding a template given anew to the template rules; `UnderLeaseAsync`: a write under a sequence's lease with its row read under it; `EditSettingsAsync`: settings an index edit writes, written to `project.json` under the lease first and put back when the index does not take them), `ArchiveIndexer` (scan, rebuild; a sequence found in another folder takes its exports' paths along; a full scan or a rebuild takes the projects' sidecars back too), `ArchiveIngest` (uploads and imports, named through `FrameNaming`; content a conversion replaced is a duplicate of the frame holding its conversion; a restore or a replacement not settled yet refuses the batch), `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` (also a conversion job's staging and journals, by the job's state; those of a job this index does not know go together, by age), `MassRenamer` (mass rename and Reorganize: the dry run reads each sidecar for a file template; each step checked under its leases before anything of it moves (where its sequences are, what is inside and at its new folder, a sidecar of a newer format, the title it was planned from when it changes it or names the folder or files after it), then the folder, with the sequences of the plan an earlier step left as they were inside it (taken along, their title and file names kept), every index row (the frame paths and render paths of the exports inside it, a file or an image-sequence folder, its own unless the export is still at the old place and another sequence's when it moved with it, follow it in one transaction; a sidecar that cannot be read or written then still has its row follow, and fails the step), then the files under the plan's journal in `journal/` (a sequence whose photos changed since, such as one still receiving them, or whose files are found changed or in use or have their new names taken keeps its file names, the renames being pinned by digest, and the step and the plan go on); the journal keeps the tally of the whole plan, and a plan its job held (paused, cancelled or failed) is left to that job, only its half-done file renames completed at an archive open, which completes any other plan an interruption left and tells each sequence changed; the file renames of a step: sidecar, a sequence whose sidecar cannot be read staying as it is with every folder around it, index (`FrameRepository.RenameFilesAsync`) and the sequence's journal), `SequenceFolders` (`Holds`: the folder the index has for a sequence is there and its sidecar names no other sequence; every writer into a sequence's folder asks it), `SequenceTrash` (delete into the archive's hidden trash with a dry run, restore; the folder moves back when the index step fails; lists sequence and photo entries; `SequenceTrash.Empty`: the emptying's dry run, fingerprint and erase, each entry checked against its fingerprint again under its lease, `TrashKept` with its `TrashKeptReason` for each entry kept; `SequenceTrash.Replaced`: where a replaced entry's conversions are, read from the archive's sidecars (in the index's or the entry's folder, in the trash, else by one `SidecarWalk` of the archive per dry run or emptying) through their replaced tombstones, a conversion deleted only on the archive's word (a tombstone, the trash, or an `ErasureRecord` in `trash/.erased/`, written when an emptying erases a deleted sequence a replaced entry still needs), `TrashEntry.ConversionDeleted` in the dry run and its fingerprint, the erase weighed under the entry's and the sequence's leases once the sequence is settled; `BusyAsync`: what running and paused jobs hold, but the job asking, from `JobRepository.ListHoldsAsync`), `FrameTrash` (photos of a sequence into `trash/photos` with a dry run, a journal that undoes an interrupted deletion whose entry stays unlisted until its sidecar is written, tombstones (a photo never hashed is hashed as it goes; one whose original is missing goes without a file or tombstone; a frame that stays and may be a twin is hashed, its hash kept), positions parked and placed back, proxies and thumbnails moved to follow their frames; `FrameTrash.Restore`: restore re-hashes each file and says why each kept photo stayed (`KeptReason`), under a journal of its own into the sequence that another writer settles only under the entry's lease, into a new sequence through the ingest when theirs is gone, each original staged inside its own entry and the record rewritten after each photo filed; a replaced entry swaps back while its converted frames are unchanged (`SwapBackAsync`); `FrameTrash.Replace`: the files of frames swapped in place, same ids and indices, the old files into one `Replaced` entry with their replacements' hashes, a copy of `analysis.json` and the job's id, the incoming files named never onto a file there, tombstones aliasing old content to new, under `.chronos/replace.pending.json` (its phase and the new names: the next writer completes it when the sidecar lists them, else undoes it; `EnsureReplaced`: the writers of a sequence's frames wait for one not settled); `ReplaceMissingAsync`: a frame missing here takes its photo back in another encoding, nothing to the trash; `FollowUps`: the passes a swap cleared), `MassConverter` (conversion's dry run: busy sequences (running and paused jobs, pending conversions), offline and unreadable ones, the space against `ArchiveServiceOptions.FreeSpace` for the archive root and its staging folder; `QueueAsync`: a confirmed plan's job queued under a process lock, its confirmed photos written first into `journal/convert-<job>.photos` (`ConfirmedPhotos`) under the job's id, a second conversion of its sequences refused, `ConversionQueuedException`; the job, a sequence at a time: under its lease, settled, planned again and held to the confirmed photos (`Confirmed`, `Held`), pinned in `journal/convert-<job>.pins` (`PinLog`); stage A converts into `staging/convert-<job>/` with `OrderedWork`, the space watched before each photo, counting every photo still being written (`SpaceWatch`), each staged file appended to `journal/convert-<job>.staged` (`StagedLog`); stage B per sequence, all or nothing: replace through `FrameTrash.ReplaceAsync` (the sequence's folder read again under its lease, as every writer does), or a new sequence through the ingest with the source's tags, rating, notes and project (a retry finishes the copy the journal names; a source another done conversion copied since is `Superseded`); `ConvertJournal` (`convert-<job>.json`: each sequence's outcome and whether its passes were queued); each sequence replaced or made told, and its passes queued, as it completes), 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 |
| `Projects` | `ProjectService` (`ArchiveService.Projects`: the projects of this PC's sequences as a home, under the sequence's lease and only in a folder that holds the sequence (`SequenceFolders.Holds`; otherwise `SequenceFolderMovedException`: reads answer from the index, writes are refused); reads wait 3 s for the lease, then answer from the index; a read-only archive is read without writing (an index-only Main written back once it takes writes): list, create, rename, delete (the folder into `projects/.trash` first, then the deleted record; never Main), history, head (NotFound once deleted), `StoredAsync` (a version file read back and checked), push with fast-forward / idempotent repeat / divergence / hash, portability, strict format and 64 MiB checks; each call first catches up: the sidecars into the index, Main made from the sequence's settings, settings another path wrote appended to Main as an `external` version or, with a push whose mirror was cut short, merged into one `merge` version where they win, a mirror never written over `project.json` settings it has not taken in (`MovedSharedAsync`), records behind the index healed (`HealAsync`, `UpdatedAfter`), projects the archive lost written back (`WriteBackAsync`); a push to Main mirrored into `project.json` and the settings with the settings version check), `ProjectIndexer` (the reconcile, also run by full scans and rebuilds: the projects' trash read before the live folders, so a deletion wins and the live folder's late version files move beside it; a record that cannot be read held back, never taken for a deletion; a lost record written again from the index only once its folder settled (`RecordSettle`, 2 minutes) and no trash folder holds it back (`TrashRecordGrace`, 1 day); a creation cut before its record left as it is; a version file a push left past its record adopted, a stray one moved to `versions/.stray`; `BehindAsync`, one rule for a record behind the index; `SettleMainAsync` and `SwapMainAsync`, one Main from the records, passed in one transaction), `ProjectSidecars` (record and immutable version files, the settings as a JSON string checked against their hash, `MaxVersionBytes` 64 MiB refused before writing), `ProjectMerge` (three-way merge member by member, pending frames merged photo by photo, conflicts, `Replay` of local commits on a moved head; `NewerSettingsException` rather than merge a newer format), `IProjectHome` and `ArchiveProjectHome` (the home a workspace pushes to and pulls from: `HoldsAsync` reads a version back, `FramesStampAsync` says when the frames changed, an offline archive or busy lease is `HomeUnavailableException`), `ServerProjectHome` (phase 5b: a server sequence's `/projects` over `ChronosClient`; a server out of reach, an expired sign-in, a 503 lease, offline archive or `projects_unreadable`, a 409 `folder_in_use` and a server without the projects are `HomeUnavailableException`, a 404 `sequence`/`project`/`version` and a refused name `ProjectException` (a deleted project's head is 404 `project`), a 422 `too_large` the `TooLarge` outcome, other refusals keep their `ChronosApiException`; `HoldsAsync` reads the version back (`?stored=true`), `FramesStampAsync` from `…/frames/stamp`, version pages read on past a page the server ended early, a 413 the `TooLarge` outcome; its sequences name an archive id made from the server's key), `HomePhotos` (a sequence's photos as positions name them, with the encodings its Replaced tombstones join; the server's frames endpoint and render nodes build the same), what each call changed (`ProjectChangeSet` to `ArchiveServiceOptions.ProjectsChanged`, once the lease is let go: projects made, renamed, deleted or with a new head, compared before and after under the lease, and whether Main's head was written into the sequence's settings), `CatchUpAsync` (the catch-up alone, saying why it cannot run), `ProjectWire` (projects, versions, push outcomes and a home's frames to and from API v1 DTOs, for the server and a client of it) |
| `Workspaces` | `WorkspaceStore` (a folder outside the library: `workspace.json` written atomically, one folder per project, no index; a leftover folder holding only stale lease files removed on listing), `WorkspaceProject` (`project.chronos` working state, `media/` with `media.json`, `proxies/<frame id>.jpg` (and `<frame id>-<sha16>.jpg` while a copy replaces one) and `analysis.json`, `versions/` with `.replaced` (versions set aside, pruned by age and count) and `.replaced.since`, `sync.json` for a conflict, a restore or the journal of a replay or a Save both, `exports/`, the lease `.lock.lease`; `UnreadableVersions`), `WorkspaceMedia` (`NamedAsAt`: the media learn the home's hashes and aliases), `WorkspaceSync` (checkout, open under the lease, save, commit, push, pull with replay and merge, the base in `project.chronos` as every write's commit point, `SettleAsync` finishing or undoing a cut push, replay or Save both, conflicts settled by keep mine, take server or save both only as shown, restore, status with Gone, Damaged and `MediaOutdated`, the home's frames read again only when their stamp moved; `FollowNameAsync`: the home's name and Main written into the copy at every pull and at a server's `renamed`), `WorkspaceCopyJobHandler` (`WorkspaceJobs.Copy` and `CopyFactsAsync`, registered by the desktop only: the archive only read, from a folder that holds the sequence; a workspace inside a library refused; the archive's current proxies copied, the others made in the workspace, each hash-verified, resumable from a checkpoint of its frames version and folder, free space checked against its estimate plus 512 MiB; the encodings conversions joined kept in `media.json`; the working state's positions moved by frame where frames stay, by photo where they came or went; a cancelled first copy's media cleared under the project's lease only when no other copy of the project waits or runs, through `ICancelledJobHandler` too; a project whose home is a server, `WorkspaceJobs.CopyFromServer`, phase 5b: downloaded through the desktop's session (`ISyncConnector`), never through this PC's archive, the frames of one frames version with the aliases of the server's conversions, each proxy (else the thumbnail standing in, `WorkspaceFrame.FileKind`) hashed as it arrives and checked on the disk, four at a time, the editor's current file never overwritten, resumable from the same checkpoint, a `<file>.thumb` marker beside a thumbnail standing in until the commit, free space checked against the server's proxy sizes) |
| `Sync` | `SyncService` (sync table of one server: compare, link by content through the aliases, settle conflicts, enqueue transfers), `SyncRules` (status, settings merge and differences, the proxies this PC can send, aliases followed; no I/O), `SyncTombstones` (photos either side removed are not offered back; the replaced tombstones of both sides join the encodings of one photo, union-find, each compared as the smallest SHA-256 among them, a deletion covering them all; immutable once made), `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, and a frame missing here whose photo the server holds in another encoding takes that file through `FrameTrash.ReplaceMissingAsync`; job log lines from the catalog), `SyncAgent` (background comparison, server events, backoff, offline proxies; a server's `projectChanged` passed on as `ProjectChanged`, and null after a lost event stream once the stream is open again and a comparison made after that reached the server: `ISyncRemote.EventsAsync(connected, ct)`), `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, `SequencePickerView` choosing in place a project of the workspace or a sequence of the library, the in-window dialogs of the workspace, and the opening of this PC's sequences as workspace projects: the project opened last, else "Open in workspace", the checkout and the copy job followed until it opens), Import, Archive, Jobs (two tabs, Queue and Scheduled: `SchedulesView` shows `Jobs/SchedulesViewModel`), Server, Settings (its last page is About) |
| `Library` | Filter, facets, pager, timeline, saved views, quick and mass actions (`MassActions`: Reorganize and Convert for the sequences of one archive), remote cards and thumbnails, thumbnail cache, list export |
| `Editor` | `EditorSession` (project, undo/redo, saving, merges through `Data/Projects/ProjectMerge`), `ISequenceSource` (`LocalSequenceSource`, `RemoteSequenceSource`, `WorkspaceSequenceSource`: a workspace project over its media, the working state saved in `project.chronos` under the project's lease and merged photo by photo in the portable form (`Merge`, a setting both sides changed asked through `ProjectConflictException`), `ReadOnlyChanged` for a project of a newer Chronos, an unstored edit kept aside in `versions/.replaced` (`SetAsideAsync`), renders at the home with the portable settings through `IProjectRenders`, naming a version only while none waits to be sent; a server home's analyses and renders are the server's jobs over `WorkspaceServerHome(connect, session)`, which connects again when the sign-in changes, a render naming the version the server holds when the project is in step with it), `ServerJobs` (a server sequence's analyses and renders followed through its events, shared by `RemoteSequenceSource` and a server home's `WorkspaceSequenceSource`), 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: format 2 opens its workspace project, format 1 gives its settings to Main) |
| `Workspace` | Owner review 2, R8: `WorkspaceHost` (the desktop's `WorkspaceStore` and `WorkspaceSync` over Settings › Workspace's folder, this PC's archive or, through `SyncHost.ProjectHome`, the signed-in server as the home (a server it is not signed in to reads as offline; `HomeChanged` from the server's `projectChanged`, texts worded for it by `WorkspaceText.ForHome`); checkout and copy with its size and free space, status, Save version with the sync after it, sync, resolve, restore, history, open, new, rename, delete, the plan and removal of a local copy whose files but the media go to `<workspace>/.trash` (put back whole when a move fails), pruning past Kept versions after `HoldsAsync`, copies a newer Chronos wrote or that cannot be read listed as such and never changed, a folder inside a library refused, `PlanFolderAsync` and `UseFolderAsync`), `WorkspaceFolderChange` (Settings › Workspace › Change… and the refused folder's Choose folder), `ProjectMenuViewModel` (the title's ▾: state chip read again after edits, the menu, Update media; `IWorkspaceUi` is what it asks of the section, `ShowDialogWhenFree` holding a background conflict until the open dialog closes), `WorkspaceDialogs` (Open in workspace with unreadable projects listed disabled, project name, Save version, History, conflict, a format conflict offering only Save both, Remove local copy with its typed confirmations; `WorkspaceDialogs.xaml`), `WorkspaceProjectItem` (a picker row), `WorkspaceText` (states, versions, authors, failures) |
| `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, Reorganize (`ReorganizeDialogViewModel`: folder, file and title templates each with its switch, the dry run, Apply queues the `move` job of that plan; `ReorganizePlans`: each template's check, the plan as rows and a summary; `ReorganizeOffer`: per archive, the templates Settings › Archive's toast offers, joined while that archive's toast is up), Convert (`ConvertDialogViewModel`: format, JPEG quality and a mode chosen at every run, the dry run made once per format and quality, Apply behind the mode's confirmation queues the `convert` job of that plan through `MassConverter.QueueAsync`; `ConvertPlans`: the plan as rows in the mode's words, a summary, the space line, the Replace confirmation that types the number of photos and the New sequence one that counts the photos not copied; `ConvertUndo`: the Undo the Jobs screen's toast offers when Replace conversions end, which restores the `Replaced` trash entries their jobs made, by the job's id), retag, delete and trash dialogs (`SequenceDeletion`, `DeletePlans`, `TrashEmptyPlans`: Empty… behind a dry run and a typed confirmation, every entry whose conversion was deleted named first), `ArchiveFailures` |
| `Server` | `ServerSession`, `ConnectFlow` (trust on first use), `SyncHost` (sync engine, agent, metered hold, editor connections, Export Sync; `HasProjects`, `ProjectHome` and `ProjectChanged`, also told with null at each session start and stop: the server as a project home), sync table, `RemoteSequenceApi` |
| `Jobs`, `Settings`, `About` | Job list and buffering, `JobNotices` (which job endings raise a toast, conversions among them; `JobEndings` lets a batch speak once); the schedules of Jobs › Scheduled (`DesktopScheduleHost`: the desktop's `IScheduleHost` and its system schedules `archive-scan`, `index-backup`, `housekeeping`; `CacheTrimStep`, the host's clean-up step; `SchedulesViewModel`, `ScheduleRowViewModel`, `ScheduleEditorViewModel` and `ScheduleDialogs.xaml`, the in-window editor; `ScheduleText`); settings rows (`LogSettingsRows`: Advanced's log rows; `WorkspaceSettingsRows`: Settings › Workspace), 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; `SequenceReorganized`, raised after each Reorganize step and each sequence a conversion replaced or made, reloads an editor open on that sequence; the archive engine's free space from `VolumeInfo.FreeBytesAt`), `AppSettings`, `AppLogging` (Settings › Advanced › Logs applied to the log files from their first line, a launch that only hands over included, and at every save), `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` (`Toast.Closed` once a toast leaves the screen), `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`; `ScheduleEndpoints`: `/api/v1/schedules`; `LibraryEndpoints`: the Library filters' facets, sequence thumbnail, photo delete, bulk delete/retag/jobs; `TrashEndpoints`: list, restore, empty (`conversionDeleted` in its dry run); `ProjectEndpoints`: `/api/v1/sequences/{sid}/projects` through the archive's `ProjectService` (list with Main first, create, rename, delete, head, versions a page at a time, one version, push with its outcome as `ProjectPushResultDto` under a 65 MiB body limit, the frames and photo aliases a workspace places positions on and their stamp; pages capped at 4 Mi settings characters, `summary` and `stored` reads, 409 `sequence_empty` for a sequence without photos, deletion by the owner, an admin or the maker's own account); `SequenceEndpoints`' settings `PATCH` through `ArchiveService.EditSettingsAsync`; `ArchiveEndpoints`: settings, statistics, scan jobs, Reorganize's dry run and `move` job, Convert's dry run and `convert` job, both through `PlanCache`: a dry run's plan, made apart from its request, a few at once across both kinds, kept a few minutes while what it reads from the index stays (typed keys `PlanKey<TPlan>`: `ReorganizePlanKey`, `ConvertPlanKey` from `GetConvertStampAsync`, the selection and the target with the quality that counts, not the mode), for the same dry run and its confirmation; a conversion's confirmation takes only a kept plan (`Kept`), its busy sequences and free space taken again), 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 (the archive module's `SequenceChanged` publishes `sequenceChanged` `reorganized`, `converted` and `created`; its `FreeSpace` is `VolumeSpace.WritableFree`, the tighter of the space path's volume and the folder's own), uploads (`UploadMaintenance`: recovery at start, and the sweep that is the `uploads` clean-up step; `UploadService.ReceiveAgainAsync`: a verified upload whose filing was refused for now goes back to receiving, 503), render store (files a render under the sequence's lease, where the index has the folder then, with the project and version a node's job rendered; `FolderMovedException`, 503 `folder_moved`, when the sequence is not in it); `ProjectCatchUp` (Main takes settings written outside the projects soon after a `PATCH`, an analysis or a conversion, for sequences with a Main: `projectChanged` without waiting for the next project call); the archive module's `ProjectsChanged`, published as `projectChanged` (and `sequenceChanged` `settings` when Main was mirrored); `JobEngineHost`, `SchedulerHost` (the `Scheduler` on the engine, started after it; archive.json read every 10 minutes whatever the scan schedule does; every schedule change and run published as a `scheduleChanged` event) and `ServerScheduleHost` (time zone, archive refreshed from archive.json, system schedules), render node service (a job of a project version claimed with that version's settings placed on the frames it lists), monitor and availability |
| `Server/Hosting`, `Server/Admin/web` | `ServerHost`, `ServerLogging` (console and file levels the logging filters read at every line, the file sink's limits, the engine's level; applied again when Settings › Logs is saved), certificates, discovery beacon, embedded static files (`EmbeddedStaticFiles`: `no-cache` and a content ETag, so an upgrade never mixes old and new modules), Windows service (start and stop failures in the Application event log); the admin panel (ES modules, one per page; `schedules.js` is the Jobs page's Scheduled tab; the Library's views in `pages/library/`: `sequence.js` a sequence and its photo viewer, `projects.js` its Projects section (Main marked, head and last change, versions on demand, Rename and Delete of the others, live on `projectChanged`; nothing that edits settings), `trash.js` the archive's trash, `shared.js` cards, selection, grid keyboard and the retry of thumbnails a finished job may have built; `upload.js` the upload dialog the Library opens on demand, hashing in the module worker `hash-worker.js` with the in-house incremental SHA-256 of `sha256.js`, self-tested before its first use, and sending the capture time `capture-time.js` reads: the Exif DateTimeOriginal of a JPEG or TIFF-based file, else the file's time; `reorganize.js` the Reorganize dialog of the Library's selection and of the Archive page's save toast: template switches and fields, a live dry run of `POST /archive/reorganize` one request at a time, Apply that sends the shown plan's fingerprint back; `convert.js` the Convert dialog of the Library's selection (`planTarget` in `library.js`, shared with Reorganize: the ids, at most 1,000, or `all`): format, JPEG quality and a mode chosen at every run (Replace or New sequence, never preselected), a debounced dry run of `POST /archive/convert` one request at a time, asked in Replace's words until a mode is chosen and again while the server is still making it (a proxy's cut-off, `plan_dropped`), per sequence photos converted, left as they are or not copied and why, blocked, size before and after, the space line; Apply that confirms Replace by a typed word and New sequence with the photos not copied, asks the dry run again and sends the shown plan's fingerprint back, never twice after no answer; `pages/library/trash.js` gives replaced entries their own Restore and lists those whose conversion was deleted first; `audit.js` reads `archive_converted` as a sentence) |
### 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 (a conversion orders its own chain, the managed decoders first), its free space measured by Windows (`VolumeInfo.FreeBytesAt`, UNC shares included); `ProcessingService` with Media Foundation, then managed encoders; one `JobEngine` with the handlers of both and the workspace copy; the workspace (`WorkspaceHost`: `%LOCALAPPDATA%\Chronos\workspace` or `.\data\workspace`, unless Settings › Workspace says otherwise; none in a capture); thumbnails; `ServerSession`; `SyncHost` while signed in (sync engine and agent, upload and download handlers, metered hold, editors of server sequences, the server as the home of workspace projects when it has the `projects` capability); 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; the `Scheduler` on `DesktopScheduleHost`, started once the archive was reopened (an unplugged one is looked for every minute), which then runs the archive scan once (again when an unplugged archive is back), and whose system schedules replaced the rescan timer, the daily backup loop and the job-history purge (scans follow Settings › Analysis › After a scan at every run); 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`; `VolumeSpace` (free space of the archive, the space path and `/data`, file system and mount from `/proc/self/mountinfo`; `WritableFree`, what a conversion counts on; tests replace it); `EventHub` (WebSocket); embedded admin panel; LAN discovery beacon; Windows service host; `SchedulerHost` with the system schedules `archive-scan` (every 10 minutes, also once at start), `upload-cleanup` (every 6 hours), `index-backup` (SQLite only, 03:00), `housekeeping` (job history, 04:00) and `audit-cleanup` (04:30; Settings › Logs shows and sets its age limit, 0 while it is off; seeded and reset from `AuditRetentionDays`, 0 by default: off, the audit log kept; `CHRONOS_AUDIT_RETENTION_DAYS` fixes it before the first pass), no other timer queues work (a 10-minute timer only reads archive.json again) |
| 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` (a project version's portable settings placed on the frames first, the render recording the project and the version) | yes | managed formats, and MP4 jobs no render node can take (`RenderNodeAvailability`); render nodes claim the others (`Server/Jobs/RenderNodeService`, which places a project version's settings on the frames it sends, and records the project and version with the result); `POST /jobs` checks a job's project and version against the sequence and pins a project alone to its head |
| `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` | `Archiving/Jobs/ReportJobHandlers` (read-only reports into the job log, queued by schedules); the Archive screen still queries `ArchiveService` directly | yes | yes |
| `Backup` | `Housekeeping/BackupJobHandler` (via `ArchiveService.CreateJobHandlers`; an SQLite index file only) | yes | SQLite only |
| `Cleanup` | `Housekeeping/CleanupJobHandler` (shared steps, plus the host's from `ArchiveServiceOptions.CleanupSteps`) | yes | yes |
| `EmptyTrash` | `Archiving/Jobs/EmptyTrashJobHandler` (erases exactly a confirmed plan's trash entries; refuses a stale fingerprint) | yes | yes |
| `Move` | `Archiving/Jobs/MoveJobHandler` (Reorganize, `MoveJobParameters`: the templates, the sequences and the confirmed fingerprint; plans again from the templates, applies the plan only while it is the one confirmed, holds it when paused, cancelled or failed, keeps it while the archive is offline, tells each sequence changed as its step completes) | yes | yes |
| `Convert` | `Archiving/Jobs/ConvertJobHandler` (mass conversion through `MassConverter`, `ConvertJobParameters`: the target, quality and mode, the sequences with their frames version and the digest of the photos confirmed, whose ids wait in `journal/convert-<job>.photos`, and the fingerprint; targets are the sequences; settles what a crash left, refuses short space, converts each sequence all or nothing, the confirmed photos alone, resumes from its journal, tells each sequence `converted` or `created` and queues the passes it needs as it completes) | yes | yes (formats and files the server cannot decode natively are skipped: convert on a PC) |
| `WorkspaceCopy` | `Workspaces/WorkspaceCopyJobHandler` (via `WorkspaceJobs.CreateHandlers`: a sequence's proxies and deep report into a workspace project's media, high in the priority queue by default; its cancel clean-up as an `ICancelledJobHandler`; originals refused until phase 5c) | yes | no: it writes into the folder its parameters name |
| `Adopt` | none: done synchronously (`ArchiveService` 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. Recurring work is queued by the host's
`Scheduler` (`Data/Scheduling`): each run queues the action's jobs with the schedule's priority and `jobs.schedule_id`.
## 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. A writer takes a sequence's
folder from its index row read under the sequence's lease (`SequenceWriter.FolderAsync`): a Reorganize moves the folder,
its row and the paths of the renders inside it under that lease, so writers of the same index (uploads, proxies and
exports a server files, exports a sync fetches, editor saves, sync applies and "Save both" copies) write where the
sequence is. The image passes hold the thumbnail lease, which a Reorganize takes too: the thumbnail pass for all of it,
the proxy pass a batch at a time (a quarter of the lease wait), reading the folder and sidecar again for each batch. A
folder another index moved is found by this index's next scan, which moves the row, its frames and its exports' paths
(`ArchiveIndexer.RebaseRendersAsync`; an export, a file or an image-sequence folder, still at the old place keeps its
path, unless the old folder is another sequence's now, and an export of the sequence that holds the old folder never
follows); until then these writers, a render job as it starts and a proxy pass at each batch refuse when they find the
folder gone or holding another sequence (`SequenceFolders.Holds`; the server's render filing with a 503 that keeps the
upload), and a deep analysis that loses it records nothing. A render whose folder another index moves while it runs is
not stopped: its output can land in a folder created again at the old place, where its row keeps finding it.
A conversion (`MassConverter`) adds no writer of its own to a sequence's folder: it stages the files it makes in the
archive's `staging/convert-<job>/`, then files them through the archive ingest (New sequence) or swaps them in through
`FrameTrash.ReplaceAsync` (Replace), each under the sequence's lease, with the folder read from the index under it and
its sidecar the sequence's (`SequenceFolders.Holds`, `SequenceWriter.ReadLocked`); the originals a Replace takes out go
into the trash, never away. Its journals in `journal/` (`convert-<job>.json`, `.staged`, `.pins`, `.photos`) tell a resume, and
another host's maintenance, what the job did.
Projects (owner review 2, R8): a sequence's home (this PC's archive, or a server through `/api/v1/sequences/{sid}/projects`, phase 5b) keeps its projects as sidecars, then
index rows. A workspace on a fast disk checks a project out (its head as the base, the proxies copied by a `WorkspaceCopy`
job), edits the working state, saves versions locally (portable settings, positions parked by photo) and pushes them in
order: a push whose parent is the head fast-forwards; otherwise the home's new versions are pulled, each local version is
replayed on them (`ProjectMerge.Replay`) and the working state merged, and settings both sides changed stop there as a
conflict for the user. Main's head is the sequence's own settings (mirrored both ways), so analyses, the Library's quick
renders and server sync keep reading `project.json` and the index's settings; other projects never leave their home. The
desktop's Edit opens only workspace projects (`App/Workspace`): it edits their working state, and a render of one runs
at the home with its portable settings, recording the project and the version. The archive's sidecars stay the truth: a
deletion is taken only from the projects' trash, read first, a record that cannot be read holds its project back, and the
index heals the records it is ahead of. In a workspace the base in `project.chronos` is the commit point of every
write, so a cut push, replay or Save both is finished or undone by the next sync (`SettleAsync`).
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; `DevelopsRawAt8Bits` when its RAWs come out at 8 bits); chained by `DecoderFactory`, and for a conversion by `FrameConverter.Decoders` |
| 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/<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 `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<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 `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.<Area>.Tests/<Folder>/<Thing>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, `release-channels`) 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/<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)`; 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` for the highest stable release, or the highest pre-release while none is stable: `release-channels`); a separate releases repository is updated only when `RELEASES_REPO` names one, for the highest stable release |
| `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).