Full-stack inventory management system with a React/TypeScript frontend and FastAPI backend. Tracks products, stock movements, and suppliers with real-time analytics.
Dashboard: KPI cards, stock value by category, top products by value
Products: Product list with search, category filter, and low-stock indicator
Movements: Audit trail of inbound/outbound stock movements
Login: JWT authentication with role-based access control (admin/staff/viewer)
┌─────────────────────────────────┐
│ React + TypeScript │
│ Vite + Tailwind CSS │
│ Recharts │
│ Port 5173 (dev) │
└──────────────┬──────────────────┘
│ REST API
▼
┌─────────────────────────────────┐
│ FastAPI + Python │
│ SQLAlchemy ORM │
│ Pydantic v2 │
│ Port 8000 │
└──────────────┬──────────────────┘
│
▼
┌─────────────────────────────────┐
│ SQLite │
│ inventory.db │
└─────────────────────────────────┘
- Dashboard: KPI cards, stock value by category (bar chart), top products, recent movements
- Product Management: CRUD operations, search, category filter, low-stock alerts
- Stock Movements: Record inbound/outbound stock with reference tracking
- Supplier Management: CRUD with product count tracking
- Analytics API: Real-time stock value, category breakdown, movement history
- Data Validation: Pydantic v2 schemas, unique SKU enforcement, stock integrity checks
- 30+ Backend Tests with pytest, 8 Frontend Tests with Vitest + Testing Library
docker compose upThis builds and starts the FastAPI backend and the React frontend. Open http://localhost:8080 in your browser. The frontend serves the app and proxies API calls to the backend, which keeps its SQLite database in a named volume.
Backend:
cd backend
pip install -r requirements.txt
python -m data.seed # Generate sample data
uvicorn main:app --reload # Start API at localhost:8000Frontend:
cd frontend
npm install
npm run dev # Start dev server at localhost:5173Once the backend is running, visit http://localhost:8000/docs for interactive Swagger documentation.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/products | List products (search, category, low_stock filter) |
| GET | /api/products/export | Download filtered products as CSV |
| POST | /api/products | Create product |
| PUT | /api/products/{id} | Update product |
| DELETE | /api/products/{id} | Delete product (only if stock is 0) |
| GET | /api/movements | List stock movements |
| POST | /api/movements | Record stock in/out |
| GET | /api/suppliers | List suppliers |
| POST | /api/suppliers | Create supplier |
| PUT | /api/suppliers/{id} | Update supplier |
| DELETE | /api/suppliers/{id} | Delete supplier (only if no products) |
| GET | /api/analytics/dashboard | Dashboard KPIs and charts |
inventory-management/
├── backend/
│ ├── agents/
│ │ ├── routes.py # API endpoint definitions
│ │ ├── product_service.py # Product CRUD logic
│ │ ├── movement_service.py # Stock movement logic
│ │ ├── supplier_service.py # Supplier CRUD logic
│ │ └── analytics_service.py # Dashboard analytics
│ ├── models/
│ │ ├── orm.py # SQLAlchemy table definitions
│ │ └── schemas.py # Pydantic request/response models
│ ├── db/
│ │ └── database.py # Database connection and session
│ ├── data/
│ │ └── seed.py # Sample data generator
│ ├── tests/ # 30+ pytest tests
│ ├── main.py # FastAPI application entry point
│ └── requirements.txt
├── frontend/
│ ├── src/
│ │ ├── pages/ # Dashboard, Products, Movements, Suppliers
│ │ ├── components/ # KpiCard, Modal, Layout, LoadingSpinner
│ │ ├── api/ # API client with fetch wrapper
│ │ └── types/ # TypeScript interfaces
│ ├── package.json
│ └── vite.config.ts
├── Dockerfile
└── README.md
Backend (pytest):
cd backend
pytest -vFrontend (Vitest + React Testing Library):
cd frontend
npm test # one-shot run
npm run test:watch # watch mode while developing
npm run test:ui # interactive UI in browserMIT