neeraj-jhaa/inventory-system

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