# ramsesoriginal/lorenzo architecture

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

- Interactive diagram: https://gitdiagram.com/ramsesoriginal/lorenzo
- Repository: https://github.com/ramsesoriginal/lorenzo

## Overview

Lorenzo is a multi-tenant worldbuilding and campaign-bookkeeping platform: users manage libraries and entries through web, mobile, CLI, and Discord clients, with the API as the source of truth. The map groups the documented client surfaces around the API and its domain capabilities, then shows selected internals and the CLI import workflow. Client-to-API and API-to-PostgreSQL links follow the README; internal links are limited to relationships visible in the sampled source or SOURCE INDEX, so unsampled domain wiring is not inferred.

Main entry points: [`apps/api/src/lorenzo_api/main.py`](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/main.py) (REST API), [`apps/cli/src/lorenzo_cli/main.py`](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/cli/src/lorenzo_cli/main.py) (Lorenzo CLI), [`apps/account-hub/src/lib/api.ts`](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/account-hub/src/lib/api.ts) (Account hub), [`apps/inventory-web/src/components/Board/dragDrop.ts`](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/inventory-web/src/components/Board/dragDrop.ts) (Inventory web)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_account["Account hub<br/>[api.ts]"]
  node_inventory["Inventory web<br/>[dragDrop.ts]"]
  node_beings["Beings app<br/>[renderer.ts]"]
  node_calendars["Calendars app<br/>[session.ts]"]
  node_sessions["Sessions app<br/>[context.ts]"]
  node_writing["Writing app<br/>[review.ts]"]
  node_maps["Maps app<br/>[previews.ts]"]
  node_social["Social app<br/>[auth.ts]"]
  node_mobile["Inventory Android"]
  node_ios["Inventory iOS<br/>[Views.swift]"]
  node_bot["Discord bot<br/>[lorenzo-client.ts]"]
end

subgraph group_api["API service"]
  node_api["REST API<br/>[main.py]"]
  node_config["API configuration<br/>[config.py]"]
  node_errors["API exceptions<br/>[exceptions.py]"]
end

subgraph group_domain["World and content"]
  node_entities["Entity routes<br/>[entities.py]"]
  node_models[("Domain models")]
end

subgraph group_repositories["Repository publishing"]
  node_repo_routes["Repository routes<br/>[repositories.py]"]
  node_repo_preview_route["Preview routes"]
  node_repo_preview["Preview rules"]
  node_repo_schemas["Repository schemas<br/>[repositories.py]"]
  node_profile_schemas["Profile schemas"]
  node_fanout["Release fanout<br/>[release_fanout.py]"]
end

subgraph group_cli["CLI import workflow"]
  node_cli["Lorenzo CLI<br/>[main.py]"]
  node_transport["API client transport<br/>[transport.py]"]
  node_importer["Import planning"]
end

node_user(("Game makers"))
node_postgres[("PostgreSQL")]

node_user -->|"manages accounts"| node_account
node_user -->|"manages items"| node_inventory
node_user -->|"reads and edits"| node_beings
node_user -->|"manages calendars"| node_calendars
node_user -->|"prepares sessions"| node_sessions
node_user -->|"writes manuscripts"| node_writing
node_user -->|"explores maps"| node_maps
node_user -->|"manages relationships"| node_social
node_user -->|"carries inventory"| node_mobile
node_user -->|"carries inventory"| node_ios
node_user -->|"uses Discord"| node_bot
node_user -->|"runs bulk work"| node_cli
node_account -->|"uses API"| node_api
node_inventory -->|"uses API"| node_api
node_beings -->|"uses API"| node_api
node_calendars -->|"uses API"| node_api
node_sessions -->|"uses API"| node_api
node_writing -->|"uses API"| node_api
node_maps -->|"uses API"| node_api
node_social -->|"uses API"| node_api
node_mobile -->|"uses API"| node_api
node_ios -->|"uses API"| node_api
node_bot -->|"uses API"| node_api
node_cli -->|"uses transport"| node_transport
node_cli -->|"runs import"| node_importer
node_importer -->|"calls API"| node_transport
node_api -->|"loads settings"| node_config
node_api -->|"uses exceptions"| node_errors
node_api -->|"registers routes"| node_entities
node_api -->|"registers routes"| node_repo_routes
node_api -->|"registers routes"| node_repo_preview_route
node_api -->|"starts sweeping"| node_fanout
node_api -->|"persists source"| node_postgres
node_repo_preview_route -->|"reads preview"| node_repo_preview
node_repo_schemas -->|"imports types"| node_profile_schemas

click node_account "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/account-hub/src/lib/api.ts"
click node_inventory "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/inventory-web/src/components/Board/dragDrop.ts"
click node_beings "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/beings/src/components/BeingPage/renderer.ts"
click node_calendars "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/calendars/src/lib/session.ts"
click node_sessions "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/sessions/src/lib/context.ts"
click node_writing "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/writing/src/lib/review.ts"
click node_maps "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/maps/src/lib/previews.ts"
click node_social "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/social/src/lib/auth.ts"
click node_mobile "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/inventory-mobile/app/src/main/kotlin/io/lorenzo/inventory/data/InventoryRepository.kt"
click node_ios "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/inventory-ios/Sources/App/Views.swift"
click node_bot "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/loot-bot/src/lorenzo-client.ts"
click node_cli "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/cli/src/lorenzo_cli/main.py"
click node_transport "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/cli/src/lorenzo_cli/client/transport.py"
click node_importer "https://github.com/ramsesoriginal/lorenzo/tree/main/apps/cli/src/lorenzo_cli/importer"
click node_api "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/main.py"
click node_config "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/config.py"
click node_errors "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/exceptions.py"
click node_entities "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/routers/entities.py"
click node_models "https://github.com/ramsesoriginal/lorenzo/tree/main/apps/api/src/lorenzo_api/models"
click node_repo_routes "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/routers/repositories.py"
click node_repo_preview_route "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/routers/repository_preview.py"
click node_repo_preview "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/repository_preview.py"
click node_repo_schemas "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/schemas/repositories.py"
click node_profile_schemas "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/schemas/repository_profiles.py"
click node_fanout "https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/release_fanout.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_account,node_inventory,node_beings,node_calendars,node_sessions,node_writing,node_maps,node_social,node_mobile,node_ios,node_bot toneBlue
class node_api,node_config,node_errors,node_postgres toneAmber
class node_entities,node_models toneMint
class node_repo_routes,node_repo_preview_route,node_repo_preview,node_repo_schemas,node_profile_schemas,node_fanout toneRose
class node_cli,node_transport,node_importer,node_user toneIndigo
```

## Components

### User clients

- [Account hub](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/account-hub/src/lib/api.ts): `apps/account-hub/src/lib/api.ts`
- [Inventory web](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/inventory-web/src/components/Board/dragDrop.ts): `apps/inventory-web/src/components/Board/dragDrop.ts`
- [Beings app](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/beings/src/components/BeingPage/renderer.ts): `apps/beings/src/components/BeingPage/renderer.ts`
- [Calendars app](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/calendars/src/lib/session.ts): `apps/calendars/src/lib/session.ts`
- [Sessions app](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/sessions/src/lib/context.ts): `apps/sessions/src/lib/context.ts`
- [Writing app](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/writing/src/lib/review.ts): `apps/writing/src/lib/review.ts`
- [Maps app](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/maps/src/lib/previews.ts): `apps/maps/src/lib/previews.ts`
- [Social app](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/social/src/lib/auth.ts): `apps/social/src/lib/auth.ts`
- [Inventory Android](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/inventory-mobile/app/src/main/kotlin/io/lorenzo/inventory/data/InventoryRepository.kt): `apps/inventory-mobile/app/src/main/kotlin/io/lorenzo/inventory/data/InventoryRepository.kt`
- [Inventory iOS](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/inventory-ios/Sources/App/Views.swift): `apps/inventory-ios/Sources/App/Views.swift`
- [Discord bot](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/loot-bot/src/lorenzo-client.ts): `apps/loot-bot/src/lorenzo-client.ts`

### API service

- [REST API](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/main.py): `apps/api/src/lorenzo_api/main.py`
- [API configuration](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/config.py): `apps/api/src/lorenzo_api/config.py`
- [API exceptions](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/exceptions.py): `apps/api/src/lorenzo_api/exceptions.py`

### World and content

- [Entity routes](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/routers/entities.py): `apps/api/src/lorenzo_api/routers/entities.py`
- [Domain models](https://github.com/ramsesoriginal/lorenzo/tree/main/apps/api/src/lorenzo_api/models): `apps/api/src/lorenzo_api/models`

### Repository publishing

- [Repository routes](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/routers/repositories.py): `apps/api/src/lorenzo_api/routers/repositories.py`
- [Preview routes](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/routers/repository_preview.py): `apps/api/src/lorenzo_api/routers/repository_preview.py`
- [Preview rules](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/repository_preview.py): `apps/api/src/lorenzo_api/repository_preview.py`
- [Repository schemas](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/schemas/repositories.py): `apps/api/src/lorenzo_api/schemas/repositories.py`
- [Profile schemas](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/schemas/repository_profiles.py): `apps/api/src/lorenzo_api/schemas/repository_profiles.py`
- [Release fanout](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/api/src/lorenzo_api/release_fanout.py): `apps/api/src/lorenzo_api/release_fanout.py`

### CLI import workflow

- [Lorenzo CLI](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/cli/src/lorenzo_cli/main.py): `apps/cli/src/lorenzo_cli/main.py`
- [API client transport](https://github.com/ramsesoriginal/lorenzo/blob/main/apps/cli/src/lorenzo_cli/client/transport.py): `apps/cli/src/lorenzo_cli/client/transport.py`
- [Import planning](https://github.com/ramsesoriginal/lorenzo/tree/main/apps/cli/src/lorenzo_cli/importer): `apps/cli/src/lorenzo_cli/importer`

### Other components

- **Game makers**
- **PostgreSQL**

## Connections

- Game makers → Account hub: manages accounts
- Game makers → Inventory web: manages items
- Game makers → Beings app: reads and edits
- Game makers → Calendars app: manages calendars
- Game makers → Sessions app: prepares sessions
- Game makers → Writing app: writes manuscripts
- Game makers → Maps app: explores maps
- Game makers → Social app: manages relationships
- Game makers → Inventory Android: carries inventory
- Game makers → Inventory iOS: carries inventory
- Game makers → Discord bot: uses Discord
- Game makers → Lorenzo CLI: runs bulk work
- Account hub → REST API: uses API
- Inventory web → REST API: uses API
- Beings app → REST API: uses API
- Calendars app → REST API: uses API
- Sessions app → REST API: uses API
- Writing app → REST API: uses API
- Maps app → REST API: uses API
- Social app → REST API: uses API
- Inventory Android → REST API: uses API
- Inventory iOS → REST API: uses API
- Discord bot → REST API: uses API
- Lorenzo CLI → API client transport: uses transport (evidence: `apps/cli/src/lorenzo_cli/main.py`)
- Lorenzo CLI → Import planning: runs import (evidence: `apps/cli/src/lorenzo_cli/main.py`)
- Import planning → API client transport: calls API (evidence: `apps/cli/src/lorenzo_cli/importer/apply.py`)
- REST API → API configuration: loads settings (evidence: `apps/api/src/lorenzo_api/main.py`)
- REST API → API exceptions: uses exceptions (evidence: `apps/api/src/lorenzo_api/main.py`)
- REST API → Entity routes: registers routes (evidence: `apps/api/src/lorenzo_api/main.py`)
- REST API → Repository routes: registers routes (evidence: `apps/api/src/lorenzo_api/main.py`)
- REST API → Preview routes: registers routes (evidence: `apps/api/src/lorenzo_api/main.py`)
- REST API → Release fanout: starts sweeping (evidence: `apps/api/src/lorenzo_api/main.py`)
- REST API → PostgreSQL: persists source
- Preview routes → Preview rules: reads preview (evidence: `apps/api/src/lorenzo_api/routers/repository_preview.py`)
- Repository schemas → Profile schemas: imports types (evidence: `apps/api/src/lorenzo_api/schemas/repositories.py`)