# dilharajay/mediasort-studio architecture

> Architecture diagram of the GitHub repository dilharajay/mediasort-studio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dilharajay/mediasort-studio
- Repository: https://github.com/dilharajay/mediasort-studio

## Overview

MediaSort scans event-photo folders, classifies images, records routing decisions, supports human review, and reconciles/export bins without modifying originals. Users enter through either the desktop GUI or CLI; the GUI calls a local FastAPI sidecar. The graph preserves the documented classification, review, configuration, and delivery stages. Some subsystem links reflect README or SOURCE INDEX references; unsampled route and export internals are not inferred beyond those references.

Main entry points: [`mediasort/cli.py`](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/cli.py) (CLI), [`mediasort/api/server.py`](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/server.py) (FastAPI server), [`mediasort/api/routes/classify.py`](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/classify.py) (Classification API), [`mediasort/config.py`](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/config.py) (Event settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_desktop["Desktop app<br/>[App.jsx]"]
  node_ui_panels["Review panels"]
  node_api_client["API client<br/>[api.js]"]
  node_cli["CLI<br/>[cli.py]"]
  node_sidecar["Electron sidecar<br/>[sidecar.js]"]
end

subgraph group_service["Local API"]
  node_api_server["FastAPI server<br/>[server.py]"]
  node_manifest_routes["Event and manifest<br/>[manifest.py]"]
  node_classify_route["Classification API<br/>[classify.py]"]
  node_image_routes["Image API<br/>[images.py]"]
  node_review_route["Review API<br/>[review.py]"]
  node_export_route["Export API<br/>[export.py]"]
  node_config_route["Configuration API<br/>[config.py]"]
end

subgraph group_ingest["Image processing"]
  node_scanner["Folder scanner<br/>[scanner.py]"]
  node_decoder["Image decoder<br/>[decoder.py]"]
  node_thumbnails["Thumbnail service<br/>[thumbnails.py]"]
end

subgraph group_decisions["Classification and review"]
  node_clip["Semantic and aesthetic<br/>[clip.py]"]
  node_faces["Face and blink analysis<br/>[face.py]"]
  node_iqa["Technical quality<br/>[iqa.py]"]
  node_fusion["Score and routing<br/>[fusion.py]"]
  node_review_cli["Interactive review<br/>[review_cli.py]"]
end

subgraph group_outputs["Manifest and delivery"]
  node_manifest[("Event manifest<br/>[models.py]")]
  node_configuration["Event settings<br/>[config.py]"]
  node_copy["Bin reconciliation<br/>[copy_cli.py]"]
  node_commit["Delivery export<br/>[commit_cli.py]"]
  node_xmp["XMP sidecars<br/>[xmp.py]"]
end

node_photographer(("Photographer"))

node_photographer -->|"reviews photos"| node_desktop
node_photographer -->|"runs stages"| node_cli
node_desktop -->|"requests data"| node_api_client
node_desktop -->|"renders"| node_ui_panels
node_api_client -->|"HTTP and WebSocket"| node_api_server
node_sidecar -->|"launches locally"| node_api_server
node_api_server -->|"registers"| node_manifest_routes
node_api_server -->|"registers"| node_classify_route
node_api_server -->|"registers"| node_image_routes
node_api_server -->|"registers"| node_review_route
node_api_server -->|"registers"| node_export_route
node_api_server -->|"registers"| node_config_route
node_manifest_routes -->|"scans event folder"| node_scanner
node_manifest_routes -->|"loads and saves"| node_manifest
node_classify_route -->|"scans images"| node_scanner
node_classify_route -->|"classifies"| node_clip
node_classify_route -->|"analyzes faces"| node_faces
node_classify_route -->|"scores quality"| node_iqa
node_classify_route -->|"reads settings"| node_configuration
node_classify_route -.->|"records results"| node_manifest
node_image_routes -->|"serves thumbnails"| node_thumbnails
node_image_routes -->|"reads manifest"| node_manifest_routes
node_review_route -->|"updates decisions"| node_manifest_routes
node_export_route -->|"runs reconciliation"| node_copy
node_export_route -->|"runs delivery export"| node_commit
node_config_route -.->|"reads and updates"| node_configuration
node_cli -->|"scans"| node_scanner
node_cli -->|"decodes"| node_decoder
node_cli -->|"classifies"| node_clip
node_cli -->|"analyzes faces"| node_faces
node_cli -->|"scores quality"| node_iqa
node_cli -->|"routes scores"| node_fusion
node_cli -->|"starts review"| node_review_cli
node_cli -->|"reconciles bins"| node_copy
node_cli -->|"exports delivery"| node_commit
node_decoder -->|"checks RAW type"| node_scanner
node_decoder -->|"uses decode settings"| node_configuration
node_thumbnails -->|"decodes previews"| node_decoder
node_clip -->|"uses taxonomy"| node_configuration
node_faces -->|"uses face settings"| node_configuration
node_iqa -->|"uses quality settings"| node_configuration
node_fusion -->|"uses routing settings"| node_configuration
node_review_cli -->|"reads decisions"| node_manifest
node_copy -->|"reconciles from"| node_manifest
node_commit -->|"reads decisions"| node_manifest
node_commit -->|"writes sidecars"| node_xmp
node_desktop -->|"edits settings"| node_configuration
node_desktop -->|"shows live results"| node_manifest

click node_desktop "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort-ui/src/App.jsx"
click node_ui_panels "https://github.com/dilharajay/mediasort-studio/tree/main/mediasort-ui/src/components"
click node_api_client "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort-ui/src/api.js"
click node_cli "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/cli.py"
click node_sidecar "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort-ui/electron/sidecar.js"
click node_api_server "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/server.py"
click node_manifest_routes "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/manifest.py"
click node_classify_route "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/classify.py"
click node_image_routes "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/images.py"
click node_review_route "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/review.py"
click node_export_route "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/export.py"
click node_config_route "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/config.py"
click node_scanner "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/ingest/scanner.py"
click node_decoder "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/ingest/decoder.py"
click node_thumbnails "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/thumbnails.py"
click node_clip "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/clip.py"
click node_faces "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/face.py"
click node_iqa "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/iqa.py"
click node_fusion "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/fusion.py"
click node_review_cli "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/review_cli.py"
click node_manifest "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/manifest/models.py"
click node_configuration "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/config.py"
click node_copy "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/copy_cli.py"
click node_commit "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/commit_cli.py"
click node_xmp "https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/xmp.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_ui_panels,node_api_client,node_cli,node_sidecar toneBlue
class node_api_server,node_manifest_routes,node_classify_route,node_image_routes,node_review_route,node_export_route,node_config_route toneAmber
class node_scanner,node_decoder,node_thumbnails toneMint
class node_clip,node_faces,node_iqa,node_fusion,node_review_cli toneRose
class node_manifest,node_configuration,node_copy,node_commit,node_xmp,node_photographer toneIndigo
```

## Components

### User clients

- [Desktop app](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort-ui/src/App.jsx): `mediasort-ui/src/App.jsx`
- [Review panels](https://github.com/dilharajay/mediasort-studio/tree/main/mediasort-ui/src/components): `mediasort-ui/src/components`
- [API client](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort-ui/src/api.js): `mediasort-ui/src/api.js`
- [CLI](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/cli.py): `mediasort/cli.py`
- [Electron sidecar](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort-ui/electron/sidecar.js): `mediasort-ui/electron/sidecar.js`

### Local API

- [FastAPI server](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/server.py): `mediasort/api/server.py`
- [Event and manifest](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/manifest.py): `mediasort/api/routes/manifest.py`
- [Classification API](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/classify.py): `mediasort/api/routes/classify.py`
- [Image API](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/images.py): `mediasort/api/routes/images.py`
- [Review API](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/review.py): `mediasort/api/routes/review.py`
- [Export API](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/export.py): `mediasort/api/routes/export.py`
- [Configuration API](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/routes/config.py): `mediasort/api/routes/config.py`

### Image processing

- [Folder scanner](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/ingest/scanner.py): `mediasort/ingest/scanner.py`
- [Image decoder](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/ingest/decoder.py): `mediasort/ingest/decoder.py`
- [Thumbnail service](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/api/thumbnails.py): `mediasort/api/thumbnails.py`

### Classification and review

- [Semantic and aesthetic](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/clip.py): `mediasort/classify/clip.py`
- [Face and blink analysis](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/face.py): `mediasort/classify/face.py`
- [Technical quality](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/iqa.py): `mediasort/classify/iqa.py`
- [Score and routing](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/classify/fusion.py): `mediasort/classify/fusion.py`
- [Interactive review](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/review_cli.py): `mediasort/review_cli.py`

### Manifest and delivery

- [Event manifest](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/manifest/models.py): `mediasort/manifest/models.py`
- [Event settings](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/config.py): `mediasort/config.py`
- [Bin reconciliation](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/copy_cli.py): `mediasort/copy_cli.py`
- [Delivery export](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/commit_cli.py): `mediasort/commit_cli.py`
- [XMP sidecars](https://github.com/dilharajay/mediasort-studio/blob/main/mediasort/xmp.py): `mediasort/xmp.py`

### Other components

- **Photographer**

## Connections

- Photographer → Desktop app: reviews photos
- Photographer → CLI: runs stages
- Desktop app → API client: requests data (evidence: `mediasort-ui/src/App.jsx`)
- Desktop app → Review panels: renders (evidence: `mediasort-ui/src/App.jsx`)
- API client → FastAPI server: HTTP and WebSocket (evidence: `mediasort-ui/src/api.js`)
- Electron sidecar → FastAPI server: launches locally
- FastAPI server → Event and manifest: registers (evidence: `mediasort/api/server.py`)
- FastAPI server → Classification API: registers (evidence: `mediasort/api/server.py`)
- FastAPI server → Image API: registers (evidence: `mediasort/api/server.py`)
- FastAPI server → Review API: registers (evidence: `mediasort/api/server.py`)
- FastAPI server → Export API: registers (evidence: `mediasort/api/server.py`)
- FastAPI server → Configuration API: registers (evidence: `mediasort/api/server.py`)
- Event and manifest → Folder scanner: scans event folder (evidence: `mediasort/api/routes/manifest.py`)
- Event and manifest → Event manifest: loads and saves (evidence: `mediasort/api/routes/manifest.py`)
- Classification API → Folder scanner: scans images (evidence: `mediasort/api/routes/classify.py`)
- Classification API → Semantic and aesthetic: classifies (evidence: `mediasort/api/routes/classify.py`)
- Classification API → Face and blink analysis: analyzes faces (evidence: `mediasort/api/routes/classify.py`)
- Classification API → Technical quality: scores quality (evidence: `mediasort/api/routes/classify.py`)
- Classification API → Event settings: reads settings (evidence: `mediasort/api/routes/classify.py`)
- Classification API → Event manifest: records results
- Image API → Thumbnail service: serves thumbnails (evidence: `mediasort/api/routes/images.py`)
- Image API → Event and manifest: reads manifest (evidence: `mediasort/api/routes/images.py`)
- Review API → Event and manifest: updates decisions (evidence: `mediasort/api/routes/review.py`)
- Export API → Bin reconciliation: runs reconciliation (evidence: `mediasort/api/routes/export.py`)
- Export API → Delivery export: runs delivery export (evidence: `mediasort/api/routes/export.py`)
- Configuration API → Event settings: reads and updates
- CLI → Folder scanner: scans (evidence: `mediasort/cli.py`)
- CLI → Image decoder: decodes (evidence: `mediasort/cli.py`)
- CLI → Semantic and aesthetic: classifies (evidence: `mediasort/cli.py`)
- CLI → Face and blink analysis: analyzes faces (evidence: `mediasort/cli.py`)
- CLI → Technical quality: scores quality (evidence: `mediasort/cli.py`)
- CLI → Score and routing: routes scores (evidence: `mediasort/cli.py`)
- CLI → Interactive review: starts review (evidence: `mediasort/cli.py`)
- CLI → Bin reconciliation: reconciles bins (evidence: `mediasort/cli.py`)
- CLI → Delivery export: exports delivery (evidence: `mediasort/cli.py`)
- Image decoder → Folder scanner: checks RAW type (evidence: `mediasort/ingest/decoder.py`)
- Image decoder → Event settings: uses decode settings (evidence: `mediasort/ingest/decoder.py`)
- Thumbnail service → Image decoder: decodes previews (evidence: `mediasort/api/thumbnails.py`)
- Semantic and aesthetic → Event settings: uses taxonomy (evidence: `mediasort/classify/clip.py`)
- Face and blink analysis → Event settings: uses face settings (evidence: `mediasort/classify/face.py`)
- Technical quality → Event settings: uses quality settings (evidence: `mediasort/classify/iqa.py`)
- Score and routing → Event settings: uses routing settings (evidence: `mediasort/classify/fusion.py`)
- Interactive review → Event manifest: reads decisions (evidence: `mediasort/review_cli.py`)
- Bin reconciliation → Event manifest: reconciles from (evidence: `mediasort/copy_cli.py`)
- Delivery export → Event manifest: reads decisions (evidence: `mediasort/commit_cli.py`)
- Delivery export → XMP sidecars: writes sidecars (evidence: `mediasort/commit_cli.py`)
- Desktop app → Event settings: edits settings
- Desktop app → Event manifest: shows live results
