# gopal092003/inventory-order-management architecture

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

- Interactive diagram: https://gitdiagram.com/gopal092003/inventory-order-management
- Repository: https://github.com/gopal092003/inventory-order-management

## Overview

#### Purpose and Runtime Entry Points
This is a full-stack inventory and order-management system: product and customer CRUD, multi-line-item orders, stock control, and operational dashboard metrics. The React/Vite SPA starts at `frontend/src/main.jsx`, composes routes in `frontend/src/routes/AppRoutes.jsx`, and is hosted in `frontend/src/App.jsx`. The FastAPI application is created in `backend/app/main.py`; Uvicorn serves it and exposes OpenAPI/Swagger.

#### Frontend Application Shell and Navigation
The browser client is organized around a dashboard layout, shared navigation, and feature pages rather than a server-rendered web app. `frontend/src/layouts/DashboardLayout.jsx` establishes the primary page frame; `frontend/src/components/layout/Sidebar.jsx` and `frontend/src/components/layout/Navbar.jsx` provide navigation. Routed feature screens represent the main user workflows: `frontend/src/features/dashboard/Dashboard.jsx`, `frontend/src/features/products/Products.jsx`, and `frontend/src/features/orders/Orders.jsx`.

#### Frontend API Boundary
Feature-local API modules call a centralized HTTP client, isolating backend URL/configuration and request behavior from UI components. `frontend/src/api/client.js` is the client boundary, with domain callers in `frontend/src/features/products/api.js`, `frontend/src/features/customers/api.js`, and `frontend/src/features/orders/api.js`. The frontend obtains its API base URL through `VITE_API_BASE_URL`; it does not directly access PostgreSQL.

#### FastAPI API and Layering
The backend follows route → service → persistence boundaries. Versioned REST endpoints are partitioned by business resource in `backend/app/api/v1/products.py`, `backend/app/api/v1/customers.py`, and `backend/app/api/v1/orders.py`; dashboard aggregation is exposed through `backend/app/api/v1/dashboard.py`. Application wiring, CORS, and exception integration belong in `backend/app/main.py`, while configuration and database-session setup are centralized in `backend/app/core/config.py` and `backend/app/core/database.py`.

#### Domain Model and Validation
SQLAlchemy entities persist the core relational model: customers, products, orders, and order line items in `backend/app/models/customer.py`, `backend/app/models/product.py`, and `backend/app/models/order_item.py`. Pydantic request/response contracts separate API payloads from ORM entities in `backend/app/schemas/product.py`, `backend/app/schemas/customer.py`, and `backend/app/schemas/order.py`. Orders form the principal transactional boundary: submitted line items must be inventory-valid and result in stock deduction.

#### Inventory and Analytics Services
Business logic that crosses resource boundaries is kept out of route handlers. `backend/app/services/inventory_service.py` governs inventory checks and updates used during ordering. `backend/app/services/dashboard_service.py` computes inventory, product, customer, and order summaries, including low-stock and recent-order data. Its output is consumed by the dashboard endpoint and rendered via `frontend/src/features/dashboard/Dashboard.jsx`.

#### Persistence, Delivery, and External Infrastructure
PostgreSQL is the system of record, configured through `DATABASE_URL`. Alembic manages schema evolution from `backend/alembic/env.py` and `backend/alembic/versions/initial_migration.py`; `backend/app/db/seed.py` supports initial data population. Local container orchestration is defined by `docker-compose.yml`, with independently containerized backend and frontend in `backend/Dockerfile` and `frontend/Dockerfile`. Target deployment boundaries are Vercel for the SPA, Render for FastAPI, and Render PostgreSQL; CI is executed by `.github/workflows/ci.yml`.

Main entry points: [`frontend/src/routes/AppRoutes.jsx`](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/routes/AppRoutes.jsx) (Application routes), [`backend/app/main.py`](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/v1/orders.py`](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/api/v1/orders.py) (Product, customer, order APIs), [`docker-compose.yml`](https://github.com/gopal092003/inventory-order-management/blob/main/docker-compose.yml) (Container orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_entry["SPA entry<br/>Vite bootstrap<br/>[main.jsx]"]
  node_app_routes["Application routes<br/>React routes<br/>[AppRoutes.jsx]"]
  node_app_shell["App host<br/>React app<br/>[App.jsx]"]
  node_dashboard_layout["Dashboard layout<br/>UI shell"]
  node_navigation["Sidebar and navbar<br/>Navigation<br/>[Sidebar.jsx]"]
  node_feature_pages["Product and order screens<br/>Feature UI<br/>[Products.jsx]"]
  node_dashboard_ui["Dashboard screen<br/>Feature UI<br/>[Dashboard.jsx]"]
  node_http_client["HTTP client<br/>API boundary<br/>[client.js]"]
  node_domain_api["Domain API callers<br/>Feature APIs<br/>[api.js]"]
end

subgraph group_backend["FastAPI backend"]
  node_fastapi_app{{"FastAPI application<br/>ASGI app<br/>[main.py]"}}
  node_resource_routes["Product, customer, order APIs<br/>REST routes<br/>[orders.py]"]
  node_dashboard_route["Dashboard API<br/>REST route<br/>[dashboard.py]"]
  node_contracts["Request and response schemas<br/>Pydantic contracts<br/>[order.py]"]
  node_inventory_service["Inventory service<br/>Business service"]
  node_dashboard_service["Dashboard service<br/>Analytics service"]
end

subgraph group_data["Data and migrations"]
  node_database_session["Database session<br/>SQLAlchemy setup<br/>[database.py]"]
  node_domain_models["Customers, products, orders<br/>SQLAlchemy entities<br/>[order_item.py]"]
  node_postgres[("PostgreSQL<br/>System of record")]
  node_migrations["Alembic migrations<br/>Schema evolution<br/>[env.py]"]
end

subgraph group_delivery["Delivery"]
  node_containers["Container orchestration<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_ci["CI workflow<br/>GitHub Actions<br/>[ci.yml]"]
end

node_spa_entry -->|"mounts"| node_app_shell
node_app_shell -->|"hosts"| node_app_routes
node_app_routes -->|"uses"| node_dashboard_layout
node_dashboard_layout -->|"contains"| node_navigation
node_app_routes -->|"renders"| node_feature_pages
node_app_routes -->|"renders"| node_dashboard_ui
node_feature_pages -->|"requests"| node_domain_api
node_domain_api -->|"uses"| node_http_client
node_dashboard_ui -->|"requests metrics"| node_http_client
node_http_client -->|"REST over HTTP"| node_fastapi_app
node_fastapi_app -->|"registers"| node_resource_routes
node_fastapi_app -->|"registers"| node_dashboard_route
node_resource_routes -->|"validates payloads"| node_contracts
node_resource_routes -->|"submits orders"| node_inventory_service
node_inventory_service -->|"uses"| node_database_session
node_dashboard_route -->|"queries summaries"| node_dashboard_service
node_dashboard_service -->|"uses"| node_database_session
node_database_session -->|"persists"| node_domain_models
node_domain_models -->|"stored in"| node_postgres
node_migrations -->|"evolves schema"| node_postgres
node_containers -.->|"serves frontend"| node_spa_entry
node_containers -.->|"runs backend"| node_fastapi_app
node_ci -.->|"validates delivery"| node_containers

click node_spa_entry "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/main.jsx"
click node_app_routes "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/routes/AppRoutes.jsx"
click node_app_shell "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/App.jsx"
click node_dashboard_layout "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/layouts/DashboardLayout.jsx"
click node_navigation "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/components/layout/Sidebar.jsx"
click node_feature_pages "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/features/products/Products.jsx"
click node_dashboard_ui "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/features/dashboard/Dashboard.jsx"
click node_http_client "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/api/client.js"
click node_domain_api "https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/features/orders/api.js"
click node_fastapi_app "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/main.py"
click node_resource_routes "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/api/v1/orders.py"
click node_dashboard_route "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/api/v1/dashboard.py"
click node_contracts "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/schemas/order.py"
click node_inventory_service "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/services/inventory_service.py"
click node_dashboard_service "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/services/dashboard_service.py"
click node_database_session "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/core/database.py"
click node_domain_models "https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/models/order_item.py"
click node_migrations "https://github.com/gopal092003/inventory-order-management/blob/main/backend/alembic/env.py"
click node_containers "https://github.com/gopal092003/inventory-order-management/blob/main/docker-compose.yml"
click node_ci "https://github.com/gopal092003/inventory-order-management/blob/main/.github/workflows/ci.yml"

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_spa_entry,node_app_routes,node_app_shell,node_dashboard_layout,node_navigation,node_feature_pages,node_dashboard_ui,node_http_client,node_domain_api toneBlue
class node_fastapi_app,node_resource_routes,node_dashboard_route,node_contracts,node_inventory_service,node_dashboard_service toneAmber
class node_database_session,node_domain_models,node_postgres,node_migrations toneMint
class node_containers,node_ci toneRose
```

## Components

### React SPA

- [SPA entry](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/main.jsx): Vite bootstrap · `frontend/src/main.jsx`
- [Application routes](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/routes/AppRoutes.jsx): React routes · `frontend/src/routes/AppRoutes.jsx`
- [App host](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/App.jsx): React app · `frontend/src/App.jsx`
- [Dashboard layout](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/layouts/DashboardLayout.jsx): UI shell · Frames routed screens with shared navigation. · `frontend/src/layouts/DashboardLayout.jsx`
- [Sidebar and navbar](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/components/layout/Sidebar.jsx): Navigation · `frontend/src/components/layout/Sidebar.jsx`
- [Product and order screens](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/features/products/Products.jsx): Feature UI · `frontend/src/features/products/Products.jsx`
- [Dashboard screen](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/features/dashboard/Dashboard.jsx): Feature UI · `frontend/src/features/dashboard/Dashboard.jsx`
- [HTTP client](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/api/client.js): API boundary · Uses VITE_API_BASE_URL for backend requests. · `frontend/src/api/client.js`
- [Domain API callers](https://github.com/gopal092003/inventory-order-management/blob/main/frontend/src/features/orders/api.js): Feature APIs · `frontend/src/features/orders/api.js`

### FastAPI backend

- [FastAPI application](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/main.py): ASGI app · Wires CORS, exceptions, and versioned API routes. · `backend/app/main.py`
- [Product, customer, order APIs](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/api/v1/orders.py): REST routes · `backend/app/api/v1/orders.py`
- [Dashboard API](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/api/v1/dashboard.py): REST route · `backend/app/api/v1/dashboard.py`
- [Request and response schemas](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/schemas/order.py): Pydantic contracts · `backend/app/schemas/order.py`
- [Inventory service](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/services/inventory_service.py): Business service · Validates submitted line items and deducts stock. · `backend/app/services/inventory_service.py`
- [Dashboard service](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/services/dashboard_service.py): Analytics service · Builds summaries, low-stock, and recent-order data. · `backend/app/services/dashboard_service.py`

### Data and migrations

- [Database session](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/core/database.py): SQLAlchemy setup · Configured through DATABASE_URL. · `backend/app/core/database.py`
- [Customers, products, orders](https://github.com/gopal092003/inventory-order-management/blob/main/backend/app/models/order_item.py): SQLAlchemy entities · Orders contain inventory-affecting line items. · `backend/app/models/order_item.py`
- **PostgreSQL**: System of record
- [Alembic migrations](https://github.com/gopal092003/inventory-order-management/blob/main/backend/alembic/env.py): Schema evolution · `backend/alembic/env.py`

### Delivery

- [Container orchestration](https://github.com/gopal092003/inventory-order-management/blob/main/docker-compose.yml): Docker Compose · Runs independently containerized frontend and backend locally. · `docker-compose.yml`
- [CI workflow](https://github.com/gopal092003/inventory-order-management/blob/main/.github/workflows/ci.yml): GitHub Actions · `.github/workflows/ci.yml`

## Connections

- SPA entry → App host: mounts
- App host → Application routes: hosts
- Application routes → Dashboard layout: uses
- Dashboard layout → Sidebar and navbar: contains
- Application routes → Product and order screens: renders
- Application routes → Dashboard screen: renders
- Product and order screens → Domain API callers: requests
- Domain API callers → HTTP client: uses
- Dashboard screen → HTTP client: requests metrics
- HTTP client → FastAPI application: REST over HTTP
- FastAPI application → Product, customer, order APIs: registers
- FastAPI application → Dashboard API: registers
- Product, customer, order APIs → Request and response schemas: validates payloads
- Product, customer, order APIs → Inventory service: submits orders
- Inventory service → Database session: uses
- Dashboard API → Dashboard service: queries summaries
- Dashboard service → Database session: uses
- Database session → Customers, products, orders: persists
- Customers, products, orders → PostgreSQL: stored in
- Alembic migrations → PostgreSQL: evolves schema
- Container orchestration → SPA entry: serves frontend
- Container orchestration → FastAPI application: runs backend
- CI workflow → Container orchestration: validates delivery