# lodilorenzo/teatro architecture

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

- Interactive diagram: https://gitdiagram.com/lodilorenzo/teatro
- Repository: https://github.com/lodilorenzo/teatro

## Overview

Teatro is a self-hosted game-library server: users sign in, browse/search a catalog, inspect game details and download files; administrators manage users and tokens, add or scan games, edit metadata, verify integrity, and run optional integrations. The graph preserves these stages and the storage, session, and job layers, plus the player and admin interfaces. Several backend feature modules are present in the tree and documented in the README but were not excerpted, so their internal call relationships are omitted; dashed links mark documented but unsampled feature paths.

Main entry points: [`src/api/admin`](https://github.com/lodilorenzo/teatro/tree/main/src/api/admin) (Admin endpoints), [`src/api/mod.rs`](https://github.com/lodilorenzo/teatro/blob/main/src/api/mod.rs) (HTTP router), [`src/services/library`](https://github.com/lodilorenzo/teatro/tree/main/src/services/library) (Library operations), [`web/public/main.js`](https://github.com/lodilorenzo/teatro/blob/main/web/public/main.js) (Player browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Web interfaces"]
  node_player["Player browser<br/>[main.js]"]
  node_admin["Admin browser<br/>[main.js]"]
  node_player_views["Catalog views<br/>[views.js]"]
  node_admin_features["Admin features"]
  node_admin_state["Admin state<br/>[state.js]"]
end

subgraph group_http["HTTP API"]
  node_http_router["HTTP router<br/>[mod.rs]"]
  node_player_api["Player endpoints<br/>[romm.rs]"]
  node_admin_api["Admin endpoints"]
  node_session_api["Session endpoints<br/>[sessions.rs]"]
end

subgraph group_library["Library workflows"]
  node_library_ops["Library operations"]
  node_ingest["Ingest planning"]
  node_integrity["Integrity checks<br/>[integrity.rs]"]
  node_gog["GOG extraction"]
  node_romm["Remote RomM"]
end

subgraph group_identity["Identity and jobs"]
  node_sessions["Session service<br/>[auth.rs]"]
  node_job_registry["Job registry<br/>[job_registry.rs]"]
  node_state["Application state<br/>[state.rs]"]
end

subgraph group_persistence["Persistence and integrations"]
  node_rom_repository["Catalog repository<br/>[read.rs]"]
  node_session_repository["Session repository"]
  node_file_store["Game file store<br/>[file_store.rs]"]
  node_sqlite[("SQLite catalog")]
  node_igdb["IGDB client<br/>[client.rs]"]
  node_igdb_service["IGDB metadata"]
  node_lan["LAN discovery<br/>[lan_discovery.rs]"]
end

node_user(("Library user"))
node_administrator(("Administrator"))
node_remote_igdb["IGDB service"]
node_remote_romm["RomM server"]
node_disk[("Game files")]

node_user -->|"browses"| node_player
node_player -->|"requests"| node_http_router
node_player -->|"renders"| node_player_views
node_admin -->|"requests"| node_http_router
node_admin -->|"dispatches"| node_admin_features
node_admin_features -->|"updates"| node_admin_state
node_http_router -->|"routes to"| node_player_api
node_http_router -->|"routes to"| node_admin_api
node_http_router -->|"routes to"| node_session_api
node_player_api -.->|"reads catalog"| node_rom_repository
node_player_api -.->|"streams downloads"| node_file_store
node_admin_api -.->|"manages library"| node_library_ops
node_admin_api -.->|"checks files"| node_integrity
node_admin_api -.->|"starts imports"| node_gog
node_admin_api -.->|"browses and imports"| node_romm
node_admin_api -.->|"matches metadata"| node_igdb_service
node_admin_api -.->|"tracks jobs"| node_job_registry
node_session_api -.->|"authenticates"| node_sessions
node_sessions -.->|"stores sessions"| node_session_repository
node_library_ops -.->|"plans ingest"| node_ingest
node_library_ops -.->|"updates catalog"| node_rom_repository
node_library_ops -.->|"manages files"| node_file_store
node_rom_repository -.->|"persists catalog"| node_sqlite
node_file_store -->|"reads and writes"| node_disk
node_igdb_service -->|"uses client"| node_igdb
node_igdb -->|"queries"| node_remote_igdb
node_romm -.->|"connects"| node_remote_romm
node_state -.->|"starts discovery"| node_lan

click node_player "https://github.com/lodilorenzo/teatro/blob/main/web/public/main.js"
click node_admin "https://github.com/lodilorenzo/teatro/blob/main/web/admin/main.js"
click node_player_views "https://github.com/lodilorenzo/teatro/blob/main/web/public/views.js"
click node_admin_features "https://github.com/lodilorenzo/teatro/tree/main/web/admin/features"
click node_admin_state "https://github.com/lodilorenzo/teatro/blob/main/web/admin/state.js"
click node_http_router "https://github.com/lodilorenzo/teatro/blob/main/src/api/mod.rs"
click node_player_api "https://github.com/lodilorenzo/teatro/blob/main/src/api/romm.rs"
click node_admin_api "https://github.com/lodilorenzo/teatro/tree/main/src/api/admin"
click node_session_api "https://github.com/lodilorenzo/teatro/blob/main/src/api/sessions.rs"
click node_library_ops "https://github.com/lodilorenzo/teatro/tree/main/src/services/library"
click node_ingest "https://github.com/lodilorenzo/teatro/tree/main/src/services/library/ingest"
click node_integrity "https://github.com/lodilorenzo/teatro/blob/main/src/services/integrity.rs"
click node_gog "https://github.com/lodilorenzo/teatro/tree/main/src/services/gog_import"
click node_romm "https://github.com/lodilorenzo/teatro/tree/main/src/services/romm_source"
click node_sessions "https://github.com/lodilorenzo/teatro/blob/main/src/services/auth.rs"
click node_job_registry "https://github.com/lodilorenzo/teatro/blob/main/src/services/job_registry.rs"
click node_state "https://github.com/lodilorenzo/teatro/blob/main/src/state.rs"
click node_rom_repository "https://github.com/lodilorenzo/teatro/blob/main/src/repositories/roms/read.rs"
click node_session_repository "https://github.com/lodilorenzo/teatro/blob/main/src/repositories/browser_sessions.rs"
click node_file_store "https://github.com/lodilorenzo/teatro/blob/main/src/storage/file_store.rs"
click node_igdb "https://github.com/lodilorenzo/teatro/blob/main/src/services/igdb/client.rs"
click node_igdb_service "https://github.com/lodilorenzo/teatro/tree/main/src/services/igdb"
click node_lan "https://github.com/lodilorenzo/teatro/blob/main/src/services/lan_discovery.rs"

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_player,node_admin,node_player_views,node_admin_features,node_admin_state,node_user toneBlue
class node_http_router,node_player_api,node_admin_api,node_session_api,node_disk toneAmber
class node_library_ops,node_ingest,node_integrity,node_gog,node_romm,node_remote_romm toneMint
class node_sessions,node_job_registry,node_state toneRose
class node_rom_repository,node_session_repository,node_file_store,node_sqlite,node_igdb,node_igdb_service,node_lan,node_administrator,node_remote_igdb toneIndigo
```

## Components

### Web interfaces

- [Player browser](https://github.com/lodilorenzo/teatro/blob/main/web/public/main.js): `web/public/main.js`
- [Admin browser](https://github.com/lodilorenzo/teatro/blob/main/web/admin/main.js): `web/admin/main.js`
- [Catalog views](https://github.com/lodilorenzo/teatro/blob/main/web/public/views.js): `web/public/views.js`
- [Admin features](https://github.com/lodilorenzo/teatro/tree/main/web/admin/features): `web/admin/features`
- [Admin state](https://github.com/lodilorenzo/teatro/blob/main/web/admin/state.js): `web/admin/state.js`

### HTTP API

- [HTTP router](https://github.com/lodilorenzo/teatro/blob/main/src/api/mod.rs): `src/api/mod.rs`
- [Player endpoints](https://github.com/lodilorenzo/teatro/blob/main/src/api/romm.rs): `src/api/romm.rs`
- [Admin endpoints](https://github.com/lodilorenzo/teatro/tree/main/src/api/admin): `src/api/admin`
- [Session endpoints](https://github.com/lodilorenzo/teatro/blob/main/src/api/sessions.rs): `src/api/sessions.rs`

### Library workflows

- [Library operations](https://github.com/lodilorenzo/teatro/tree/main/src/services/library): `src/services/library`
- [Ingest planning](https://github.com/lodilorenzo/teatro/tree/main/src/services/library/ingest): `src/services/library/ingest`
- [Integrity checks](https://github.com/lodilorenzo/teatro/blob/main/src/services/integrity.rs): `src/services/integrity.rs`
- [GOG extraction](https://github.com/lodilorenzo/teatro/tree/main/src/services/gog_import): `src/services/gog_import`
- [Remote RomM](https://github.com/lodilorenzo/teatro/tree/main/src/services/romm_source): `src/services/romm_source`

### Identity and jobs

- [Session service](https://github.com/lodilorenzo/teatro/blob/main/src/services/auth.rs): `src/services/auth.rs`
- [Job registry](https://github.com/lodilorenzo/teatro/blob/main/src/services/job_registry.rs): `src/services/job_registry.rs`
- [Application state](https://github.com/lodilorenzo/teatro/blob/main/src/state.rs): `src/state.rs`

### Persistence and integrations

- [Catalog repository](https://github.com/lodilorenzo/teatro/blob/main/src/repositories/roms/read.rs): `src/repositories/roms/read.rs`
- [Session repository](https://github.com/lodilorenzo/teatro/blob/main/src/repositories/browser_sessions.rs): `src/repositories/browser_sessions.rs`
- [Game file store](https://github.com/lodilorenzo/teatro/blob/main/src/storage/file_store.rs): `src/storage/file_store.rs`
- **SQLite catalog**
- [IGDB client](https://github.com/lodilorenzo/teatro/blob/main/src/services/igdb/client.rs): `src/services/igdb/client.rs`
- [IGDB metadata](https://github.com/lodilorenzo/teatro/tree/main/src/services/igdb): `src/services/igdb`
- [LAN discovery](https://github.com/lodilorenzo/teatro/blob/main/src/services/lan_discovery.rs): `src/services/lan_discovery.rs`

### Other components

- **Library user**
- **Administrator**
- **IGDB service**
- **RomM server**
- **Game files**

## Connections

- Library user → Player browser: browses (evidence: `README.md`)
- Player browser → HTTP router: requests (evidence: `web/public/main.js`)
- Player browser → Catalog views: renders (evidence: `web/public/main.js`)
- Admin browser → HTTP router: requests (evidence: `web/admin/main.js`)
- Admin browser → Admin features: dispatches (evidence: `web/admin/main.js`)
- Admin features → Admin state: updates (evidence: `web/admin/features/romm-source.js`)
- HTTP router → Player endpoints: routes to (evidence: `src/api/mod.rs`)
- HTTP router → Admin endpoints: routes to (evidence: `src/api/mod.rs`)
- HTTP router → Session endpoints: routes to (evidence: `src/api/mod.rs`)
- Player endpoints → Catalog repository: reads catalog
- Player endpoints → Game file store: streams downloads
- Admin endpoints → Library operations: manages library
- Admin endpoints → Integrity checks: checks files
- Admin endpoints → GOG extraction: starts imports
- Admin endpoints → Remote RomM: browses and imports
- Admin endpoints → IGDB metadata: matches metadata
- Admin endpoints → Job registry: tracks jobs
- Session endpoints → Session service: authenticates
- Session service → Session repository: stores sessions
- Library operations → Ingest planning: plans ingest
- Library operations → Catalog repository: updates catalog
- Library operations → Game file store: manages files
- Catalog repository → SQLite catalog: persists catalog
- Game file store → Game files: reads and writes (evidence: `src/storage/file_store.rs`)
- IGDB metadata → IGDB client: uses client (evidence: `src/services/igdb/client.rs`)
- IGDB client → IGDB service: queries (evidence: `src/services/igdb/client.rs`)
- Remote RomM → RomM server: connects
- Application state → LAN discovery: starts discovery
