# surag29/inventory-core architecture

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

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

## Overview

InventoryCore is a FastAPI inventory and commerce API. Users register or authenticate, manage carts, and place orders; order creation checks and locks inventory, creates order records, reduces stock, and may raise low-stock alerts. Administrative capabilities include catalog and supplier management, inventory and alert operations, users and roles, audit logs, dashboards, and reports. The graph follows documented router registration and indexed imports; several subsystems are represented at directory level because their implementation excerpts were not provided.

Main entry points: [`app/main.py`](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/main.py) (FastAPI app), [`app/models`](https://github.com/surag29/inventory-core/tree/feature/backend-work/app/models) (Domain models), [`app/services/order_service.py`](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/order_service.py) (Order service), [`app/routes/auth.py`](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/auth.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
  node_security["Token security<br/>[security.py]"]
  node_auth_guard["Identity and roles"]
end

subgraph group_catalog["Catalog and supply"]
  node_catalog_routes["Catalog routes"]
  node_catalog_services["Catalog services"]
  node_supplier_routes["Supplier routes<br/>[supplier.py]"]
  node_supplier_service["Supplier service"]
  node_product_supplier["Product-supplier links"]
end

subgraph group_commerce["Cart and fulfillment"]
  node_cart_routes["Cart item routes<br/>[cart_item.py]"]
  node_cart_service["Cart item service"]
  node_order_routes["Order routes<br/>[order.py]"]
  node_order_service["Order service<br/>[order_service.py]"]
  node_alerts["Low-stock alerts"]
end

subgraph group_platform["Operations and data"]
  node_operations_routes["Inventory operations routes"]
  node_reporting["Dashboard and reports"]
  node_audit["Audit logging"]
  node_models["Domain models"]
  node_database_dep["Database dependency<br/>[database.py]"]
  node_database[("SQL database<br/>[database.py]")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_app
node_app -->|"registers router"| node_auth_routes
node_app -->|"registers routers"| node_catalog_routes
node_app -->|"registers router"| node_supplier_routes
node_app -->|"registers router"| node_product_supplier
node_app -->|"registers routers"| node_operations_routes
node_app -->|"registers router"| node_cart_routes
node_app -->|"registers router"| node_order_routes
node_auth_routes -->|"calls"| node_auth_service
node_auth_routes -->|"creates tokens"| node_security
node_auth_service -->|"hashes and verifies"| node_security
node_auth_service -->|"queries and creates users"| node_models
node_cart_routes -->|"calls"| node_cart_service
node_cart_service -->|"reads and updates cart and stock"| node_models
node_cart_service -->|"records changes"| node_audit
node_order_routes -->|"calls"| node_order_service
node_order_service -->|"reads and writes order and stock"| node_models
node_order_service -->|"creates alerts"| node_alerts
node_order_service -->|"records status changes"| node_audit
node_catalog_routes -->|"calls"| node_catalog_services
node_catalog_services -->|"reads and updates catalog"| node_models
node_supplier_routes -->|"calls"| node_supplier_service
node_supplier_service -.->|"accesses supplier data"| node_models
node_product_supplier -->|"accesses linked records"| node_models
node_operations_routes -.->|"manages inventory and alerts"| node_models
node_reporting -.->|"queries reporting data"| node_models
node_database_dep -->|"opens sessions"| node_database
node_auth_guard -->|"verifies tokens"| node_security
node_auth_guard -->|"loads user"| node_models
node_app -->|"uses health-check dependency"| node_database_dep

click node_app "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/main.py"
click node_auth_routes "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/auth.py"
click node_auth_service "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/auth_service.py"
click node_security "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/core/security.py"
click node_auth_guard "https://github.com/surag29/inventory-core/tree/feature/backend-work/app/dependencies"
click node_catalog_routes "https://github.com/surag29/inventory-core/tree/feature/backend-work/app/routes"
click node_catalog_services "https://github.com/surag29/inventory-core/tree/feature/backend-work/app/services"
click node_supplier_routes "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/supplier.py"
click node_supplier_service "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/supplier_service.py"
click node_product_supplier "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/product_supplier_service.py"
click node_cart_routes "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/cart_item.py"
click node_cart_service "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/cart_item_service.py"
click node_order_routes "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/order.py"
click node_order_service "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/order_service.py"
click node_alerts "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/low_stock_alert_service.py"
click node_operations_routes "https://github.com/surag29/inventory-core/tree/feature/backend-work/app/routes"
click node_reporting "https://github.com/surag29/inventory-core/tree/feature/backend-work/app/services"
click node_audit "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/audit_log_service.py"
click node_models "https://github.com/surag29/inventory-core/tree/feature/backend-work/app/models"
click node_database_dep "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/dependencies/database.py"
click node_database "https://github.com/surag29/inventory-core/blob/feature/backend-work/app/db/database.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_app,node_auth_routes,node_auth_service,node_security,node_auth_guard,node_client toneBlue
class node_catalog_routes,node_catalog_services,node_supplier_routes,node_supplier_service,node_product_supplier toneAmber
class node_cart_routes,node_cart_service,node_order_routes,node_order_service,node_alerts toneMint
class node_operations_routes,node_reporting,node_audit,node_models,node_database_dep,node_database toneRose
```

## Components

### API and access

- [FastAPI app](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/main.py): `app/main.py`
- [Authentication routes](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/auth.py): `app/routes/auth.py`
- [Authentication service](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/auth_service.py): `app/services/auth_service.py`
- [Token security](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/core/security.py): `app/core/security.py`
- [Identity and roles](https://github.com/surag29/inventory-core/tree/feature/backend-work/app/dependencies): `app/dependencies`

### Catalog and supply

- [Catalog routes](https://github.com/surag29/inventory-core/tree/feature/backend-work/app/routes): `app/routes`
- [Catalog services](https://github.com/surag29/inventory-core/tree/feature/backend-work/app/services): `app/services`
- [Supplier routes](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/supplier.py): `app/routes/supplier.py`
- [Supplier service](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/supplier_service.py): `app/services/supplier_service.py`
- [Product-supplier links](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/product_supplier_service.py): `app/services/product_supplier_service.py`

### Cart and fulfillment

- [Cart item routes](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/cart_item.py): `app/routes/cart_item.py`
- [Cart item service](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/cart_item_service.py): `app/services/cart_item_service.py`
- [Order routes](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/routes/order.py): `app/routes/order.py`
- [Order service](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/order_service.py): `app/services/order_service.py`
- [Low-stock alerts](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/low_stock_alert_service.py): `app/services/low_stock_alert_service.py`

### Operations and data

- [Inventory operations routes](https://github.com/surag29/inventory-core/tree/feature/backend-work/app/routes): `app/routes`
- [Dashboard and reports](https://github.com/surag29/inventory-core/tree/feature/backend-work/app/services): `app/services`
- [Audit logging](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/services/audit_log_service.py): `app/services/audit_log_service.py`
- [Domain models](https://github.com/surag29/inventory-core/tree/feature/backend-work/app/models): `app/models`
- [Database dependency](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/dependencies/database.py): `app/dependencies/database.py`
- [SQL database](https://github.com/surag29/inventory-core/blob/feature/backend-work/app/db/database.py): `app/db/database.py`

### Other components

- **API client**

## Connections

- API client → FastAPI app: sends requests (evidence: `app/main.py`)
- FastAPI app → Authentication routes: registers router (evidence: `app/main.py`)
- FastAPI app → Catalog routes: registers routers (evidence: `app/main.py`)
- FastAPI app → Supplier routes: registers router (evidence: `app/main.py`)
- FastAPI app → Product-supplier links: registers router (evidence: `app/main.py`)
- FastAPI app → Inventory operations routes: registers routers (evidence: `app/main.py`)
- FastAPI app → Cart item routes: registers router (evidence: `app/main.py`)
- FastAPI app → Order routes: registers router (evidence: `app/main.py`)
- Authentication routes → Authentication service: calls (evidence: `app/routes/auth.py`)
- Authentication routes → Token security: creates tokens (evidence: `app/routes/auth.py`)
- Authentication service → Token security: hashes and verifies (evidence: `app/services/auth_service.py`)
- Authentication service → Domain models: queries and creates users (evidence: `app/services/auth_service.py`)
- Cart item routes → Cart item service: calls (evidence: `app/routes/cart_item.py`)
- Cart item service → Domain models: reads and updates cart and stock (evidence: `app/services/cart_item_service.py`)
- Cart item service → Audit logging: records changes (evidence: `app/services/cart_item_service.py`)
- Order routes → Order service: calls (evidence: `app/routes/order.py`)
- Order service → Domain models: reads and writes order and stock (evidence: `app/services/order_service.py`)
- Order service → Low-stock alerts: creates alerts (evidence: `app/services/order_service.py`)
- Order service → Audit logging: records status changes (evidence: `app/services/order_service.py`)
- Catalog routes → Catalog services: calls (evidence: `app/routes/product.py`)
- Catalog services → Domain models: reads and updates catalog (evidence: `app/services/product_service.py`)
- Supplier routes → Supplier service: calls (evidence: `app/routes/supplier.py`)
- Supplier service → Domain models: accesses supplier data
- Product-supplier links → Domain models: accesses linked records (evidence: `app/services/product_supplier_service.py`)
- Inventory operations routes → Domain models: manages inventory and alerts (evidence: `app/routes/cart_item.py`)
- Dashboard and reports → Domain models: queries reporting data (evidence: `app/services/auth_service.py`)
- Database dependency → SQL database: opens sessions (evidence: `app/dependencies/database.py`)
- Identity and roles → Token security: verifies tokens (evidence: `app/dependencies/auth.py`)
- Identity and roles → Domain models: loads user (evidence: `app/dependencies/auth.py`)
- FastAPI app → Database dependency: uses health-check dependency (evidence: `app/main.py`)
