Files
Chronos/docs/ARCHITECTURE.md
T
Alby96andClaude Opus 5.5 50e28fd63d fix: projects and the workspace copy follow phase 4's folder and conversion rules
Phase 5a was written on an early phase 4a state. On top of phase 4b it now
keeps the rules every writer of a sequence's folder follows, and keeps
project versions intact through Reorganize and conversions:

- ProjectService writes project sidecars, project.json and the settings
  only under the sequence's lease and only in a folder that holds the
  sequence (SequenceFolders.Holds). A folder another index moved away, or
  one another sequence was moved into, is refused with
  SequenceFolderMovedException: reads answer from the index, so no
  project is taken for gone, nothing is written into the other sequence's
  folder and the old folder is never created again. The home reports it
  as out of reach. Full scans and rebuilds reconcile projects the same
  way, and a failure there is logged instead of failing the scan.
- Stored versions park positions by photo and now follow the encodings a
  Replace conversion (or its undo) joined through the sequence's Replaced
  tombstones (PhotoAlias, HomePhotos): Main's mirror, renders of a
  version and workspace media place them on the converted frames.
  ProjectContent.Rebind/SameChoices name parked photos as the frames hold
  them now, so a conversion or a hash since is no "external" Main version
  and no spurious "Modified" in a workspace, and merges see one photo.
- The workspace copy job only reads the archive: it no longer runs the
  archive's proxy pass, makes missing proxies in the workspace, reads
  only a folder that holds the sequence, starts again when the folder
  moved or files were renamed during the copy, resumes from a checkpoint
  of its frames version, and refuses a workspace folder inside any
  library before it writes anything (Errors.Workspace.InsideLibrary).
  The working state keeps its positions by frame where frames stay.
- ArchiveProjectHome looks for a project or version the index does not
  know yet in the sequence's sidecars first (an index taken back from a
  backup, a sequence back from the trash), instead of calling it gone.

Tests cover the moved and taken folder, conversions in the archive and in
the workspace, the copy refusing a workspace in a library, resuming on
other frames, the alias lookup and the rebinding.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 10:14:39 +01:00

53 KiB
Raw Blame History

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, 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, 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; 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, JPEG quality, 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 (native-tier decode only, 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), ConvertPlanner (per sequence the frames converted and skipped with ConvertSkip, size estimates per pixel, 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), 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); 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)
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), 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), 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 (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), 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; FrameTrash.Replace: the files of frames swapped in place, same ids and indices, the old files into one Replaced entry with their replacements' hashes and a copy of analysis.json, tombstones aliasing old content to new, under .chronos/replace.pending.json, which the next writer undoes or completes), MassConverter (conversion's dry run with busy, offline and unreadable sequences and the space against ArchiveServiceOptions.FreeSpace; the job's stage A converts into staging/convert-<job>/ with OrderedWork, each staged file appended to journal/convert-<job>.staged; 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; each sequence replaced or made told 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): list, create, rename, delete into projects/.trash, history, push with fast-forward / idempotent repeat / divergence / hash and portability checks; each call first catches up: the sidecars into the index (ProjectIndexer, also run by full scans and rebuilds; a version file a push left past its record adopted, a stray one moved to versions/.stray), Main made from the sequence's settings, settings another path wrote appended to Main as an external version, a mirror a crash cut short completed or merged; a push to Main mirrored into project.json and the settings with the settings version check), ProjectSidecars (record and immutable version files, the settings as a JSON string checked against their hash), ProjectMerge (three-way merge member by member, pending frames merged photo by photo, conflicts, Replay of local commits on a moved head), IProjectHome and ArchiveProjectHome (the home a workspace pushes to and pulls from, a project or version the index lacks looked for in the sidecars first; the server's comes in phase 5b), HomePhotos (a sequence's photos as positions name them, with the encodings its Replaced tombstones join)
Workspaces WorkspaceStore (a folder outside the library: workspace.json, one folder per project, no index), WorkspaceProject (project.chronos working state, media/ with media.json, proxies/<frame id>.jpg and analysis.json, versions/, sync.json for a restore or a conflict, exports/, the lease .lock.lease), WorkspaceSync (checkout, open, save, commit, push, pull with replay and merge, conflicts settled by keep mine, take server or save both, restore, status), WorkspaceCopyJobHandler (WorkspaceJobs.Copy, 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; 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)
Sync SyncService (sync table of one server: compare, link by content, settle conflicts, enqueue transfers), SyncRules (status, settings merge and differences, no I/O), SyncTombstones (photos either side removed are not offered back, a replaced photo counts as its replacement), 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, 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, 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, renders at the home with the portable settings through IProjectRenders), 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 as the home; checkout and copy, status, Save version with the sync after it, sync, resolve, restore, history, new, rename, delete, the plan and removal of a local copy whose unsent work goes to <workspace>/.trash, pruning past Kept versions), ProjectMenuViewModel (the title's ▾: state chip, the menu, Update media; IWorkspaceUi is what it asks of the section), WorkspaceDialogs (Open in workspace, project name, Save version, History, conflict, Remove local copy; WorkspaceDialogs.xaml), WorkspaceProjectItem (a picker row), WorkspaceText (states, versions, 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, Apply behind a typed confirmation for Replace queues the convert job of that plan; ConvertPlans: the plan as rows, a summary, the space line and the Replace confirmation; ConvertUndo: the Undo of a finished Replace, which restores its Replaced trash entries), retag, delete and trash dialogs (SequenceDeletion, DeletePlans, TrashEmptyPlans: Empty… behind a dry run and a typed confirmation), 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); 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, reloads an editor open on that sequence), 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; 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, kept a few minutes while what it reads from the index stays (its PlanKey), for the same dry run and its confirmation), 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), 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; FolderMovedException, 503 folder_moved, when the sequence is not in it); 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, 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, 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: format, JPEG quality and a mode chosen at every run (Replace or New sequence, never preselected), a debounced dry run of POST /archive/convert per sequence (photos converted, left as they are and why, blocked, size before and after, the space line), Apply that confirms Replace by a typed word and sends the shown plan's fingerprint back)

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 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 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; 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)
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: targets are the sequences; plans again, refuses short space, converts each sequence all or nothing, resumes from its journal, queues the passes the frames need again) yes yes (formats 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; 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.

Projects (owner review 2, R8): a sequence's home (this PC's archive; a server in 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.

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/<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).