# neeraj-jhaa/inventory-system architecture

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

- Interactive diagram: https://gitdiagram.com/neeraj-jhaa/inventory-system
- Repository: https://github.com/neeraj-jhaa/inventory-system

## Overview

#### Purpose and Runtime Topology
This is a containerized inventory and order-management system. A React single-page application calls a FastAPI REST API, which persists products, customers, orders, and order items in PostgreSQL. Docker Compose orchestrates the three tiers; Nginx serves the frontend container.
- `docker-compose.yml`
- `backend/Dockerfile`
- `frontend/Dockerfile`
- `frontend/nginx.conf`

#### Application Entry Points
The backend ASGI entry point creates the FastAPI application and mounts domain routers; it is run as `uvicorn app.main:app`. The browser application starts from the React index and renders the top-level application/router.
- `backend/app/main.py`
- `frontend/src/index.js`
- `frontend/src/App.js`

There are duplicate frontend-looking files at `frontend/App.js`, `frontend/pages/*`, and `frontend/services/api.js`; the `frontend/src/` tree is the conventional React build source and should be treated as the primary application boundary unless package scripts indicate otherwise.

#### Persistence and Domain Model
SQLAlchemy connection/session setup isolates database access from HTTP handlers. ORM models define the core relational state: inventory products, customers, orders, and likely order-item associations. PostgreSQL is configured through environment-provided connection settings, enabling Compose and hosted database deployments.
- `backend/app/database/connection.py`
- `backend/app/models/models.py`
- `.env.example`
- `backup.sql`

#### API Contract and Validation Layer
Pydantic schemas define request/response shapes at the API boundary, while routers own CRUD and workflow endpoints. Product SKU and customer email uniqueness are enforced through persistence-aware API operations; errors should be translated into HTTP responses rather than exposed as database failures.
- `backend/app/schemas/schemas.py`
- `backend/app/routers/products.py`
- `backend/app/routers/customers.py`

#### Order Transaction Workflow
Order creation is the central business workflow: accept a customer and item list, load referenced products, validate sufficient stock, create an order with line items, deduct inventory, and commit atomically. Cancellation reverses this state transition by restoring quantities before/with order removal or cancellation. This is the key consistency boundary and depends on a shared database transaction/session.
- `backend/app/routers/orders.py`
- `backend/app/models/models.py`
- `backend/app/database/connection.py`

#### Dashboard Read Model
Dashboard statistics are derived from persisted inventory/order data rather than maintained as a separate service. The dashboard router exposes aggregate figures such as total stock, low-stock count, and out-of-stock count for the frontend dashboard page.
- `backend/app/routers/dashboard.py`
- `frontend/src/pages/Dashboard.js`
- `backend/app/models/models.py`

#### Frontend UI and API Integration
React pages implement product, customer, order, and dashboard workflows. A centralized Axios service is the frontend’s API boundary, using an environment-configured backend URL; layout and shared UI components provide cross-page structure and feedback.
- `frontend/src/services/api.js`
- `frontend/src/pages/Products.js`
- `frontend/src/pages/Orders.js`
- `frontend/src/components/Layout/Layout.js`

#### External Interfaces and Deployment Boundaries
External dependencies are PostgreSQL, Docker/Docker Compose, and optional deployment hosts (Render for API/database; Netlify or Vercel for static frontend). The backend exposes interactive API documentation through FastAPI, while Nginx separates static frontend delivery from API execution.
- `backend/requirements.txt`
- `frontend/package.json`
- `frontend/nginx.conf`
- `docker-compose.yml`

Main entry points: [`backend/app/main.py`](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/database/connection.py`](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/database/connection.py) (SQLAlchemy session), [`docker-compose.yml`](https://github.com/neeraj-jhaa/inventory-system/blob/main/docker-compose.yml) (Docker Compose), [`frontend/src/pages/Products.js`](https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/pages/Products.js) (Workflow pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client"))
  node_react_entry["React entry and router<br/>React SPA<br/>[index.js]"]
  node_react_pages["Workflow pages<br/>React pages<br/>[Products.js]"]
  node_api_client["Axios API client<br/>[api.js]"]
  node_layout["Shared layout<br/>React component<br/>[Layout.js]"]
end

subgraph group_backend["Backend API"]
  node_fastapi_app["FastAPI application<br/>ASGI entry point<br/>[main.py]"]
  node_api_schemas["Request and response schemas<br/>Pydantic schemas<br/>[schemas.py]"]
  node_catalog_routers["Product and customer APIs<br/>CRUD routers<br/>[products.py]"]
  node_orders_router["Order workflow API<br/>transactional router<br/>[orders.py]"]
  node_dashboard_router["Dashboard aggregates API<br/>read-model router<br/>[dashboard.py]"]
end

subgraph group_data["Persistence"]
  node_db_session["SQLAlchemy session<br/>database access<br/>[connection.py]"]
  node_domain_models["Inventory and order models<br/>SQLAlchemy ORM<br/>[models.py]"]
  node_postgres[("PostgreSQL<br/>relational database")]
end

subgraph group_deployment["Container Deployment"]
  node_nginx["Nginx static server<br/>web server<br/>[nginx.conf]"]
  node_compose{{"Docker Compose<br/>orchestrator<br/>[docker-compose.yml]"}}
  node_backend_image["Backend container image<br/>Docker build"]
  node_frontend_image["Frontend container image<br/>Docker build"]
end

node_browser -->|"loads SPA"| node_nginx
node_nginx -->|"serves build"| node_react_entry
node_react_entry -->|"renders routes"| node_react_pages
node_react_pages -->|"uses"| node_layout
node_react_pages -->|"calls"| node_api_client
node_api_client -->|"REST requests"| node_fastapi_app
node_fastapi_app -->|"validates payloads"| node_api_schemas
node_fastapi_app -->|"mounts"| node_catalog_routers
node_fastapi_app -->|"mounts"| node_orders_router
node_fastapi_app -->|"mounts"| node_dashboard_router
node_catalog_routers -->|"CRUD sessions"| node_db_session
node_orders_router -->|"shared transaction"| node_db_session
node_dashboard_router -->|"aggregate queries"| node_db_session
node_db_session -->|"maps"| node_domain_models
node_domain_models -->|"persists"| node_postgres
node_compose -->|"builds and runs"| node_frontend_image
node_compose -->|"builds and runs"| node_backend_image
node_compose -->|"runs"| node_postgres
node_frontend_image -->|"contains"| node_nginx
node_backend_image -->|"runs"| node_fastapi_app

click node_react_entry "https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/index.js"
click node_react_pages "https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/pages/Products.js"
click node_api_client "https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/services/api.js"
click node_layout "https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/components/Layout/Layout.js"
click node_nginx "https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/nginx.conf"
click node_fastapi_app "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/main.py"
click node_api_schemas "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/schemas/schemas.py"
click node_catalog_routers "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/routers/products.py"
click node_orders_router "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/routers/orders.py"
click node_dashboard_router "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/routers/dashboard.py"
click node_db_session "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/database/connection.py"
click node_domain_models "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/models/models.py"
click node_compose "https://github.com/neeraj-jhaa/inventory-system/blob/main/docker-compose.yml"
click node_backend_image "https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/Dockerfile"
click node_frontend_image "https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/Dockerfile"

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_react_entry,node_react_pages,node_api_client,node_layout toneBlue
class node_fastapi_app,node_api_schemas,node_catalog_routers,node_orders_router,node_dashboard_router toneAmber
class node_db_session,node_domain_models,node_postgres toneMint
class node_nginx,node_compose,node_backend_image,node_frontend_image toneRose
```

## Components

### Frontend

- **Browser**: client
- [React entry and router](https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/index.js): React SPA · `frontend/src/index.js`
- [Workflow pages](https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/pages/Products.js): React pages · Products, orders, customers, and dashboard views. · `frontend/src/pages/Products.js`
- [Axios API client](https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/services/api.js): API client · Uses an environment-configured backend URL. · `frontend/src/services/api.js`
- [Shared layout](https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/src/components/Layout/Layout.js): React component · `frontend/src/components/Layout/Layout.js`

### Backend API

- [FastAPI application](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/main.py): ASGI entry point · Run as uvicorn app.main:app. · `backend/app/main.py`
- [Request and response schemas](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/schemas/schemas.py): Pydantic schemas · `backend/app/schemas/schemas.py`
- [Product and customer APIs](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/routers/products.py): CRUD routers · Enforces SKU and email uniqueness with HTTP error translation. · `backend/app/routers/products.py`
- [Order workflow API](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/routers/orders.py): transactional router · Creates or cancels orders while adjusting stock atomically. · `backend/app/routers/orders.py`
- [Dashboard aggregates API](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/routers/dashboard.py): read-model router · Derives stock and order statistics from persisted data. · `backend/app/routers/dashboard.py`

### Persistence

- [SQLAlchemy session](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/database/connection.py): database access · Isolates connection and transaction handling from HTTP handlers. · `backend/app/database/connection.py`
- [Inventory and order models](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/app/models/models.py): SQLAlchemy ORM · Products, customers, orders, and order items. · `backend/app/models/models.py`
- **PostgreSQL**: relational database

### Container Deployment

- [Nginx static server](https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/nginx.conf): web server · `frontend/nginx.conf`
- [Docker Compose](https://github.com/neeraj-jhaa/inventory-system/blob/main/docker-compose.yml): orchestrator · Runs frontend, API, and database tiers. · `docker-compose.yml`
- [Backend container image](https://github.com/neeraj-jhaa/inventory-system/blob/main/backend/Dockerfile): Docker build · `backend/Dockerfile`
- [Frontend container image](https://github.com/neeraj-jhaa/inventory-system/blob/main/frontend/Dockerfile): Docker build · `frontend/Dockerfile`

## Connections

- Browser → Nginx static server: loads SPA
- Nginx static server → React entry and router: serves build
- React entry and router → Workflow pages: renders routes
- Workflow pages → Shared layout: uses
- Workflow pages → Axios API client: calls
- Axios API client → FastAPI application: REST requests
- FastAPI application → Request and response schemas: validates payloads
- FastAPI application → Product and customer APIs: mounts
- FastAPI application → Order workflow API: mounts
- FastAPI application → Dashboard aggregates API: mounts
- Product and customer APIs → SQLAlchemy session: CRUD sessions
- Order workflow API → SQLAlchemy session: shared transaction
- Dashboard aggregates API → SQLAlchemy session: aggregate queries
- SQLAlchemy session → Inventory and order models: maps
- Inventory and order models → PostgreSQL: persists
- Docker Compose → Frontend container image: builds and runs
- Docker Compose → Backend container image: builds and runs
- Docker Compose → PostgreSQL: runs
- Frontend container image → Nginx static server: contains
- Backend container image → FastAPI application: runs