StockFlow is a production-oriented, multi-tenant SaaS platform for managing products, warehouses, inventory, customers, orders, payments, shipments, and operational workflows.
The project is designed to demonstrate how a senior full-stack engineer approaches the design and implementation of a business-critical system where data consistency, concurrency, security, reliability, and maintainability matter more than simply exposing CRUD endpoints.
🚧 In active development
Modern businesses often manage inventory across multiple warehouses while processing orders from multiple users and channels.
StockFlow provides a centralized platform for managing these operations while addressing common production challenges such as:
- Concurrent inventory updates
- Stock reservation and release
- Transactional order creation
- Duplicate request prevention
- Multi-tenant data isolation
- Role-based access control
- Background processing
- API performance and caching
- Auditability of critical business operations
The system is intentionally being developed as a modular monolith, providing clear domain boundaries without introducing the operational complexity of microservices prematurely.
- Multi-tenant organizations
- User management
- Role-based access control (RBAC)
- Permission management
- Tenant-level authorization
- Secure authentication and token lifecycle
- Object-level authorization where required
- Product management
- Categories
- Product variants
- SKU management
- Pricing
- Product status and metadata
- Multiple warehouses
- Warehouse locations
- Available stock
- Reserved stock
- Damaged stock
- Stock adjustments
- Inventory transactions
- Inventory reservations
- Stock transfers
- Low-stock monitoring
- Customer orders
- Order items
- Order lifecycle
- Transactional order creation
- Inventory reservation during checkout
- Order cancellation
- Idempotent order operations
- Order history
- Payment records and lifecycle
- Payment status tracking
- Shipment creation
- Shipment lifecycle
- Tracking information
- Order fulfillment workflow
- Sales dashboards
- Inventory analytics
- Low-stock reports
- Operational reports
- CSV exports
- PDF invoice generation
- Audit history
StockFlow follows a modular monolith architecture.
┌──────────────────────────┐
│ React Client │
│ React + TypeScript │
└────────────┬─────────────┘
│ HTTPS
▼
┌──────────────────────────┐
│ Nginx │
│ Reverse Proxy / Routing │
└────────────┬─────────────┘
│
▼
┌────────────────────────────────────────┐
│ Django REST API │
│ │
│ Accounts Tenants Catalog │
│ Inventory Orders Customers │
│ Payments Shipping Audit │
└───────────────┬───────────────┬────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ PostgreSQL │ │ Redis │
│ Source of │ │ Cache / │
│ Truth │ │ Infrastructure│
└──────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ Celery │
│ Workers │
└──────────────┘
StockFlow deliberately avoids starting with microservices.
A modular monolith provides:
- Strong domain boundaries
- Simpler deployment
- Lower operational overhead
- Straightforward database transactions
- Easier local development
- Easier debugging and testing
The internal architecture will maintain clear module boundaries so that high-value domains could be extracted into independent services later if scale, team ownership, or operational requirements justify the change.
StockFlow is intentionally focused on problems that commonly appear in production systems.
Every tenant owns its own users, products, inventory, customers, and orders.
StockFlow
│
┌──────────┴──────────┐
▼ ▼
Tenant A Tenant B
│ │
┌──────┼──────┐ ┌──────┼──────┐
▼ ▼ ▼ ▼ ▼ ▼
Products Orders Inventory Products Orders Inventory
A user belonging to Tenant A must never be able to read or modify Tenant B's resources.
Tenant isolation is enforced at the backend through authorization, tenant-aware queries, database relationships, constraints, and automated tests.
Inventory is treated as a business domain rather than a simple integer field.
Instead of:
product.quantity -= 1StockFlow models:
- Available Stock
- Reserved Stock
- Damaged Stock
- Inventory State
- Inventory Transactions
Critical inventory operations use database transactions and appropriate row-level locking.
Example:
Inventory = 1
Request A ──────┐
├── Concurrent purchase
Request B ──────┘
Expected:
- Request A → succeeds
- Request B → safely rejected
- Inventory → remains consistent
Concurrency scenarios will be explicitly covered by automated tests.
Creating an order involves multiple related operations.
Conceptually:
BEGIN TRANSACTION
│
├── Validate customer
├── Validate products
├── Lock inventory
├── Reserve stock
├── Create order
├── Create order items
├── Calculate totals
├── Create payment record
└── Create audit event
│
COMMIT
If a critical operation fails, the transaction is rolled back to prevent partially completed orders.
Important write operations support idempotency to protect against duplicate requests.
POST /api/v1/orders/
Idempotency-Key: 7f4a...A retry of the same operation should return the previously created result rather than creating another order.
This protects against scenarios such as:
- Client retries
- Network failures
- Request timeouts
- Duplicate submissions
Operations that do not need to block the primary API request are delegated to Celery.
Examples include:
- Email notifications
- Report generation
- CSV exports
- PDF invoices
- Low-stock notifications
- Bulk imports
- Scheduled reports
Redis provides the supporting infrastructure for caching and asynchronous workloads.
Technology Stack Layer Technology Frontend React, TypeScript Routing React Router Server State TanStack Query Forms React Hook Form, Zod Styling Tailwind CSS Charts Recharts Backend Python, Django API Django REST Framework Database PostgreSQL Cache / Queue Infrastructure Redis Background Jobs Celery, Celery Beat Reverse Proxy Nginx Containers Docker, Docker Compose Backend Testing Pytest, pytest-django Frontend Testing React Testing Library E2E Testing Playwright CI/CD GitHub Actions API Documentation OpenAPI / Swagger Diagrams Mermaid, diagrams.net Backend Architecture
The backend follows a layered approach:
HTTP Request │ ▼ API View │ ▼ Serializer / Validation │ ▼ Service / Business Logic │ ▼ Query / ORM Layer │ ▼ PostgreSQL
Business rules are intentionally kept separate from HTTP handling wherever practical.
Planned Django domains include:
backend/apps/
├── accounts/ ├── tenants/ ├── catalog/ ├── inventory/ ├── orders/ ├── customers/ ├── payments/ ├── shipping/ └── audit/
Frontend Architecture
The frontend follows a feature-oriented architecture.
frontend/src/
├── app/ │ ├── router/ │ ├── providers/ │ └── store/ │ ├── features/ │ ├── auth/ │ ├── dashboard/ │ ├── products/ │ ├── inventory/ │ ├── orders/ │ ├── customers/ │ └── users/ │ ├── components/ │ ├── ui/ │ ├── tables/ │ ├── forms/ │ └── charts/ │ ├── hooks/ ├── services/ ├── types/ └── utils/
TanStack Query will primarily manage server state, while local component state and global state management will be introduced only where justified.
Database
The initial database model includes:
Tenant User Role Permission
Category Product ProductVariant
Warehouse WarehouseLocation Inventory InventoryTransaction InventoryReservation StockTransfer
Customer
Order OrderItem
Payment Shipment
Supplier AuditLog
Database design will emphasize:
Referential integrity Foreign keys Unique constraints Composite indexes Transactional consistency Query performance Appropriate normalization
Query optimization will consider:
select_related prefetch_related Pagination Indexing N+1 query prevention Query profiling
An ER diagram will be maintained in docs/diagrams/.
Security
Security is treated as a core system requirement.
StockFlow will address:
Authentication Authorization RBAC Tenant isolation Object-level permissions Password security Token security Input validation API throttling Secure configuration Secret management Security headers Audit logging
Frontend permission checks are considered a UX mechanism—not a security boundary.
All authorization decisions must ultimately be enforced by the backend.
API
The API follows a versioned REST structure:
/api/v1/
Planned resources include:
/api/v1/auth/ /api/v1/users/ /api/v1/products/ /api/v1/categories/ /api/v1/warehouses/ /api/v1/inventory/ /api/v1/orders/ /api/v1/customers/ /api/v1/suppliers/ /api/v1/shipments/ /api/v1/payments/ /api/v1/reports/ /api/v1/audit-logs/
API documentation will be generated using OpenAPI.
Testing Strategy
Testing will cover multiple levels.
Backend Unit tests Integration tests Authentication tests Authorization tests Tenant isolation tests Transaction tests Concurrency tests Idempotency tests API throttling tests Frontend Component tests Form validation Loading states Error states Permission behavior API integration behavior End-to-End
A primary E2E flow will cover:
Login ↓ Dashboard ↓ Create Product ↓ Add Inventory ↓ Create Order ↓ Payment ↓ Shipment
Docker & Development
The complete development environment will be containerized.
Planned services:
frontend backend postgres redis celery_worker celery_beat nginx
The goal is to make the environment reproducible with:
docker compose up
Environment-specific configuration will be separated from application code.
Documentation
Engineering documentation will be maintained separately from this README.
docs/ ├── architecture/ ├── adr/ ├── database/ ├── api/ └── diagrams/
Architecture Decision Records will capture significant decisions such as:
Why PostgreSQL? Why modular monolith? Why Redis? Why Celery? How is multi-tenancy implemented? How is inventory concurrency handled? Why API versioning? Project Roadmap Phase 1 — Foundation Repository setup Development environment Project structure Git conventions Initial documentation Phase 2 — Architecture Domain boundaries ER diagram Database design Multi-tenancy strategy ADRs Phase 3 — Backend Django foundation Authentication Authorization Multi-tenancy Catalog Inventory Orders Payments Shipping Audit logging Phase 4 — Infrastructure Redis Celery Caching Background jobs Scheduled jobs Docker Nginx Phase 5 — Frontend React foundation Authentication Dashboard Product management Inventory management Orders Customers Users Reports Phase 6 — Quality & Production Automated testing E2E testing CI/CD Security hardening Performance optimization Observability Production configuration Phase 7 — Interview Preparation System design walkthrough Database design discussion Concurrency discussion Multi-tenancy discussion Scaling discussion Failure scenarios Architecture trade-offs Mock interviews Engineering Principles
StockFlow follows a few core principles:
Correctness over cleverness Security by design Explicit business rules Database integrity matters Simple architecture before unnecessary complexity Design for failure Test critical invariants Measure before optimizing Document important decisions Every technology must have a clear responsibility Project Objective
StockFlow is being developed as a senior-level engineering project with an emphasis on depth rather than technology quantity.
The objective is to demonstrate the ability to:
Design, build, test, document, and explain a production-oriented software system.
The project should serve as a practical demonstration of full-stack engineering, backend architecture, database design, distributed-system concepts, security, testing, and system-design thinking.
License
To be determined.