# spasmilenkov/project-alexandria architecture

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

- Interactive diagram: https://gitdiagram.com/spasmilenkov/project-alexandria
- Repository: https://github.com/spasmilenkov/project-alexandria
- Video tour (about a minute): https://gitdiagram.com/spasmilenkov/project-alexandria/video

## Overview

Alexandria is a self-hosted file-management and media-serving application. Users manage directories and files through the API, upload content, and retrieve versions, previews, or shared files; preview generation runs asynchronously. The repository also exposes tagging, streaming/playlists, account and appearance settings, and administrative monitoring. The preview dispatch, worker, storage, and statistics connections are supported by sampled source; other feature groupings reflect the file tree and README, so their internal call wiring is not expanded.

Main entry points: [`Backend/Alexandria.Workers.Document/Handlers/PreviewGenerationHandler.cs`](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Workers.Document/Handlers/PreviewGenerationHandler.cs) (Preview job handler), [`Backend/Alexandria.Api/Features/Storage`](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Storage) (Files and directories API), [`Backend/Alexandria.Services.Preview/PreviewService.cs`](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Preview/PreviewService.cs) (Preview dispatch), [`Backend/Alexandria.Services.Monitoring/PreviewStatsService.cs`](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Monitoring/PreviewStatsService.cs) (Preview statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Accounts and access"]
  node_auth["Authentication API<br/>[Auth]"]
  node_users["User management<br/>[Users]"]
  node_policies["Access policies<br/>[Policies]"]
end

subgraph group_files["File management"]
  node_fileapi["Files and directories API<br/>[Storage]"]
  node_tags["Tagging API<br/>[Tags]"]
  node_sharing["Share links API<br/>[SignedUrls]"]
  node_objectstore[("S3 object storage")]
end

subgraph group_preview["Preview pipeline"]
  node_previewapi["Preview API<br/>[Preview]"]
  node_previewservice["Preview dispatch<br/>[PreviewService.cs]"]
  node_broker["Message broker"]
  node_worker["Preview job handler"]
  node_pdf["Document previews"]
  node_mediaengine["Media previews"]
  node_previewrepo["Preview repository"]
end

subgraph group_media["Streaming and media"]
  node_streamapi["Streaming and playlists API<br/>[Streaming]"]
  node_player["Player engine<br/>[usePlayerEngine.ts]"]
end

subgraph group_operations["Settings and operations"]
  node_settings["User settings<br/>[Settings]"]
  node_admin["Admin and monitoring API<br/>[Admin]"]
  node_monitoring["Preview statistics"]
  node_postgres[("PostgreSQL")]
  node_previewstatsrepo["Preview data access"]
end

node_user(("User"))

node_user -->|"authenticates"| node_auth
node_user -->|"manages files"| node_fileapi
node_user -->|"organizes files"| node_tags
node_user -->|"shares files"| node_sharing
node_user -->|"views previews"| node_previewapi
node_user -->|"streams media"| node_streamapi
node_user -->|"customizes"| node_settings
node_fileapi -->|"requests previews"| node_previewservice
node_previewservice -->|"checks jobs"| node_previewrepo
node_previewservice -->|"publishes jobs"| node_broker
node_broker -->|"delivers jobs"| node_worker
node_worker -->|"generates documents"| node_pdf
node_worker -->|"generates media"| node_mediaengine
node_worker -->|"uploads previews"| node_objectstore
node_worker -->|"updates records"| node_previewrepo
node_previewapi -->|"serves previews"| node_objectstore
node_sharing -->|"serves shared files"| node_objectstore
node_player -->|"requests streams"| node_streamapi
node_player -->|"plays media"| node_user
node_admin -->|"requests statistics"| node_monitoring
node_monitoring -->|"queries preview data"| node_previewstatsrepo
node_monitoring -->|"queries job data"| node_postgres
node_previewrepo -->|"reads and writes"| node_postgres
node_previewstatsrepo -->|"reads preview records"| node_postgres
node_policies -->|"stores rules"| node_postgres
node_users -->|"stores accounts"| node_postgres
node_settings -->|"stores preferences"| node_postgres
node_fileapi -->|"stores file content"| node_objectstore

click node_auth "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Auth"
click node_users "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Users"
click node_fileapi "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Storage"
click node_tags "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Tags"
click node_sharing "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Storage/SignedUrls"
click node_previewapi "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Storage/Files/Preview"
click node_previewservice "https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Preview/PreviewService.cs"
click node_worker "https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Workers.Document/Handlers/PreviewGenerationHandler.cs"
click node_pdf "https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Preview/Documents/PdfPreviewService.cs"
click node_mediaengine "https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Preview/Media/MediaPreviewService.cs"
click node_previewrepo "https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Repositories/PreviewRepository.cs"
click node_streamapi "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Streaming"
click node_player "https://github.com/spasmilenkov/project-alexandria/blob/main/Frontend/src/composables/usePlayerEngine.ts"
click node_policies "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Policies"
click node_settings "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Settings"
click node_admin "https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Admin"
click node_monitoring "https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Monitoring/PreviewStatsService.cs"
click node_previewstatsrepo "https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Repositories/PreviewRepository.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_auth,node_users,node_policies,node_user toneBlue
class node_fileapi,node_tags,node_sharing,node_objectstore toneAmber
class node_previewapi,node_previewservice,node_broker,node_worker,node_pdf,node_mediaengine,node_previewrepo toneMint
class node_streamapi,node_player toneRose
class node_settings,node_admin,node_monitoring,node_postgres,node_previewstatsrepo toneIndigo
```

## Components

### Accounts and access

- [Authentication API](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Auth): `Backend/Alexandria.Api/Features/Auth`
- [User management](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Users): `Backend/Alexandria.Api/Features/Users`
- [Access policies](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Policies): `Backend/Alexandria.Api/Features/Policies`

### File management

- [Files and directories API](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Storage): `Backend/Alexandria.Api/Features/Storage`
- [Tagging API](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Tags): `Backend/Alexandria.Api/Features/Tags`
- [Share links API](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Storage/SignedUrls): `Backend/Alexandria.Api/Features/Storage/SignedUrls`
- **S3 object storage**

### Preview pipeline

- [Preview API](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Storage/Files/Preview): `Backend/Alexandria.Api/Features/Storage/Files/Preview`
- [Preview dispatch](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Preview/PreviewService.cs): `Backend/Alexandria.Services.Preview/PreviewService.cs`
- **Message broker**
- [Preview job handler](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Workers.Document/Handlers/PreviewGenerationHandler.cs): `Backend/Alexandria.Workers.Document/Handlers/PreviewGenerationHandler.cs`
- [Document previews](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Preview/Documents/PdfPreviewService.cs): `Backend/Alexandria.Services.Preview/Documents/PdfPreviewService.cs`
- [Media previews](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Preview/Media/MediaPreviewService.cs): `Backend/Alexandria.Services.Preview/Media/MediaPreviewService.cs`
- [Preview repository](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Repositories/PreviewRepository.cs): `Backend/Alexandria.Repositories/PreviewRepository.cs`

### Streaming and media

- [Streaming and playlists API](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Streaming): `Backend/Alexandria.Api/Features/Streaming`
- [Player engine](https://github.com/spasmilenkov/project-alexandria/blob/main/Frontend/src/composables/usePlayerEngine.ts): `Frontend/src/composables/usePlayerEngine.ts`

### Settings and operations

- [User settings](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Settings): `Backend/Alexandria.Api/Features/Settings`
- [Admin and monitoring API](https://github.com/spasmilenkov/project-alexandria/tree/main/Backend/Alexandria.Api/Features/Admin): `Backend/Alexandria.Api/Features/Admin`
- [Preview statistics](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Services.Monitoring/PreviewStatsService.cs): `Backend/Alexandria.Services.Monitoring/PreviewStatsService.cs`
- **PostgreSQL**
- [Preview data access](https://github.com/spasmilenkov/project-alexandria/blob/main/Backend/Alexandria.Repositories/PreviewRepository.cs): `Backend/Alexandria.Repositories/PreviewRepository.cs`

### Other components

- **User**

## Connections

- User → Authentication API: authenticates
- User → Files and directories API: manages files
- User → Tagging API: organizes files
- User → Share links API: shares files
- User → Preview API: views previews
- User → Streaming and playlists API: streams media
- User → User settings: customizes
- Files and directories API → Preview dispatch: requests previews
- Preview dispatch → Preview repository: checks jobs
- Preview dispatch → Message broker: publishes jobs
- Message broker → Preview job handler: delivers jobs
- Preview job handler → Document previews: generates documents
- Preview job handler → Media previews: generates media
- Preview job handler → S3 object storage: uploads previews
- Preview job handler → Preview repository: updates records
- Preview API → S3 object storage: serves previews
- Share links API → S3 object storage: serves shared files
- Player engine → Streaming and playlists API: requests streams
- Player engine → User: plays media
- Admin and monitoring API → Preview statistics: requests statistics
- Preview statistics → Preview data access: queries preview data
- Preview statistics → PostgreSQL: queries job data
- Preview repository → PostgreSQL: reads and writes
- Preview data access → PostgreSQL: reads preview records
- Access policies → PostgreSQL: stores rules
- User management → PostgreSQL: stores accounts
- User settings → PostgreSQL: stores preferences
- Files and directories API → S3 object storage: stores file content