# lucifron28/provision architecture

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

- Interactive diagram: https://gitdiagram.com/lucifron28/provision
- Repository: https://github.com/lucifron28/provision

## Overview

Provision is a household pantry and food-inventory product: people use a native iOS app to scan and manage groceries, then track batches, expiration, consumption, and shopping through a FastAPI service. The app also exposes recipe discovery and shopping, meal planning, analytics, food-safety, and household-management capabilities. The excerpts show API-client and grocery-session behavior, plus the inventory data model; several feature branches are represented from the repository tree and README, so their internal call paths are not inferred.

Main entry points: [`frontend/frontend/Core/APIClient.swift`](https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/APIClient.swift) (API client), [`backend/app/core/database.py`](https://github.com/lucifron28/provision/blob/main/backend/app/core/database.py) (SQL database), [`backend/app/api/v1/endpoints/sessions.py`](https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/sessions.py) (Grocery sessions), [`backend/app/models/batch.py`](https://github.com/lucifron28/provision/blob/main/backend/app/models/batch.py) (Inventory batches)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["iOS Client"]
  node_ios["SwiftUI app<br/>[ContentView.swift]"]
  node_scan["Grocery intake"]
  node_workflow["Workflow service"]
  node_clientapi["API client<br/>[APIClient.swift]"]
  node_cache[("Offline cache")]
  node_keychain[("Credential storage")]
end

subgraph group_api["Backend API"]
  node_server["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_sessions["Grocery sessions<br/>[sessions.py]"]
  node_inventory_api["Inventory and products<br/>[inventory.py]"]
  node_shopping_api["Shopping lists<br/>[shopping.py]"]
  node_analytics["Food analytics<br/>[analytics.py]"]
  node_recipes_api["Recipe endpoints<br/>[recipes.py]"]
end

subgraph group_food["Pantry Domain"]
  node_batch["Inventory batches<br/>[batch.py]"]
  node_product["Products<br/>[product.py]"]
  node_session_model["Session records<br/>[session.py]"]
  node_event["Inventory ledger<br/>[event.py]"]
end

subgraph group_recipes["Recipes and Planning"]
  node_recipe_shopping["Recipe shopping<br/>[recipe_shopping.py]"]
  node_meal_plans["Meal planning<br/>[meal_plans.py]"]
  node_ai_recipes["AI recipes<br/>[ai_recipes.py]"]
end

subgraph group_platform["Persistence and Security"]
  node_database[("SQL database<br/>[database.py]")]
  node_household["Household records<br/>[household.py]"]
  node_security["Token security<br/>[security.py]"]
end

node_person(("Household member"))

node_person -->|"uses"| node_ios
node_ios -->|"requests data"| node_clientapi
node_scan -->|"submits intake"| node_clientapi
node_workflow -->|"delegates requests"| node_clientapi
node_clientapi -->|"caches responses"| node_cache
node_clientapi -->|"calls REST API"| node_server
node_server -.->|"registers routes"| node_auth
node_auth -->|"uses sessions"| node_database
node_auth -->|"uses token security"| node_security
node_sessions -->|"uses sessions"| node_database
node_sessions -->|"reads and writes"| node_session_model
node_sessions -->|"creates batches"| node_batch
node_sessions -->|"records intake"| node_event
node_batch -->|"references product"| node_product
node_batch -->|"references session"| node_session_model
node_event -->|"references batch"| node_batch
node_inventory_api -.->|"uses persistence"| node_database
node_shopping_api -.->|"uses persistence"| node_database
node_analytics -.->|"queries records"| node_database
node_recipes_api -.->|"uses service"| node_recipe_shopping
node_recipes_api -.->|"uses service"| node_meal_plans
node_recipes_api -.->|"uses service"| node_ai_recipes
node_household -.->|"stored in"| node_database
node_keychain -.->|"stores credentials for"| node_clientapi

click node_ios "https://github.com/lucifron28/provision/blob/main/frontend/frontend/ContentView.swift"
click node_scan "https://github.com/lucifron28/provision/blob/main/frontend/frontend/ViewModels/ScanViewModel.swift"
click node_workflow "https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/CookWithPipWorkflowService.swift"
click node_clientapi "https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/APIClient.swift"
click node_cache "https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/LocalCacheStore.swift"
click node_server "https://github.com/lucifron28/provision/blob/main/backend/app/main.py"
click node_auth "https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/auth.py"
click node_sessions "https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/sessions.py"
click node_inventory_api "https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/inventory.py"
click node_shopping_api "https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/shopping.py"
click node_analytics "https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/analytics.py"
click node_recipes_api "https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/recipes.py"
click node_recipe_shopping "https://github.com/lucifron28/provision/blob/main/backend/app/services/recipe_shopping.py"
click node_meal_plans "https://github.com/lucifron28/provision/blob/main/backend/app/services/meal_plans.py"
click node_ai_recipes "https://github.com/lucifron28/provision/blob/main/backend/app/services/ai_recipes.py"
click node_batch "https://github.com/lucifron28/provision/blob/main/backend/app/models/batch.py"
click node_product "https://github.com/lucifron28/provision/blob/main/backend/app/models/product.py"
click node_session_model "https://github.com/lucifron28/provision/blob/main/backend/app/models/session.py"
click node_event "https://github.com/lucifron28/provision/blob/main/backend/app/models/event.py"
click node_database "https://github.com/lucifron28/provision/blob/main/backend/app/core/database.py"
click node_household "https://github.com/lucifron28/provision/blob/main/backend/app/models/household.py"
click node_security "https://github.com/lucifron28/provision/blob/main/backend/app/core/security.py"
click node_keychain "https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/KeychainStore.swift"

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_ios,node_scan,node_workflow,node_clientapi,node_cache,node_keychain toneBlue
class node_server,node_auth,node_sessions,node_inventory_api,node_shopping_api,node_analytics,node_recipes_api toneAmber
class node_batch,node_product,node_session_model,node_event toneMint
class node_recipe_shopping,node_meal_plans,node_ai_recipes toneRose
class node_database,node_household,node_security,node_person toneIndigo
```

## Components

### iOS Client

- [SwiftUI app](https://github.com/lucifron28/provision/blob/main/frontend/frontend/ContentView.swift): `frontend/frontend/ContentView.swift`
- [Grocery intake](https://github.com/lucifron28/provision/blob/main/frontend/frontend/ViewModels/ScanViewModel.swift): `frontend/frontend/ViewModels/ScanViewModel.swift`
- [Workflow service](https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/CookWithPipWorkflowService.swift): `frontend/frontend/Core/CookWithPipWorkflowService.swift`
- [API client](https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/APIClient.swift): `frontend/frontend/Core/APIClient.swift`
- [Offline cache](https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/LocalCacheStore.swift): `frontend/frontend/Core/LocalCacheStore.swift`
- [Credential storage](https://github.com/lucifron28/provision/blob/main/frontend/frontend/Core/KeychainStore.swift): `frontend/frontend/Core/KeychainStore.swift`

### Backend API

- [FastAPI app](https://github.com/lucifron28/provision/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Grocery sessions](https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/sessions.py): `backend/app/api/v1/endpoints/sessions.py`
- [Inventory and products](https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/inventory.py): `backend/app/api/v1/endpoints/inventory.py`
- [Shopping lists](https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/shopping.py): `backend/app/api/v1/endpoints/shopping.py`
- [Food analytics](https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/analytics.py): `backend/app/api/v1/endpoints/analytics.py`
- [Recipe endpoints](https://github.com/lucifron28/provision/blob/main/backend/app/api/v1/endpoints/recipes.py): `backend/app/api/v1/endpoints/recipes.py`

### Pantry Domain

- [Inventory batches](https://github.com/lucifron28/provision/blob/main/backend/app/models/batch.py): `backend/app/models/batch.py`
- [Products](https://github.com/lucifron28/provision/blob/main/backend/app/models/product.py): `backend/app/models/product.py`
- [Session records](https://github.com/lucifron28/provision/blob/main/backend/app/models/session.py): `backend/app/models/session.py`
- [Inventory ledger](https://github.com/lucifron28/provision/blob/main/backend/app/models/event.py): `backend/app/models/event.py`

### Recipes and Planning

- [Recipe shopping](https://github.com/lucifron28/provision/blob/main/backend/app/services/recipe_shopping.py): `backend/app/services/recipe_shopping.py`
- [Meal planning](https://github.com/lucifron28/provision/blob/main/backend/app/services/meal_plans.py): `backend/app/services/meal_plans.py`
- [AI recipes](https://github.com/lucifron28/provision/blob/main/backend/app/services/ai_recipes.py): `backend/app/services/ai_recipes.py`

### Persistence and Security

- [SQL database](https://github.com/lucifron28/provision/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Household records](https://github.com/lucifron28/provision/blob/main/backend/app/models/household.py): `backend/app/models/household.py`
- [Token security](https://github.com/lucifron28/provision/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### Other components

- **Household member**

## Connections

- Household member → SwiftUI app: uses
- SwiftUI app → API client: requests data (evidence: `frontend/frontend/Core/APIClient.swift`)
- Grocery intake → API client: submits intake (evidence: `frontend/frontend/Core/APIClient.swift`)
- Workflow service → API client: delegates requests (evidence: `frontend/frontend/Core/CookWithPipWorkflowService.swift`)
- API client → Offline cache: caches responses (evidence: `frontend/frontend/Core/APIClient.swift`)
- API client → FastAPI app: calls REST API
- FastAPI app → Authentication: registers routes
- Authentication → SQL database: uses sessions (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Authentication → Token security: uses token security (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Grocery sessions → SQL database: uses sessions (evidence: `backend/app/api/v1/endpoints/sessions.py`)
- Grocery sessions → Session records: reads and writes (evidence: `backend/app/api/v1/endpoints/sessions.py`)
- Grocery sessions → Inventory batches: creates batches (evidence: `backend/app/api/v1/endpoints/sessions.py`)
- Grocery sessions → Inventory ledger: records intake (evidence: `backend/app/api/v1/endpoints/sessions.py`)
- Inventory batches → Products: references product (evidence: `backend/app/models/batch.py`)
- Inventory batches → Session records: references session (evidence: `backend/app/models/batch.py`)
- Inventory ledger → Inventory batches: references batch (evidence: `backend/app/models/event.py`)
- Inventory and products → SQL database: uses persistence
- Shopping lists → SQL database: uses persistence
- Food analytics → SQL database: queries records
- Recipe endpoints → Recipe shopping: uses service
- Recipe endpoints → Meal planning: uses service
- Recipe endpoints → AI recipes: uses service
- Household records → SQL database: stored in
- Credential storage → API client: stores credentials for