# sidlnk/lore architecture

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

- Interactive diagram: https://gitdiagram.com/sidlnk/lore
- Repository: https://github.com/sidlnk/lore

## Overview

Lore is a self-hosted family photo and video library: paired Android devices upload originals over the home network, then browse and organize the shared catalogue. The graph follows the upload path from app queue through the resumable client to the server API, and includes documented browsing, organization, location, and administration capabilities. Several routes and app pages were not sampled; their inclusion reflects the README and source tree, while uncertain internal call edges are omitted.

Main entry points: [`src/Lore.Client/LoreApiClient.cs`](https://github.com/sidlnk/lore/blob/main/src/Lore.Client/LoreApiClient.cs) (HTTP API client), [`src/Lore.Api/Program.cs`](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Program.cs) (API host and routing), [`src/Lore.Api/Endpoints/MediaEndpoints.cs`](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/MediaEndpoints.cs) (Media browsing routes), [`src/Lore.Api/Data/MediaAssetRow.cs`](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Data/MediaAssetRow.cs) (Media catalogue record)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_gallery["Gallery and viewer<br/>[GalleryPage.cs]"]
  node_library["Timeline and filters"]
  node_organize_ui["Organize screens<br/>[OrganizePages.cs]"]
  node_places["Places view<br/>[PlacesPage.cs]"]
  node_pairing["Pairing screen"]
  node_session["Device session<br/>[Session.cs]"]
  node_uploads["Upload coordinator<br/>[Uploads.cs]"]
  node_upload_service["Background upload<br/>[UploadService.cs]"]
  node_device_gallery["Phone media access<br/>[DeviceGallery.cs]"]
  node_free_up["Free phone space<br/>[FreeUp.cs]"]
  node_organizer["Organization actions<br/>[Organizer.cs]"]
  node_saves["Save to phone<br/>[Saves.cs]"]
end

subgraph group_client["Client and contracts"]
  node_api_client["HTTP API client<br/>[LoreApiClient.cs]"]
  node_upload_engine["Resumable upload engine<br/>[UploadEngine.cs]"]
  node_upload_queue[("Persistent upload queue<br/>[UploadQueue.cs]")]
  node_contracts["Shared DTOs<br/>[Contracts.cs]"]
end

subgraph group_api["Server API"]
  node_api_host["API host and routing<br/>[Program.cs]"]
  node_device_routes["Pairing and device routes<br/>[DeviceEndpoints.cs]"]
  node_upload_routes["Upload routes<br/>[UploadEndpoints.cs]"]
  node_media_routes["Media browsing routes<br/>[MediaEndpoints.cs]"]
  node_organize_routes["Organization routes"]
  node_admin_routes["Admin and app updates<br/>[AdminEndpoints.cs]"]
  node_app_routes["App version routes<br/>[AppEndpoints.cs]"]
end

subgraph group_media["Media and storage"]
  node_media_row["Media catalogue record<br/>[MediaAssetRow.cs]"]
  node_ingest["Metadata ingest<br/>[Ingest.cs]"]
  node_thumbnails["Thumbnail generation<br/>[Thumbnails.cs]"]
  node_storage[("Original file storage<br/>[StorageVolume.cs]")]
  node_maintenance["Database and upload maintenance"]
end

node_family(("Family member"))

node_family -->|"browses"| node_gallery
node_family -->|"pairs device"| node_pairing
node_gallery -->|"opens timeline"| node_library
node_library -->|"requests media"| node_api_client
node_organize_ui -->|"invokes actions"| node_organizer
node_organizer -->|"edits catalogue"| node_api_client
node_places -.->|"loads places"| node_api_client
node_pairing -.->|"pairs device"| node_session
node_session -->|"creates client"| node_api_client
node_gallery -->|"queues media"| node_uploads
node_uploads -->|"persists items"| node_upload_queue
node_uploads -->|"starts service"| node_upload_service
node_upload_service -->|"drains queue"| node_upload_engine
node_upload_engine -->|"updates items"| node_upload_queue
node_upload_engine -->|"sends chunks"| node_api_client
node_api_client -->|"calls upload API"| node_upload_routes
node_api_client -->|"calls media API"| node_media_routes
node_api_client -->|"calls organize API"| node_organize_routes
node_api_client -.->|"calls pairing API"| node_device_routes
node_api_client -->|"checks app version"| node_app_routes
node_api_host -->|"maps routes"| node_device_routes
node_api_host -->|"maps routes"| node_upload_routes
node_api_host -->|"maps routes"| node_media_routes
node_api_host -->|"maps routes"| node_organize_routes
node_api_host -->|"maps routes"| node_admin_routes
node_api_host -->|"maps routes"| node_app_routes
node_media_routes -->|"serves derivatives"| node_thumbnails
node_media_routes -->|"uses catalogue record"| node_media_row
node_organize_routes -->|"uses catalogue record"| node_media_row
node_ingest -->|"populates metadata"| node_media_row
node_thumbnails -->|"reads media metadata"| node_media_row
node_thumbnails -.->|"reads originals"| node_storage
node_free_up -->|"checks phone files"| node_device_gallery
node_free_up -->|"verifies originals"| node_api_client
node_saves -.->|"writes phone media"| node_device_gallery
node_admin_routes -->|"reports maintenance"| node_maintenance
node_maintenance -.->|"cleans abandoned uploads"| node_upload_queue

click node_gallery "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/GalleryPage.cs"
click node_library "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/LibraryViewModel.cs"
click node_organize_ui "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/OrganizePages.cs"
click node_places "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/PlacesPage.cs"
click node_pairing "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/PairingPage.xaml.cs"
click node_session "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Session.cs"
click node_uploads "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Uploads.cs"
click node_upload_service "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Platforms/Android/UploadService.cs"
click node_device_gallery "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Platforms/Android/DeviceGallery.cs"
click node_free_up "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/FreeUp.cs"
click node_organizer "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Organizer.cs"
click node_saves "https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Saves.cs"
click node_api_client "https://github.com/sidlnk/lore/blob/main/src/Lore.Client/LoreApiClient.cs"
click node_upload_engine "https://github.com/sidlnk/lore/blob/main/src/Lore.Client/UploadEngine.cs"
click node_upload_queue "https://github.com/sidlnk/lore/blob/main/src/Lore.Client/UploadQueue.cs"
click node_contracts "https://github.com/sidlnk/lore/blob/main/src/Lore.Contracts/Contracts.cs"
click node_api_host "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Program.cs"
click node_device_routes "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/DeviceEndpoints.cs"
click node_upload_routes "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/UploadEndpoints.cs"
click node_media_routes "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/MediaEndpoints.cs"
click node_organize_routes "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/OrganizeEndpoints.cs"
click node_admin_routes "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/AdminEndpoints.cs"
click node_app_routes "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/AppEndpoints.cs"
click node_media_row "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Data/MediaAssetRow.cs"
click node_ingest "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Media/Ingest.cs"
click node_thumbnails "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Media/Thumbnails.cs"
click node_storage "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Storage/StorageVolume.cs"
click node_maintenance "https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Data/MaintenanceService.cs"

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_gallery,node_library,node_organize_ui,node_places,node_pairing,node_session,node_uploads,node_upload_service,node_device_gallery,node_free_up,node_organizer,node_saves toneBlue
class node_api_client,node_upload_engine,node_upload_queue,node_contracts toneAmber
class node_api_host,node_device_routes,node_upload_routes,node_media_routes,node_organize_routes,node_admin_routes,node_app_routes toneMint
class node_media_row,node_ingest,node_thumbnails,node_storage,node_maintenance toneRose
class node_family toneIndigo
```

## Components

### Android app

- [Gallery and viewer](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/GalleryPage.cs): `src/Lore.App/Pages/GalleryPage.cs`
- [Timeline and filters](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/LibraryViewModel.cs): `src/Lore.App/Pages/LibraryViewModel.cs`
- [Organize screens](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/OrganizePages.cs): `src/Lore.App/Pages/OrganizePages.cs`
- [Places view](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/PlacesPage.cs): `src/Lore.App/Pages/PlacesPage.cs`
- [Pairing screen](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Pages/PairingPage.xaml.cs): `src/Lore.App/Pages/PairingPage.xaml.cs`
- [Device session](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Session.cs): `src/Lore.App/Services/Session.cs`
- [Upload coordinator](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Uploads.cs): `src/Lore.App/Services/Uploads.cs`
- [Background upload](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Platforms/Android/UploadService.cs): `src/Lore.App/Platforms/Android/UploadService.cs`
- [Phone media access](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Platforms/Android/DeviceGallery.cs): `src/Lore.App/Platforms/Android/DeviceGallery.cs`
- [Free phone space](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/FreeUp.cs): `src/Lore.App/Services/FreeUp.cs`
- [Organization actions](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Organizer.cs): `src/Lore.App/Services/Organizer.cs`
- [Save to phone](https://github.com/sidlnk/lore/blob/main/src/Lore.App/Services/Saves.cs): `src/Lore.App/Services/Saves.cs`

### Client and contracts

- [HTTP API client](https://github.com/sidlnk/lore/blob/main/src/Lore.Client/LoreApiClient.cs): `src/Lore.Client/LoreApiClient.cs`
- [Resumable upload engine](https://github.com/sidlnk/lore/blob/main/src/Lore.Client/UploadEngine.cs): `src/Lore.Client/UploadEngine.cs`
- [Persistent upload queue](https://github.com/sidlnk/lore/blob/main/src/Lore.Client/UploadQueue.cs): `src/Lore.Client/UploadQueue.cs`
- [Shared DTOs](https://github.com/sidlnk/lore/blob/main/src/Lore.Contracts/Contracts.cs): `src/Lore.Contracts/Contracts.cs`

### Server API

- [API host and routing](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Program.cs): `src/Lore.Api/Program.cs`
- [Pairing and device routes](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/DeviceEndpoints.cs): `src/Lore.Api/Endpoints/DeviceEndpoints.cs`
- [Upload routes](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/UploadEndpoints.cs): `src/Lore.Api/Endpoints/UploadEndpoints.cs`
- [Media browsing routes](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/MediaEndpoints.cs): `src/Lore.Api/Endpoints/MediaEndpoints.cs`
- [Organization routes](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/OrganizeEndpoints.cs): `src/Lore.Api/Endpoints/OrganizeEndpoints.cs`
- [Admin and app updates](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/AdminEndpoints.cs): `src/Lore.Api/Endpoints/AdminEndpoints.cs`
- [App version routes](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Endpoints/AppEndpoints.cs): `src/Lore.Api/Endpoints/AppEndpoints.cs`

### Media and storage

- [Media catalogue record](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Data/MediaAssetRow.cs): `src/Lore.Api/Data/MediaAssetRow.cs`
- [Metadata ingest](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Media/Ingest.cs): `src/Lore.Api/Media/Ingest.cs`
- [Thumbnail generation](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Media/Thumbnails.cs): `src/Lore.Api/Media/Thumbnails.cs`
- [Original file storage](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Storage/StorageVolume.cs): `src/Lore.Api/Storage/StorageVolume.cs`
- [Database and upload maintenance](https://github.com/sidlnk/lore/blob/main/src/Lore.Api/Data/MaintenanceService.cs): `src/Lore.Api/Data/MaintenanceService.cs`

### Other components

- **Family member**

## Connections

- Family member → Gallery and viewer: browses (evidence: `README.md`)
- Family member → Pairing screen: pairs device (evidence: `README.md`)
- Gallery and viewer → Timeline and filters: opens timeline (evidence: `src/Lore.App/Pages/GalleryPage.cs`)
- Timeline and filters → HTTP API client: requests media (evidence: `src/Lore.App/Pages/LibraryViewModel.cs`)
- Organize screens → Organization actions: invokes actions (evidence: `src/Lore.App/Pages/OrganizePages.cs`)
- Organization actions → HTTP API client: edits catalogue (evidence: `src/Lore.App/Services/Organizer.cs`)
- Places view → HTTP API client: loads places
- Pairing screen → Device session: pairs device
- Device session → HTTP API client: creates client (evidence: `src/Lore.App/Services/Session.cs`)
- Gallery and viewer → Upload coordinator: queues media (evidence: `src/Lore.App/Pages/GalleryPage.cs`)
- Upload coordinator → Persistent upload queue: persists items (evidence: `src/Lore.App/Services/Uploads.cs`)
- Upload coordinator → Background upload: starts service (evidence: `src/Lore.App/Services/Uploads.cs`)
- Background upload → Resumable upload engine: drains queue (evidence: `src/Lore.App/Platforms/Android/UploadService.cs`)
- Resumable upload engine → Persistent upload queue: updates items (evidence: `src/Lore.Client/UploadEngine.cs`)
- Resumable upload engine → HTTP API client: sends chunks (evidence: `src/Lore.Client/UploadEngine.cs`)
- HTTP API client → Upload routes: calls upload API (evidence: `src/Lore.Client/LoreApiClient.cs`)
- HTTP API client → Media browsing routes: calls media API (evidence: `src/Lore.Client/LoreApiClient.cs`)
- HTTP API client → Organization routes: calls organize API (evidence: `src/Lore.Client/LoreApiClient.cs`)
- HTTP API client → Pairing and device routes: calls pairing API
- HTTP API client → App version routes: checks app version (evidence: `src/Lore.Client/LoreApiClient.cs`)
- API host and routing → Pairing and device routes: maps routes (evidence: `src/Lore.Api/Program.cs`)
- API host and routing → Upload routes: maps routes (evidence: `src/Lore.Api/Program.cs`)
- API host and routing → Media browsing routes: maps routes (evidence: `src/Lore.Api/Program.cs`)
- API host and routing → Organization routes: maps routes (evidence: `src/Lore.Api/Program.cs`)
- API host and routing → Admin and app updates: maps routes (evidence: `src/Lore.Api/Program.cs`)
- API host and routing → App version routes: maps routes (evidence: `src/Lore.Api/Program.cs`)
- Media browsing routes → Thumbnail generation: serves derivatives (evidence: `src/Lore.Api/Endpoints/MediaEndpoints.cs`)
- Media browsing routes → Media catalogue record: uses catalogue record (evidence: `src/Lore.Api/Endpoints/MediaEndpoints.cs`)
- Organization routes → Media catalogue record: uses catalogue record (evidence: `src/Lore.Api/Endpoints/OrganizeEndpoints.cs`)
- Metadata ingest → Media catalogue record: populates metadata (evidence: `src/Lore.Api/Media/Ingest.cs`)
- Thumbnail generation → Media catalogue record: reads media metadata (evidence: `src/Lore.Api/Media/Thumbnails.cs`)
- Thumbnail generation → Original file storage: reads originals
- Free phone space → Phone media access: checks phone files (evidence: `src/Lore.App/Services/FreeUp.cs`)
- Free phone space → HTTP API client: verifies originals (evidence: `src/Lore.App/Services/FreeUp.cs`)
- Save to phone → Phone media access: writes phone media (evidence: `src/Lore.App/Services/Saves.cs`)
- Admin and app updates → Database and upload maintenance: reports maintenance (evidence: `src/Lore.Api/Endpoints/AdminEndpoints.cs`)
- Database and upload maintenance → Persistent upload queue: cleans abandoned uploads
