# jackthomasanderson/glou-server architecture

> Architecture diagram of the GitHub repository jackthomasanderson/glou-server, 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/jackthomasanderson/glou-server
- Repository: https://github.com/jackthomasanderson/glou-server

## Overview

Glou is a self-hosted collection manager for wine, spirits, sparkling wine, and cigars. Users register, then add and manage shared inventory through manual entry, CSV import, or label scanning; they can organize cellars and collections, record tastings, and use analytics, maturity alerts, consumption planning, and wishlist budgets. The web app communicates with an Express API whose routers own request handling and delegate selected work to services backed by PostgreSQL. The README documents further capabilities whose implementation paths are present but whose internal wiring was not sampled; those branches are shown without guessed call chains.

Main entry points: [`web/lib/api.ts`](https://github.com/jackthomasanderson/glou-server/blob/dev/web/lib/api.ts) (API client), [`api/src/lib/prisma.ts`](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/lib/prisma.ts) (PostgreSQL), [`api/src/app.ts`](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/app.ts) (Feature routers), [`api/src/routes/auth.router.ts`](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/auth.router.ts) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_browser["Web application<br/>[layout.tsx]"]
  node_auth_ui["Authentication UI<br/>[LoginForm.tsx]"]
  node_inventory_ui["Inventory UI"]
  node_onboarding["Intake choices"]
  node_offline_sync["Offline sync<br/>[syncEngine.ts]"]
  node_domain_ui["Collection features"]
  node_analytics_ui["Analytics views"]
  node_tasting_ui["Tasting and pairing"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and domain"]
  node_auth_routes["Authentication routes<br/>[auth.router.ts]"]
  node_inventory_routes["Inventory routes"]
  node_app_routes["Feature routers<br/>[app.ts]"]
  node_inventory_service["Inventory domain"]
  node_auth_service["Identity and sessions<br/>[auth.service.ts]"]
  node_scan_import["Scan and import<br/>[scan.router.ts]"]
  node_search["Product search<br/>[search.router.ts]"]
  node_domain_services["Domain services"]
  node_alerts["Maturity alerts<br/>[alert.service.ts]"]
  node_auth_middleware["Authentication middleware<br/>[auth.middleware.ts]"]
end

subgraph group_ops["Administration and data"]
  node_admin_routes["Admin routes<br/>[admin.router.ts]"]
  node_backup["Backup service<br/>[backup.service.ts]"]
  node_audit["Audit logging<br/>[audit.service.ts]"]
end

subgraph group_state["Persistence and offline"]
  node_database[("PostgreSQL<br/>[prisma.ts]")]
  node_offline_db[("Offline cache<br/>[db.ts]")]
end

node_user(("Collector"))
node_external_vision["Vision service"]

node_user -->|"uses"| node_browser
node_browser -.->|"offers sign-in"| node_auth_ui
node_browser -.->|"manages assets"| node_inventory_ui
node_onboarding -->|"chooses scan"| node_scan_import
node_inventory_ui -.->|"requests data"| node_api_client
node_auth_ui -.->|"submits credentials"| node_api_client
node_api_client -.->|"calls API"| node_auth_routes
node_api_client -.->|"calls API"| node_inventory_routes
node_auth_routes -->|"delegates"| node_auth_service
node_auth_routes -->|"uses"| node_auth_middleware
node_auth_service -->|"reads and writes"| node_database
node_auth_service -->|"records events"| node_audit
node_inventory_routes -.->|"protects routes"| node_auth_middleware
node_inventory_routes -.->|"delegates"| node_inventory_service
node_inventory_service -->|"reads and writes"| node_database
node_inventory_service -->|"triggers alerts"| node_alerts
node_app_routes -->|"mounts routes"| node_auth_routes
node_app_routes -->|"mounts routes"| node_inventory_routes
node_app_routes -->|"mounts routes"| node_admin_routes
node_app_routes -->|"mounts routes"| node_search
node_domain_ui -.->|"requests features"| node_api_client
node_analytics_ui -.->|"requests insights"| node_api_client
node_tasting_ui -.->|"requests tastings"| node_api_client
node_offline_sync -->|"queues mutations"| node_offline_db
node_offline_sync -.->|"syncs changes"| node_api_client
node_scan_import -.->|"requests recognition"| node_external_vision
node_admin_routes -->|"delegates backups"| node_backup
node_admin_routes -->|"queries administration data"| node_database
node_audit -->|"writes audit records"| node_database
node_domain_services -.->|"reads domain data"| node_database
node_alerts -.->|"reads domain data"| node_database

click node_browser "https://github.com/jackthomasanderson/glou-server/blob/dev/web/app/layout.tsx"
click node_auth_ui "https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/auth/LoginForm.tsx"
click node_inventory_ui "https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/inventory/InventoryDashboard.tsx"
click node_onboarding "https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/onboarding/steps/IngestionChoiceStep.tsx"
click node_offline_sync "https://github.com/jackthomasanderson/glou-server/blob/dev/web/lib/offline/syncEngine.ts"
click node_domain_ui "https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/cellars/CellarDashboard.tsx"
click node_analytics_ui "https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/analytics/AnalyticsDashboard.tsx"
click node_tasting_ui "https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/tastings/PairingExplorer.tsx"
click node_api_client "https://github.com/jackthomasanderson/glou-server/blob/dev/web/lib/api.ts"
click node_auth_routes "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/auth.router.ts"
click node_inventory_routes "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/inventory.router.ts"
click node_app_routes "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/app.ts"
click node_inventory_service "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/inventory.service.ts"
click node_auth_service "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/auth.service.ts"
click node_scan_import "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/scan.router.ts"
click node_search "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/search.router.ts"
click node_domain_services "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/analytics.service.ts"
click node_alerts "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/alert.service.ts"
click node_admin_routes "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/admin.router.ts"
click node_backup "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/backup.service.ts"
click node_audit "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/audit.service.ts"
click node_auth_middleware "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/middleware/auth.middleware.ts"
click node_database "https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/lib/prisma.ts"
click node_offline_db "https://github.com/jackthomasanderson/glou-server/blob/dev/web/lib/offline/db.ts"

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_browser,node_auth_ui,node_inventory_ui,node_onboarding,node_offline_sync,node_domain_ui,node_analytics_ui,node_tasting_ui,node_api_client toneBlue
class node_auth_routes,node_inventory_routes,node_app_routes,node_inventory_service,node_auth_service,node_scan_import,node_search,node_domain_services,node_alerts,node_auth_middleware toneAmber
class node_admin_routes,node_backup,node_audit toneMint
class node_database,node_offline_db toneRose
class node_user,node_external_vision toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/jackthomasanderson/glou-server/blob/dev/web/app/layout.tsx): `web/app/layout.tsx`
- [Authentication UI](https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/auth/LoginForm.tsx): `web/components/auth/LoginForm.tsx`
- [Inventory UI](https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/inventory/InventoryDashboard.tsx): `web/components/inventory/InventoryDashboard.tsx`
- [Intake choices](https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/onboarding/steps/IngestionChoiceStep.tsx): `web/components/onboarding/steps/IngestionChoiceStep.tsx`
- [Offline sync](https://github.com/jackthomasanderson/glou-server/blob/dev/web/lib/offline/syncEngine.ts): `web/lib/offline/syncEngine.ts`
- [Collection features](https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/cellars/CellarDashboard.tsx): `web/components/cellars/CellarDashboard.tsx`
- [Analytics views](https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/analytics/AnalyticsDashboard.tsx): `web/components/analytics/AnalyticsDashboard.tsx`
- [Tasting and pairing](https://github.com/jackthomasanderson/glou-server/blob/dev/web/components/tastings/PairingExplorer.tsx): `web/components/tastings/PairingExplorer.tsx`
- [API client](https://github.com/jackthomasanderson/glou-server/blob/dev/web/lib/api.ts): `web/lib/api.ts`

### API and domain

- [Authentication routes](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/auth.router.ts): `api/src/routes/auth.router.ts`
- [Inventory routes](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/inventory.router.ts): `api/src/routes/inventory.router.ts`
- [Feature routers](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/app.ts): `api/src/app.ts`
- [Inventory domain](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/inventory.service.ts): `api/src/services/inventory.service.ts`
- [Identity and sessions](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/auth.service.ts): `api/src/services/auth.service.ts`
- [Scan and import](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/scan.router.ts): `api/src/routes/scan.router.ts`
- [Product search](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/search.router.ts): `api/src/routes/search.router.ts`
- [Domain services](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/analytics.service.ts): `api/src/services/analytics.service.ts`
- [Maturity alerts](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/alert.service.ts): `api/src/services/alert.service.ts`
- [Authentication middleware](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/middleware/auth.middleware.ts): `api/src/middleware/auth.middleware.ts`

### Administration and data

- [Admin routes](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/routes/admin.router.ts): `api/src/routes/admin.router.ts`
- [Backup service](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/backup.service.ts): `api/src/services/backup.service.ts`
- [Audit logging](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/services/audit.service.ts): `api/src/services/audit.service.ts`

### Persistence and offline

- [PostgreSQL](https://github.com/jackthomasanderson/glou-server/blob/dev/api/src/lib/prisma.ts): `api/src/lib/prisma.ts`
- [Offline cache](https://github.com/jackthomasanderson/glou-server/blob/dev/web/lib/offline/db.ts): `web/lib/offline/db.ts`

### Other components

- **Collector**
- **Vision service**

## Connections

- Collector → Web application: uses (evidence: `README.md`)
- Web application → Authentication UI: offers sign-in
- Web application → Inventory UI: manages assets
- Intake choices → Scan and import: chooses scan (evidence: `web/components/onboarding/steps/IngestionChoiceStep.tsx`)
- Inventory UI → API client: requests data
- Authentication UI → API client: submits credentials
- API client → Authentication routes: calls API
- API client → Inventory routes: calls API
- Authentication routes → Identity and sessions: delegates (evidence: `api/src/routes/auth.router.ts`)
- Authentication routes → Authentication middleware: uses (evidence: `api/src/routes/auth.router.ts`)
- Identity and sessions → PostgreSQL: reads and writes (evidence: `api/src/services/auth.service.ts`)
- Identity and sessions → Audit logging: records events (evidence: `api/src/services/auth.service.ts`)
- Inventory routes → Authentication middleware: protects routes
- Inventory routes → Inventory domain: delegates
- Inventory domain → PostgreSQL: reads and writes (evidence: `api/src/services/inventory.service.ts`)
- Inventory domain → Maturity alerts: triggers alerts (evidence: `api/src/services/inventory.service.ts`)
- Feature routers → Authentication routes: mounts routes (evidence: `api/src/app.ts`)
- Feature routers → Inventory routes: mounts routes (evidence: `api/src/app.ts`)
- Feature routers → Admin routes: mounts routes (evidence: `api/src/app.ts`)
- Feature routers → Product search: mounts routes (evidence: `api/src/app.ts`)
- Collection features → API client: requests features
- Analytics views → API client: requests insights
- Tasting and pairing → API client: requests tastings
- Offline sync → Offline cache: queues mutations (evidence: `web/lib/offline/syncEngine.ts`)
- Offline sync → API client: syncs changes
- Scan and import → Vision service: requests recognition
- Admin routes → Backup service: delegates backups (evidence: `api/src/routes/admin.router.ts`)
- Admin routes → PostgreSQL: queries administration data (evidence: `api/src/routes/admin.router.ts`)
- Audit logging → PostgreSQL: writes audit records (evidence: `api/src/services/audit.service.ts`)
- Domain services → PostgreSQL: reads domain data
- Maturity alerts → PostgreSQL: reads domain data
