Aladdin
AI-first operating system for Egypt's finishing, construction, interior design, furnishing, supply, and professional-services sector. B2B-first, with a connected B2C consultation/discovery/project layer. Consultation-first — not an add-to-cart / price-war marketplace.
Value chain: Need → Advice → Discovery → Trusted Match → RFQ → Quote → Decision → Execution → Follow-up. Three surfaces: B2C, B2B (Sales is the key daily-active user), Admin.
Private Pilot MVP goal
Ship the core value journey with Sales-first sequencing (05C → 05A → 05B → 05D → 05E). Full scope and ordering: docs/product/mvp-scope.md.
Project Memory — Read First
Five files are persistent project memory and part of the core architecture, not optional docs. Product, architecture, UI, and unfinished-work decisions must not live only in prompts or chat history — they live here. Read them before making changes:
docs/product/PRODUCT_DIRECTION_GUIDE.md — product direction & guardrailsdocs/architecture/ARCHITECTURE_GUIDE.md — currently active architecture (complements the ADRs)UI-UX/UI_UX_SYSTEM_GUIDE.md — design system, tokens, UX rulesdocs/operations/AGENT_WORK_LOG.md — append-only session log & unfinished workdocs/operations/RUNTIME_STATE.md — current live repository state
Authority rules and the end-of-session checklist live in root AGENTS.md and docs/AGENTS.md. Full documentation map: docs/README.md.
Status: Architecture foundation established. No product features are implemented yet. Authentication, catalog, sales, RFQ, quotations, projects, and AI features are scaffolded as boundaries only. See Current status.
Approved stack
| Layer | Choice |
|---|
| Web app | Next.js (App Router), React, TypeScript strict, Tailwind, Radix/shadcn, RHF+Zod, next-intl |
| Data platform | Supabase — Postgres, Auth, Storage, RLS, Realtime, Queues, FTS, pg_trgm, pgvector, PostGIS |
| Schema source of truth | Supabase SQL migrations (supabase/migrations/*.sql) — no Alembic |
| Specialized service | Python 3.12+ / FastAPI — AI, OCR, RAG, documents, embeddings, workers (not the CRUD backend) |
| Hosting | Cloudflare Workers (web app) + Cloudflare Containers (FastAPI) · Supabase (data) · OpenAI · Sentry — Vercel retired (ADR-0024) |
Rationale is recorded in ADRs: ADR-0001 · ADR-0002 · ADR-0003 · ADR-0004 · ADR-0005.
Architecture overview
A modular monolith: one Next.js web app, one Supabase data platform, one specialized FastAPI service, background workers where needed. Full picture: docs/architecture/overview.md.
Repository structure
aladdin/
├── AGENTS.md # universal agent/coding rules (+ scoped AGENTS.md per area)
├── frontend/ # Next.js App Router web app (pnpm)
├── backend/ # specialized FastAPI AI/document service (uv)
├── supabase/ # migrations (schema source of truth), seed, tests, config
├── assets/brand/ # canonical brand source assets
├── data/ # local dev data (templates/seed/samples/imports)
├── docs/ # architecture, product, decisions (ADRs), database, security, operations, guides
├── agents/ # reusable agent personas (source material, not authoritative)
├── scripts/ # repo scripts
└── UI-UX/ # Pencil design files (gitignored; design.pen is canonical)
Prerequisites
- Node.js ≥ 20 and pnpm ≥ 9
- Python ≥ 3.12 and uv
- Docker (Supabase local stack + backend container)
Local setup
# 1. Install Node deps (pnpm workspace) + the Supabase CLI
pnpm install
# 2. Start the Supabase local stack (Docker)
pnpm supabase start
pnpm supabase db reset # apply migrations + seed
# 3. Backend (specialized FastAPI service)
cd backend && uv sync && cp .env.example .env && cd ..
# 4. Frontend env
cp frontend/.env.example frontend/.env.local
# put the local Supabase URL + anon key (from `pnpm supabase status`) into both env files
Detailed guides: frontend · backend · supabase. Environment rules: docs/security/secrets-and-environments.md.
Running
pnpm --filter frontend dev # web app → http://localhost:3000
cd backend && uv run uvicorn app.main:app --reload # API → http://localhost:8000/health
Tests
pnpm --filter frontend typecheck && pnpm --filter frontend lint && pnpm --filter frontend test
cd backend && uv run pytest && uv run ruff check .
pnpm supabase db lint # migration lint (RLS/isolation tests once tables exist)
Continuous integration (recommended sequence)
No CI pipeline is wired yet (deferred), but the foundation exposes stable commands ready to drop into CI. Recommended gate, in order:
# Frontend
pnpm install --frozen-lockfile
pnpm --filter frontend typecheck
pnpm --filter frontend lint
pnpm --filter frontend test
pnpm --filter frontend build
# Backend (uv-managed Python 3.12)
cd backend
uv sync --frozen
uv run ruff check .
uv run pytest
docker build -t aladdin-backend ./backend # from repo root
cd ..
# Supabase (requires Docker; validates config + clean migration apply)
pnpm exec supabase start
pnpm exec supabase db reset # applies all migrations + seed from clean
pnpm exec supabase db lint
pnpm exec supabase stop
Migration workflow
Supabase SQL migrations are the only schema source of truth (ADR-0002).
pnpm supabase migration new <descriptive_name> # new supabase/migrations/*.sql
pnpm supabase db reset # re-apply all migrations + seed locally
Never edit Production schema by hand; never use Alembic or Base.metadata.create_all() in Staging/Production. Details: docs/database/migration-strategy.md.
Agent-instruction reading order
- Root
AGENTS.md → 2. the four core-memory files + RUNTIME_STATE.md → 3. nearest scoped AGENTS.md → 4. relevant ADRs → 5. relevant product spec → 6. existing tests/conventions → 7. run validation before reporting done.
Before touching any file, read the root AGENTS.md and every applicable scoped AGENTS.md between the repo root and the target file.
Security rules (must-read)
- RLS is mandatory on tenant/user/verification/sales/project/file/AI data; every policy needs tests.
- Service-role and other server secrets never reach the browser; only validated
NEXT_PUBLIC_* vars do.
- FastAPI verifies the Supabase JWT and derives identity from the token, never the request body.
- AI retrieval applies authorization filters before returning content (no cross-org leakage).
Full model: docs/security/security-model.md.
Deployment overview
Cloudflare Workers hosts the Next.js web app (frontend/wrangler.jsonc) and Cloudflare Containers the FastAPI service (edge/backend-worker), same-origin at /api/backend through a service binding. Vercel is retired (ADR-0024). Plus Supabase (data) · Sentry (errors). Staging before Production; backward-compatible migrations. Details: docs/operations/deployment-overview.md · ADR-0009.
Current status
Implemented: repository architecture foundation — AGENTS hierarchy, ADRs, docs, Next.js scaffold (typecheck/lint/tests green), FastAPI scaffold (health + config tests), Supabase migrations/seed/test structure, env examples, CI-ready validation commands.
Not implemented yet: Authentication, Onboarding/Profiles, Catalog, Inventory, Sales workflow, RFQ, Quotations, Projects, Notifications, Advertisements, Analytics, Admin, and AI product features. Production connections and the CI/CD pipeline are also deferred.
Design files
UI-UX/design.pen is the canonical Pencil design (gitignored, private IP). Coding tasks must never edit .pen files. See UI-UX/AGENTS.md.
