# scotchlabs/inventory architecture

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

- Interactive diagram: https://gitdiagram.com/scotchlabs/inventory
- Repository: https://github.com/scotchlabs/inventory

## Overview

This is a web-based inventory management application: users browse and search assets, filter by location and category, and administrators can add, edit, or delete inventory items. The frontend calls a FastAPI backend; backend routes enforce user authorization and access PostgreSQL-backed models. File uploads are handled separately, stored locally in development or in S3 in production, and exposed as file metadata. The graph preserves the documented and indexed inventory, identity, and file capabilities. Some inventory and admin implementation details are unsampled, so their internal links are omitted where the evidence does not establish a call.

Main entry points: [`backend/app/inventory/routes/asset.py`](https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/routes/asset.py) (Inventory routes), [`backend/app/app.py`](https://github.com/scotchlabs/inventory/blob/main/backend/app/app.py) (FastAPI app), [`backend/app/db/__init__.py`](https://github.com/scotchlabs/inventory/blob/main/backend/app/db/__init__.py) (DB session), [`backend/app/files/routes.py`](https://github.com/scotchlabs/inventory/blob/main/backend/app/files/routes.py) (File routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_web_app["Web app<br/>[App.tsx]"]
  node_public_inventory["Public inventory<br/>[Public.tsx]"]
  node_admin_ui["Admin UI<br/>[Admin.tsx]"]
  node_add_item["Add item<br/>[AddItem.tsx]"]
  node_file_widget["File widget<br/>[Files.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API runtime"]
  node_fastapi["FastAPI app<br/>[app.py]"]
  node_route_auth["Route authorization<br/>[api_route.py]"]
  node_db_session["DB session<br/>[__init__.py]"]
end

subgraph group_inventory["Inventory domain"]
  node_inventory_routes["Inventory routes<br/>[asset.py]"]
  node_category_routes["Category routes<br/>[category.py]"]
  node_location_routes["Location routes<br/>[locations.py]"]
  node_asset_model["Asset model<br/>[asset.py]"]
  node_category_model["Category model<br/>[category.py]"]
  node_location_model["Location model<br/>[location.py]"]
end

subgraph group_identity_files["Identity and files"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_auth_service["Token and auth<br/>[auth.py]"]
  node_user_service["User service<br/>[user.py]"]
  node_file_routes["File routes<br/>[routes.py]"]
  node_file_service["File storage service<br/>[services.py]"]
  node_file_model["File model<br/>[models.py]"]
end

node_visitor(("User"))
node_postgres[("PostgreSQL")]
node_file_storage[("Local files / S3")]

node_visitor -->|"uses"| node_web_app
node_web_app -->|"routes to"| node_public_inventory
node_web_app -->|"routes to"| node_admin_ui
node_admin_ui -->|"uses"| node_public_inventory
node_admin_ui -->|"uses"| node_add_item
node_public_inventory -->|"queries and mutates"| node_api_client
node_add_item -->|"calls"| node_api_client
node_public_inventory -->|"renders"| node_file_widget
node_add_item -->|"uses"| node_file_widget
node_api_client -->|"sends API requests"| node_fastapi
node_fastapi -->|"registers"| node_inventory_routes
node_fastapi -->|"registers"| node_file_routes
node_fastapi -->|"registers"| node_auth_routes
node_inventory_routes -->|"uses router authorization"| node_route_auth
node_file_routes -->|"uses router authorization"| node_route_auth
node_auth_routes -->|"calls"| node_auth_service
node_auth_service -->|"calls"| node_user_service
node_inventory_routes -->|"reads and writes"| node_asset_model
node_inventory_routes -->|"uses"| node_category_routes
node_inventory_routes -->|"uses"| node_location_routes
node_category_routes -->|"reads and writes"| node_category_model
node_location_routes -->|"reads and writes"| node_location_model
node_inventory_routes -->|"uses file operations"| node_file_service
node_file_routes -->|"calls"| node_file_service
node_file_service -->|"creates and queries"| node_file_model
node_file_service -->|"stores uploads"| node_file_storage
node_fastapi -->|"opens request session"| node_db_session
node_inventory_routes -->|"uses"| node_db_session
node_file_routes -->|"uses"| node_db_session
node_auth_service -->|"uses"| node_db_session
node_db_session -->|"connects to"| node_postgres

click node_web_app "https://github.com/scotchlabs/inventory/blob/main/frontend/src/App.tsx"
click node_public_inventory "https://github.com/scotchlabs/inventory/blob/main/frontend/src/pages/Public.tsx"
click node_admin_ui "https://github.com/scotchlabs/inventory/blob/main/frontend/src/pages/Admin.tsx"
click node_add_item "https://github.com/scotchlabs/inventory/blob/main/frontend/src/pages/AddItem.tsx"
click node_file_widget "https://github.com/scotchlabs/inventory/blob/main/frontend/src/components/Files.tsx"
click node_api_client "https://github.com/scotchlabs/inventory/blob/main/frontend/src/api/client.ts"
click node_fastapi "https://github.com/scotchlabs/inventory/blob/main/backend/app/app.py"
click node_auth_routes "https://github.com/scotchlabs/inventory/blob/main/backend/app/users/routes/auth.py"
click node_auth_service "https://github.com/scotchlabs/inventory/blob/main/backend/app/users/services/auth.py"
click node_user_service "https://github.com/scotchlabs/inventory/blob/main/backend/app/users/services/user.py"
click node_route_auth "https://github.com/scotchlabs/inventory/blob/main/backend/app/utils/api_route.py"
click node_inventory_routes "https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/routes/asset.py"
click node_category_routes "https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/routes/category.py"
click node_location_routes "https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/routes/locations.py"
click node_asset_model "https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/models/asset.py"
click node_category_model "https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/models/category.py"
click node_location_model "https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/models/location.py"
click node_file_routes "https://github.com/scotchlabs/inventory/blob/main/backend/app/files/routes.py"
click node_file_service "https://github.com/scotchlabs/inventory/blob/main/backend/app/files/services.py"
click node_file_model "https://github.com/scotchlabs/inventory/blob/main/backend/app/files/models.py"
click node_db_session "https://github.com/scotchlabs/inventory/blob/main/backend/app/db/__init__.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_web_app,node_public_inventory,node_admin_ui,node_add_item,node_file_widget,node_api_client,node_visitor toneBlue
class node_fastapi,node_route_auth,node_db_session,node_postgres,node_file_storage toneAmber
class node_inventory_routes,node_category_routes,node_location_routes,node_asset_model,node_category_model,node_location_model toneMint
class node_auth_routes,node_auth_service,node_user_service,node_file_routes,node_file_service,node_file_model toneRose
```

## Components

### Web application

- [Web app](https://github.com/scotchlabs/inventory/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Public inventory](https://github.com/scotchlabs/inventory/blob/main/frontend/src/pages/Public.tsx): `frontend/src/pages/Public.tsx`
- [Admin UI](https://github.com/scotchlabs/inventory/blob/main/frontend/src/pages/Admin.tsx): `frontend/src/pages/Admin.tsx`
- [Add item](https://github.com/scotchlabs/inventory/blob/main/frontend/src/pages/AddItem.tsx): `frontend/src/pages/AddItem.tsx`
- [File widget](https://github.com/scotchlabs/inventory/blob/main/frontend/src/components/Files.tsx): `frontend/src/components/Files.tsx`
- [API client](https://github.com/scotchlabs/inventory/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API runtime

- [FastAPI app](https://github.com/scotchlabs/inventory/blob/main/backend/app/app.py): `backend/app/app.py`
- [Route authorization](https://github.com/scotchlabs/inventory/blob/main/backend/app/utils/api_route.py): `backend/app/utils/api_route.py`
- [DB session](https://github.com/scotchlabs/inventory/blob/main/backend/app/db/__init__.py): `backend/app/db/__init__.py`

### Inventory domain

- [Inventory routes](https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/routes/asset.py): `backend/app/inventory/routes/asset.py`
- [Category routes](https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/routes/category.py): `backend/app/inventory/routes/category.py`
- [Location routes](https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/routes/locations.py): `backend/app/inventory/routes/locations.py`
- [Asset model](https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/models/asset.py): `backend/app/inventory/models/asset.py`
- [Category model](https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/models/category.py): `backend/app/inventory/models/category.py`
- [Location model](https://github.com/scotchlabs/inventory/blob/main/backend/app/inventory/models/location.py): `backend/app/inventory/models/location.py`

### Identity and files

- [Auth routes](https://github.com/scotchlabs/inventory/blob/main/backend/app/users/routes/auth.py): `backend/app/users/routes/auth.py`
- [Token and auth](https://github.com/scotchlabs/inventory/blob/main/backend/app/users/services/auth.py): `backend/app/users/services/auth.py`
- [User service](https://github.com/scotchlabs/inventory/blob/main/backend/app/users/services/user.py): `backend/app/users/services/user.py`
- [File routes](https://github.com/scotchlabs/inventory/blob/main/backend/app/files/routes.py): `backend/app/files/routes.py`
- [File storage service](https://github.com/scotchlabs/inventory/blob/main/backend/app/files/services.py): `backend/app/files/services.py`
- [File model](https://github.com/scotchlabs/inventory/blob/main/backend/app/files/models.py): `backend/app/files/models.py`

### Other components

- **User**
- **PostgreSQL**
- **Local files / S3**

## Connections

- User → Web app: uses (evidence: `frontend/src/App.tsx`)
- Web app → Public inventory: routes to (evidence: `frontend/src/App.tsx`)
- Web app → Admin UI: routes to (evidence: `frontend/src/App.tsx`)
- Admin UI → Public inventory: uses (evidence: `frontend/src/pages/Admin.tsx`)
- Admin UI → Add item: uses (evidence: `frontend/src/pages/Admin.tsx`)
- Public inventory → API client: queries and mutates (evidence: `frontend/src/pages/Public.tsx`)
- Add item → API client: calls (evidence: `frontend/src/pages/AddItem.tsx`)
- Public inventory → File widget: renders (evidence: `frontend/src/pages/Public.tsx`)
- Add item → File widget: uses (evidence: `frontend/src/pages/AddItem.tsx`)
- API client → FastAPI app: sends API requests (evidence: `frontend/src/api/client.ts`)
- FastAPI app → Inventory routes: registers (evidence: `backend/app/app.py`)
- FastAPI app → File routes: registers (evidence: `backend/app/app.py`)
- FastAPI app → Auth routes: registers (evidence: `backend/app/app.py`)
- Inventory routes → Route authorization: uses router authorization (evidence: `backend/app/inventory/routes/asset.py`)
- File routes → Route authorization: uses router authorization (evidence: `backend/app/files/routes.py`)
- Auth routes → Token and auth: calls (evidence: `backend/app/users/routes/auth.py`)
- Token and auth → User service: calls (evidence: `backend/app/users/services/auth.py`)
- Inventory routes → Asset model: reads and writes (evidence: `backend/app/inventory/routes/asset.py`)
- Inventory routes → Category routes: uses (evidence: `backend/app/inventory/routes/asset.py`)
- Inventory routes → Location routes: uses (evidence: `backend/app/inventory/routes/asset.py`)
- Category routes → Category model: reads and writes (evidence: `backend/app/inventory/routes/category.py`)
- Location routes → Location model: reads and writes (evidence: `backend/app/inventory/routes/locations.py`)
- Inventory routes → File storage service: uses file operations (evidence: `backend/app/inventory/routes/asset.py`)
- File routes → File storage service: calls (evidence: `backend/app/files/routes.py`)
- File storage service → File model: creates and queries (evidence: `backend/app/files/services.py`)
- File storage service → Local files / S3: stores uploads (evidence: `backend/app/files/services.py`)
- FastAPI app → DB session: opens request session (evidence: `backend/app/app.py`)
- Inventory routes → DB session: uses (evidence: `backend/app/inventory/routes/asset.py`)
- File routes → DB session: uses (evidence: `backend/app/files/routes.py`)
- Token and auth → DB session: uses (evidence: `backend/app/users/services/auth.py`)
- DB session → PostgreSQL: connects to (evidence: `backend/app/db/__init__.py`)
