Integrated ERP + E-commerce + POS + Garment Manufacturing Platform for Hijab Valiasr.
Stack: Next.js 16 (App Router) · FastAPI · PostgreSQL · Tailwind CSS · Docker
# Start PostgreSQL
docker compose up -d db
# Backend
cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements/dev.txt
cp .env.example .env # edit as needed
alembic upgrade head
uvicorn app.main:app --reload --port 8000
# Frontend
cd frontend
pnpm install
pnpm devcp .env.example .env # edit sensitive values
docker compose up --build -dSee docs/deployment/production.md for full deployment guide.
backend/ — FastAPI (clean architecture)
frontend/ — Next.js 16 (App Router)
compose.yml — full Docker stack
nginx/ — reverse proxy config
prometheus/ — monitoring config
grafana/ — dashboards
scripts/ — backup, restore, pre-commit hooks
docs/ — architecture, deployment, migration
Production-ready REST API for the Mahdis / Hijab Valiasr e-commerce store.
Stack: FastAPI · SQLAlchemy 2.x (async) · Alembic · PostgreSQL · Pydantic v2 · JWT (access + refresh) · OTP auth · Clean Architecture (repository + service + DI).
app/
├── main.py # app factory, middleware, exception handlers, lifespan
├── core/ # config, security (JWT/OTP), exceptions, logging
├── db/ # base, async session, seed
├── models/ # SQLAlchemy ORM (13 tables)
├── schemas/ # Pydantic v2 DTOs
├── repositories/ # data access (no business logic)
├── services/ # business logic
├── api/
│ ├── deps.py # DI: db session, current user, admin guard
│ └── v1/endpoints/ # route handlers
└── utils/
Layering: endpoints → services → repositories → models. Endpoints never touch the ORM directly.
Phone OTP → JWT. POST /auth/otp/request generates a 6-digit code, stores a
keyed hash, and prints the code to the backend console (fake SMS). In dev
(OTP_DEBUG_RETURN=true) the code is also returned in the response.
POST /auth/otp/verify upserts the user and issues an access + refresh token
pair. Refresh tokens are stored server-side and rotated on use. The user whose
phone equals FIRST_ADMIN_PHONE is granted the admin role.
cd backend
python -m venv .venv && source .venv/bin/activate # or: uv venv
pip install -r requirements/dev.txt # or: uv pip install -r requirements/dev.txt
cp .env.example .env # adjust POSTGRES_* / SECRET_KEY
# Start PostgreSQL (compose maps host 5433 -> container 5432)
docker compose up -d db
# Apply migrations (seeds run automatically on app startup)
alembic upgrade head
# Run the API
uvicorn app.main:app --reload --port 8000Docs: http://localhost:8000/docs · Health: http://localhost:8000/api/health
docker compose up --build # api on :8000, db on :5433alembic revision --autogenerate -m "describe change"
alembic upgrade head
alembic downgrade -1ruff check app # lint
mypy app # strict typing
pytest # unit + API tests (SQLite in-memory)| Group | Endpoints |
|---|---|
| auth | POST /auth/otp/request, POST /auth/otp/verify, POST /auth/refresh, POST /auth/logout, GET /auth/me |
| categories | GET /categories, POST/PUT/DELETE (admin) |
| products | GET /products, GET /filters, GET /products/{slugOrId}, POST/PUT/DELETE (admin) |
| cart | GET/POST /cart, PUT/DELETE /cart/{id} (auth) |
| wishlist | GET/POST /wishlist (auth) |
| orders | POST /orders, GET /orders, PUT /orders/{id}/status (admin), GET /orders/{id}/track |
| reviews | POST /reviews, GET /reviews/product/{id} |
| promo | GET /promo-codes/{code} |
| admin | GET /admin/stats (admin) |
Health lives at /api/health (unversioned). Errors use the {"error": "..."}
shape for parity with the legacy client.