NUMU API

The core backend for NUMU — a multi-tenant SaaS e-commerce platform purpose-built for the Egyptian and MENA market ("Shopify for Egypt"). Built with FastAPI and Clean Architecture, with PostgreSQL Row-Level Security for tenant isolation and a Celery worker fleet for background jobs.

Every NUMU frontend (merchant hub, admin backoffice, customer storefront, landing page) talks to this single API.

System architecture

flowchart TB
  subgraph Clients["NUMU clients"]
    LP[numu-landing-page]
    MH[numo-merchant-hub]
    AD[numu-admin]
    SF[numu-storefront · V3 BYOT]
    BZ[numu-egyptian-bazaar · V2]
    MA[numu-merchant-app · Expo]
    PI[numu-payments-intelligence · Shopify app]
  end

  subgraph API["NUMU-api · FastAPI"]
    HTTP[HTTP layer<br/>routes · middleware]
    APP[Application layer<br/>use cases · DTOs]
    CORE[Core domain<br/>entities · value objects]
    INFRA[Infrastructure<br/>repositories · adapters]
  end

  subgraph Storage["Storage"]
    DB[(PostgreSQL · RLS)]
    R[(Redis · cache + Celery broker)]
    OS[(Object storage · R2/S3/MinIO)]
  end

  subgraph Workers["Celery workers"]
    W1[default queue]
    W2[images queue]
    W3[notifications]
  end

  subgraph External["External services"]
    PM[Paymob · Fawry · InstaPay<br/>Kashier · Moyasar · Tap · JT · Stripe]
    BO[Bosta · MyLerz · Shippo]
    RS[Resend · Twilio]
    WA[WhatsApp Business]
    MT[Meta · Pixel/CAPI/OAuth]
    OAI[OpenAI · HF Vision OCR]
    ETA[ETA Egypt · ZATCA Saudi · Fawaterak]
    SE[Sentry / Slack]
  end

  Clients -- "REST · httpOnly cookies" --> HTTP
  HTTP --> APP --> CORE
  APP --> INFRA
  INFRA --> DB
  INFRA --> R
  INFRA --> OS
  R --> Workers
  Workers --> RS
  Workers --> WA
  Workers --> SE
  INFRA --> PM
  INFRA --> BO
  INFRA --> MT
  INFRA --> OAI
  INFRA --> ETA

Clean Architecture layering

Strict, one-way dependencies — never reverse them.

flowchart LR
  subgraph L["Dependency direction"]
    direction LR
    api[api/<br/>routes · middleware] --> application[application/<br/>use cases · DTOs] --> core[core/<br/>entities · interfaces]
    api --> infrastructure[infrastructure/<br/>DB · adapters · cache]
    application --> infrastructure
    infrastructure -.implements.-> core
  end

Layer	Responsibility	Allowed imports
`core/`	Pure domain — entities, value objects, exceptions, interfaces	(nothing internal)
`application/`	Use cases + DTOs	`core/` only
`infrastructure/`	DB models, repositories, external services, cache, Celery tasks	`core/` (implements interfaces)
`api/`	HTTP routes, middleware, FastAPI deps, Pydantic schemas	All inner layers via DI

Request lifecycle

sequenceDiagram
    actor U as Client
    participant MW as Middleware stack
    participant R as FastAPI route
    participant UC as Use case
    participant Repo as Repository
    participant DB as PostgreSQL (RLS)
    participant C as Redis
    participant E as External service

    U->>MW: HTTP request (host: shop.numueg.app)
    Note over MW: CORS → Logging → Tenant → CSRF<br/>ResponseTime → Sentry → RateLimit<br/>Compression → CacheHeaders → SecurityHeaders
    MW->>MW: resolve tenant from subdomain<br/>SET app.current_tenant
    MW->>R: dispatch
    R->>UC: validate Pydantic schema · invoke use case
    UC->>Repo: load entities
    Repo->>DB: SELECT … (RLS filters by tenant)
    DB-->>Repo: rows
    UC->>C: read/write cache (optional)
    UC->>E: outbound call (optional · Paymob, OpenAI, …)
    UC-->>R: result DTO
    R-->>MW: serialize response
    MW-->>U: HTTP response (with security + cache headers)

Multi-tenancy

Shared schema + PostgreSQL Row-Level Security. Every tenant-scoped model carries a tenant_id foreign key, and the tenant middleware sets app.current_tenant per-request so RLS policies filter automatically.

flowchart LR
  Sub["shop.numueg.app"] --> M[TenantMiddleware]
  M -- "resolve subdomain" --> T[(public.tenants)]
  M -- "SET app.current_tenant = ..." --> Conn[(per-request DB connection)]
  Conn -- "every SELECT/UPDATE filtered<br/>by RLS USING (tenant_id = current_tenant)" --> Tables[(tenant-scoped tables)]

Tech stack

Layer	Choice
Language	Python 3.11+
Framework	FastAPI (async)
ORM	SQLAlchemy 2.0 (async)
Validation	Pydantic v2
Database	PostgreSQL 15+ (Row-Level Security)
Cache / broker	Redis 7+
Background jobs	Celery
Migrations	Alembic
Auth	JWT RS256 (access 30m + refresh 7d) · CSRF double-submit
Logging	structlog (JSON in prod, console in dev)
Admin panel	SQLAdmin (session-cookie auth)
PDF	WeasyPrint + Jinja2 (Noto Sans Arabic)
Encryption	AES-256-GCM (merchant credentials at rest)

Quick start

Prerequisites: Python 3.11+, PostgreSQL 15+, Redis 7+.

# 1. Clone and install dependencies
git clone <repository-url>
cd NUMU-api
pip install -e ".[dev]"

# 2. Configure environment
cp .env.example .env

# 3. Start dependencies via Docker
docker compose -f docker/docker-compose.yml up -d db redis

# 4. Run migrations
alembic upgrade head

# 5. (optional) Seed sample data
python scripts/seed_data.py

# 6. Start the dev server
make dev   # or: uvicorn src.main:app --reload --port 8000

Full stack via Docker Compose:

docker compose -f docker/docker-compose.yml up --build

API docs

Once running, the auto-generated docs live at:

URL	UI
`http://localhost:8000/docs`	Swagger UI
`http://localhost:8000/redoc`	ReDoc
`http://localhost:8000/admin`	SQLAdmin web panel (session-cookie auth)

Routes are grouped under /api/v1/:

Prefix	Domain
`/auth/`	Register · login · refresh · logout · CSRF · 2FA · email verification · password reset
`/stores/`	Store CRUD (owner)
`/stores/{id}/…`	Commerce: products · variants · categories · orders (+drafts · import · returns · refunds) · customers · inventory (+levels · transfers) · locations · gift_cards · bundles · shipments · shipping (+zones)
`/stores/{id}/…`	Growth: coupons · promotions (offers v2) · marketing campaigns/audiences · email_templates · upsells · abandoned_checkouts · social · analytics (+realtime) · dashboard · ai
`/stores/{id}/…`	Content: menus · pages · settings · onboarding · invoices · payment_proofs · payments · reconciliation · apps · order_import
`/stores/{id}/…`	WhatsApp & omnichannel: whatsapp (+campaigns · chat · templates · opt_ins · scheduled_sends) · channels · threads · messages · capi
`/stores/{id}/…`	Themes V3: themes · theme_editor_v3 · theme_installations · theme_updates · customizer_undo
`/themes` + `/marketplace/`	Theme marketplace: upload/build · developer submissions · admin review · catalog · purchases · reviews · store install
`/storefront/store/{id}/`	Public catalog · search · reviews · customer auth · checkout (+session) · gift cards · shipping rates · locations · payment proofs · pay · tracking
`/storefront/me/`	Customer profile · addresses · cart · checkout · wishlist · returns · saved cards · data rights
`/storefront/…`	`store-by-subdomain/{subdomain}` · theme_resolution · meta_feed (Meta Commerce XML)
`/staff/` + `/roles` + `/permissions`	Staff invitations · sessions · access requests · policies · RBAC
`/admin/`	Super-admin: tenants, waitlist, feedback, dashboard, platform config
`/tenants/` · `/public/`	Tenant registration & subdomain check · waitlist · landing config
`/billing` · `/referrals` · `/risk`	Subscriptions · merchant referrals · trust-network risk
`/shopify/`	Shopify app surface (11 sub-routers)
`/oauth/meta`	Meta OAuth for business scopes
`/webhooks/`	paymob · fawry · instapay · kashier · moyasar · jt · bosta · mylerz · meta · whatsapp · fawaterak · resend
`/ws` · `/health`	WebSocket realtime (inbox) · liveness probe

Configuration

Variable	Description	Default
`DEBUG`	Enable debug mode	`false`
`DATABASE_URL`	PostgreSQL connection string	required
`REDIS_URL`	Redis connection string	required
`JWT_PRIVATE_KEY`	RSA private key (PEM)	required
`JWT_PUBLIC_KEY`	RSA public key (PEM)	required
`STRIPE_SECRET_KEY`	Stripe API key	optional
`RESEND_API_KEY`	Resend email API key	optional
`OPENAI_API_KEY`	OpenAI API key	optional
`R2_ACCESS_KEY_ID`	Cloudflare R2 access key	optional
`META_APP_ID`	Meta (Facebook / Instagram) App ID	optional
`META_APP_SECRET`	Meta App Secret	optional
`META_WEBHOOK_VERIFY_TOKEN`	Webhook verification token	optional
`META_GRAPH_API_VERSION`	Graph API version	`v21.0`
`META_LOGIN_CONFIG_ID`	Facebook Login Config ID	optional
`INBOX_REALTIME_ENABLED`	Enable WebSocket inbox	`true`
`NOMINATIM_URL`	Self-hosted Nominatim base URL	optional
`LOCATIONIQ_KEY`	LocationIQ key (used if Nominatim unset)	optional

See src/config/settings.py for the complete list.

External services

Category	Services
Payments	Paymob (cards + wallets) · Fawry · InstaPay · Kashier · Moyasar · Tap · JT · Stripe · Cash on Delivery
Shipping	Bosta · MyLerz (Egyptian couriers) · Shippo
Email / SMS	Resend · Twilio
Messaging	WhatsApp Business API (templates · campaigns · omnichannel inbox)
Marketing	Meta — Pixel, Conversions API, OAuth, custom/lookalike audiences, Messenger/Instagram inbox
Storage	Cloudflare R2 / MinIO / AWS S3
AI	OpenAI (product descriptions, insights) · Hugging Face Vision (payment-proof OCR)
Tax / e-invoicing	ETA (Egypt) · ZATCA (Saudi Arabia) · Fawaterak
Maps	Self-hosted Nominatim (or) LocationIQ
Monitoring	Sentry · Slack (webhook channels, batched every 30s)

Self-hosted Nominatim

The storefront checkout location picker calls /storefront/.../geocode/reverse, which proxies to either a self-hosted Nominatim container or LocationIQ depending on env config.

docker compose --profile geocoding up nominatim

The first run downloads ~200 MB and imports the Egypt OSM extract (~5 GB on disk, ~30 min). Subsequent restarts come up in seconds. The container runs UPDATE_MODE=continuous against Geofabrik's daily Egypt diff feed — no Celery task or manual re-import required.

Background jobs

flowchart LR
  API[NUMU-api] -- enqueue --> R[(Redis broker)]
  R --> W[Celery workers<br/>~57 task modules]
  W --> Email[Resend email]
  W --> WA[WhatsApp Business]
  W --> Slack[Slack webhooks · batched 30s]
  W --> Store[(R2 / S3 / MinIO)]
  W --> Meta[Meta CAPI]

Area	Tasks (selection)
Commerce	abandoned-cart recovery · back-in-stock · shipments · order webhooks
WhatsApp	campaign sends · scheduled dispatcher (60s) · template poll (15m) · dead-letter purge (daily)
Payments / risk	InstaPay expiry · COD deposit expiry · auto-RTO · risk scoring · fraud detection
Marketing	campaigns · promotions · Meta CAPI dispatch · social
Analytics	daily rollups · event ingest · retention purge · courier stats
Themes	theme build · upload · marketplace tasks
Lifecycle	demo cleanup · trial expiry · data retention · daily DB backup (03:00 UTC) · image processing

Project structure

Show tree

NUMU-api/
├── alembic/                   # Database migrations
├── docker/                    # Docker configuration
├── docs/                      # Documentation
├── scripts/                   # Utility scripts (seed, ops, etc.)
├── src/
│   ├── api/
│   │   ├── dependencies/      # FastAPI Depends() factories
│   │   ├── middleware/        # CORS, logging, tenant, CSRF, etc.
│   │   ├── responses/         # Response envelopes
│   │   └── v1/
│   │       ├── routes/        # API endpoints grouped by domain
│   │       └── schemas/       # Pydantic request/response schemas
│   ├── application/
│   │   ├── dto/               # Data transfer objects
│   │   ├── services/          # Application services
│   │   └── use_cases/         # Business use cases
│   ├── config/                # Pydantic settings management
│   ├── core/
│   │   ├── entities/          # Domain entities
│   │   ├── exceptions/        # Domain exceptions
│   │   ├── interfaces/        # Repository + service interfaces
│   │   └── value_objects/     # Money, LocalizedString, etc.
│   └── infrastructure/
│       ├── cache/             # Redis cache
│       ├── database/          # SQLAlchemy setup + ORM models
│       ├── external_services/ # Paymob, Bosta, OpenAI, …
│       ├── messaging/         # Celery tasks
│       └── repositories/      # Repository implementations
└── tests/
    ├── unit/                  # Unit tests
    ├── integration/           # Integration tests (real DB / Redis)
    └── e2e/                   # End-to-end tests

Testing

pytest                                    # full suite
pytest --cov=src --cov-report=html        # with coverage
pytest tests/unit/                        # unit only
pytest tests/integration/                 # integration only
pytest tests/e2e/                         # end-to-end only

Development tools

ruff format src/ tests/    # format
ruff check src/ tests/     # lint
mypy src/                  # type check
make migrate-new           # generate a new Alembic migration
make migrate               # apply migrations
make seed                  # seed sample data

License

MIT.

Name		Name	Last commit message	Last commit date
Latest commit History 1,032 Commits
.agents/skills		.agents/skills
.github		.github
.specify		.specify
.zap		.zap
alembic		alembic
docker		docker
docs		docs
ig_posts		ig_posts
ops/n8n		ops/n8n
packages/api-types		packages/api-types
scripts		scripts
specs		specs
src		src
tests		tests
uploads		uploads
.env.example		.env.example
.env.production.example		.env.production.example
.env.stage.example		.env.stage.example
.env.staging.example		.env.staging.example
.env.test.example		.env.test.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
BACKEND_IMPLEMENTATION_SUMMARY.md		BACKEND_IMPLEMENTATION_SUMMARY.md
CLAUDE.md		CLAUDE.md
Kashier.md		Kashier.md
MULTI_TENANCY_Implementation_Plan.md		MULTI_TENANCY_Implementation_Plan.md
Makefile		Makefile
NUMU_Dashboard_Frontend_Plan.pdf		NUMU_Dashboard_Frontend_Plan.pdf
NUMU_Phase2_Days31_60.pdf		NUMU_Phase2_Days31_60.pdf
PR_DESCRIPTION.md		PR_DESCRIPTION.md
README.md		README.md
alembic.ini		alembic.ini
compute_kashier_sig.py		compute_kashier_sig.py
dasd		dasd
fix_mypy.py		fix_mypy.py
generate_test_invoice.py		generate_test_invoice.py
pyproject.toml		pyproject.toml
test_invoice_ar.html		test_invoice_ar.html
test_invoice_en.html		test_invoice_en.html
test_kashier_e2e.py		test_kashier_e2e.py
update_themes.py		update_themes.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

NUMU API

Table of contents

System architecture

Clean Architecture layering

Request lifecycle

Multi-tenancy

Tech stack

Quick start

API docs

Configuration

External services

Self-hosted Nominatim

Background jobs

Project structure

Testing

Development tools

License

About

Uh oh!

Releases

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

NUMU API

Table of contents

System architecture

Clean Architecture layering

Request lifecycle

Multi-tenancy

Tech stack

Quick start

API docs

Configuration

External services

Self-hosted Nominatim

Background jobs

Project structure

Testing

Development tools

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages