# lorenzopina-dev/gestione_dispensa architecture

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

- Interactive diagram: https://gitdiagram.com/lorenzopina-dev/gestione_dispensa
- Repository: https://github.com/lorenzopina-dev/gestione_dispensa

## Overview

Gestione_dispensa is a family-oriented pantry and grocery-management product. The user workflow spans sign-in and family access, product identification, pantry inventory and expiry tracking, shopping, recipes, nutrition, and notifications; privacy export/erasure are additional user-facing capabilities. The sampled API controllers show service delegation and authorization, and server composition shows PostgreSQL-backed setup. The README documents broader capabilities, but this tree and excerpts do not establish wiring for every service or UI journey, so uncertain links are omitted.

Main entry points: [`apps/web/src/api/client.ts`](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/web/src/api/client.ts) (API client), [`apps/api/src/db/postgres-client.ts`](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/db/postgres-client.ts) (PostgreSQL), [`apps/api/src/catalog/workflow.ts`](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/catalog/workflow.ts) (Product catalog), [`apps/web/src/App.tsx`](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/web/src/App.tsx) (Web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web app<br/>[App.tsx]"]
  node_webapi["API client<br/>[client.ts]"]
end

subgraph group_api["API and domain"]
  node_auth["Identity and access<br/>[oidc.ts]"]
  node_family["Family and invites<br/>[service.ts]"]
  node_catalog["Product catalog<br/>[workflow.ts]"]
  node_barcode["Barcode lookup"]
  node_inventory["Pantry inventory<br/>[service.ts]"]
  node_shelf["Expiry tracking<br/>[service.ts]"]
  node_shopping["Shopping lists<br/>[service.ts]"]
  node_recipes["Recipes<br/>[service.ts]"]
  node_nutrition["Nutrition<br/>[service.ts]"]
  node_notifications["Notifications<br/>[service.ts]"]
  node_privacy["Privacy controls<br/>[erasure.ts]"]
  node_postgres[("PostgreSQL<br/>[postgres-client.ts]")]
end

subgraph group_async["Background services"]
  node_jobs["Job processing<br/>[worker.ts]"]
  node_scheduler["Job scheduler<br/>[scheduler.ts]"]
  node_queue["Job queue<br/>[queue.ts]"]
end

subgraph group_external["External integrations"]
  node_offlookup["OFF lookup service<br/>[server.ts]"]
end

node_user(("Family member"))
node_offapi["Open Food Facts"]

node_user -->|"uses"| node_webapp
node_webapp -->|"requests data"| node_webapi
node_webapi -->|"authenticates"| node_auth
node_webapi -->|"requests family"| node_family
node_webapi -->|"requests products"| node_catalog
node_webapi -->|"manages stock"| node_inventory
node_webapi -->|"manages lists"| node_shopping
node_webapi -->|"requests recipes"| node_recipes
node_webapi -->|"requests summary"| node_nutrition
node_webapi -->|"reads alerts"| node_notifications
node_webapi -->|"requests privacy"| node_privacy
node_catalog -->|"resolves barcode"| node_barcode
node_barcode -->|"looks up code"| node_offlookup
node_offlookup -->|"queries products"| node_offapi
node_catalog -->|"stores catalog"| node_postgres
node_family -->|"stores family"| node_postgres
node_inventory -->|"stores stock"| node_postgres
node_shelf -->|"reads expiry data"| node_postgres
node_shopping -->|"stores lists"| node_postgres
node_recipes -->|"reads recipes"| node_postgres
node_nutrition -->|"reads nutrition"| node_postgres
node_notifications -->|"stores alerts"| node_postgres
node_privacy -->|"exports or erases"| node_postgres
node_scheduler -->|"enqueues jobs"| node_queue
node_queue -->|"dispatches jobs"| node_jobs

click node_webapp "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/web/src/App.tsx"
click node_webapi "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/web/src/api/client.ts"
click node_auth "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/identity/oidc.ts"
click node_family "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/family/service.ts"
click node_catalog "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/catalog/workflow.ts"
click node_barcode "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/catalog/external-barcode-client.ts"
click node_inventory "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/inventory/service.ts"
click node_shelf "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/shelf-life/service.ts"
click node_shopping "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/shopping/service.ts"
click node_recipes "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/recipes/service.ts"
click node_nutrition "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/nutrition/service.ts"
click node_notifications "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/notifications/service.ts"
click node_privacy "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/privacy/erasure.ts"
click node_postgres "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/db/postgres-client.ts"
click node_offlookup "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/off-lookup/src/server.ts"
click node_jobs "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/worker-core/src/worker.ts"
click node_scheduler "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/scheduler/src/scheduler.ts"
click node_queue "https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/worker-core/src/queue.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_webapp,node_webapi toneBlue
class node_auth,node_family,node_catalog,node_barcode,node_inventory,node_shelf,node_shopping,node_recipes,node_nutrition,node_notifications,node_privacy,node_postgres toneAmber
class node_jobs,node_scheduler,node_queue toneMint
class node_offlookup toneRose
class node_user,node_offapi toneIndigo
```

## Components

### Web experience

- [Web app](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [API client](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/web/src/api/client.ts): `apps/web/src/api/client.ts`

### API and domain

- [Identity and access](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/identity/oidc.ts): `apps/api/src/identity/oidc.ts`
- [Family and invites](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/family/service.ts): `apps/api/src/family/service.ts`
- [Product catalog](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/catalog/workflow.ts): `apps/api/src/catalog/workflow.ts`
- [Barcode lookup](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/catalog/external-barcode-client.ts): `apps/api/src/catalog/external-barcode-client.ts`
- [Pantry inventory](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/inventory/service.ts): `apps/api/src/inventory/service.ts`
- [Expiry tracking](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/shelf-life/service.ts): `apps/api/src/shelf-life/service.ts`
- [Shopping lists](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/shopping/service.ts): `apps/api/src/shopping/service.ts`
- [Recipes](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/recipes/service.ts): `apps/api/src/recipes/service.ts`
- [Nutrition](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/nutrition/service.ts): `apps/api/src/nutrition/service.ts`
- [Notifications](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/notifications/service.ts): `apps/api/src/notifications/service.ts`
- [Privacy controls](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/privacy/erasure.ts): `apps/api/src/privacy/erasure.ts`
- [PostgreSQL](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/apps/api/src/db/postgres-client.ts): `apps/api/src/db/postgres-client.ts`

### Background services

- [Job processing](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/worker-core/src/worker.ts): `services/worker-core/src/worker.ts`
- [Job scheduler](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/scheduler/src/scheduler.ts): `services/scheduler/src/scheduler.ts`
- [Job queue](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/worker-core/src/queue.ts): `services/worker-core/src/queue.ts`

### External integrations

- [OFF lookup service](https://github.com/lorenzopina-dev/gestione_dispensa/blob/main/services/off-lookup/src/server.ts): `services/off-lookup/src/server.ts`

### Other components

- **Family member**
- **Open Food Facts**

## Connections

- Family member → Web app: uses
- Web app → API client: requests data
- API client → Identity and access: authenticates
- API client → Family and invites: requests family
- API client → Product catalog: requests products
- API client → Pantry inventory: manages stock
- API client → Shopping lists: manages lists
- API client → Recipes: requests recipes
- API client → Nutrition: requests summary
- API client → Notifications: reads alerts
- API client → Privacy controls: requests privacy
- Product catalog → Barcode lookup: resolves barcode
- Barcode lookup → OFF lookup service: looks up code
- OFF lookup service → Open Food Facts: queries products
- Product catalog → PostgreSQL: stores catalog
- Family and invites → PostgreSQL: stores family
- Pantry inventory → PostgreSQL: stores stock
- Expiry tracking → PostgreSQL: reads expiry data
- Shopping lists → PostgreSQL: stores lists
- Recipes → PostgreSQL: reads recipes
- Nutrition → PostgreSQL: reads nutrition
- Notifications → PostgreSQL: stores alerts
- Privacy controls → PostgreSQL: exports or erases
- Job scheduler → Job queue: enqueues jobs
- Job queue → Job processing: dispatches jobs