OceanX — Restaurant & Café Management SaaS

Multi-tenant platform for restaurants, cafés, coffee shops, bakeries, fast food, juice and dessert shops, takeaways and other food businesses. One codebase and one data model; the business type only changes defaults, terminology and suggestions.

Status: Phases 1–6 are implemented. That covers the platform foundation, menu, POS, sales, kitchen display, customers and credit, quotations and invoices (with conversion and printing in the document language), inventory, purchases, suppliers, expenses, add-ons (karaoke, reservations, QR menu, online ordering, loyalty, recipes and costing, transfers), reports, notifications and six languages. See docs/PHASE-1-REPORT.md and docs/PHASES-2-6-REPORT.md for details and the known limitations.

Stack

Layer	Choice
API	Node 22, Fastify 5, TypeScript, Zod validation
Database	PostgreSQL 16, Drizzle ORM + SQL migrations (apps/api/drizzle)
Web	React 19, Vite, Tailwind CSS 4, TanStack Query, react-i18next
Shared	packages/shared — permission catalog, modules/add-ons, business types, languages, settings & request schemas, locales
Tests	Vitest integration tests against real PostgreSQL; Playwright end-to-end tests

apps/api          Fastify API (business + super admin domains)
apps/web          React SPA (business app at /, super admin console at /superadmin)
packages/shared   Code + translations shared by API and web
deploy/           nginx config for the web image
docs/             Phase reports, translation review

Architecture in one page

Two isolated security domains

	Business users	Super Admin
Login	/login	/superadmin/login (never linked from /login)
API	/api/*	/api/superadmin/*
Cookie	ox_session (path /api, SameSite=Lax)	ox_sa_session (path /api/superadmin, SameSite=Strict)
Sessions	user_sessions	super_admin_sessions
Guard	BusinessUserGuard (guards/business.ts)	SuperAdminGuard (guards/superadmin.ts)

Each guard reads only its own cookie and table, so a token from one domain can't authenticate in the other. Session tokens are random 256-bit values stored only as SHA-256 hashes. Sessions have idle and absolute expiry, and mutating requests require a per-session CSRF token. Passwords use Argon2id. Logins have lockout and per-IP rate limits. Password resets and invitations use single-use hashed tokens. Super Admins can enable TOTP 2FA: the secret is AES-256-GCM encrypted at rest, codes can't be replayed, and the session is rotated after the second factor.

Tenant isolation. The tenant (business_id) and working outlet (outlet_id) are resolved from the server-side session, never from client input. Every service query is scoped by the session's business, and request schemas never accept business_id or outlet_id (unknown keys are stripped). Composite foreign keys ((business_id, id)) on user↔role, user↔outlet and session↔outlet links mean the database itself rejects cross-tenant references. Files are resolved through the owning business row, never through a client-supplied path.

Access = subscription + plan + add-ons + permissions. services/access.ts evaluates the following on every request:

• business status (pending / active / suspended / deactivated)
• effective subscription status (trial / active / expired)
• plan modules and limits (stored in the DB, editable by Super Admin)
• granted add-ons

Role permissions only take effect if their module is in the plan and any required add-on is granted. Enforcement is server-side (requirePermission). Non-owners can only grant permissions they hold themselves, which prevents privilege escalation.

Document numbering (services/sequences.ts) allocates numbers with one atomic INSERT … ON CONFLICT DO UPDATE … RETURNING per business, scope (business or outlet), document type and period. It is safe under concurrency (tested with 100 parallel allocations), the format is configurable ({PREFIX}-{YYYY}-{SEQ} → INV-2026-00001), and numbers roll back with the transaction.

Languages, RTL and Faruma

The UI is fully translated into English, Dhivehi (dv, RTL), Hindi, Bengali, Nepali and Sinhala (764 keys each). Language is stored per user, and document language is a separate business setting. Locales live in packages/shared/locales. npm run i18n:check reports missing keys, placeholder mismatches and the Dhivehi review list. Non-English locales are code-split and loaded on demand.

Faruma font. Faruma is bundled at apps/web/public/fonts/Faruma.woff2 (with the original .ttf as a fallback) and is the only font used for Thaana text. No other Thaana font is substituted: if Faruma ever fails to load, Dhivehi pages show a visible warning: "Faruma font file is required to finalize Dhivehi typography."

Dhivehi wording that needs a native/business decision is tracked in docs/TRANSLATION-REVIEW.md (source: packages/shared/locales/review/dv.json).

Local development

Requirements: Node 20+, PostgreSQL 14+.

npm install
createdb oceanx_dev && createdb oceanx_test
cp apps/api/.env.example apps/api/.env      # set DATABASE_URL and APP_ENCRYPTION_KEY
npm run db:migrate                           # migrations + reference data (permissions, languages, plans, add-ons)
npm run superadmin:create -- --email [email protected] --name "Your Name"   # prompts for a password (min 12)
npm run dev:api                              # http://localhost:4000
npm run dev:web                              # http://localhost:5173  (proxies /api)

There are no default credentials and no demo tenants. Create businesses from the Super Admin console, or self-register at /register (Super Admin → Settings → Self-registration: open / requires approval / closed). Money and pricing. Amounts are integer minor units. The server prices every POS order, quotation, invoice, booking and public QR-menu order from database prices with the shared calculateTotals (discount allocation, service charge, inclusive/exclusive tax). Client totals are never trusted. All money received is recorded in a single payments ledger, and customer balances are calculated from it.

Public QR menu. /menu/:slug needs no login and only shows what the business publishes (QR-menu add-on + setting). Orders placed there are re-priced on the server and arrive under Online orders for staff to accept.

In development, emails (invitations, password resets) are printed to the API log (MAIL_TRANSPORT=log).

Tests

npm run test -w @oceanx/api       # API integration tests (needs PostgreSQL; TEST_DATABASE_URL, default oceanx_test)
npm run test -w @oceanx/shared    # translation completeness
npm run i18n:check                # human-readable translation report
npm run e2e                       # Playwright (needs PostgreSQL db oceanx_e2e; starts API + web itself)

Deployment

Dockerfile builds two images: api (Node) and web (nginx serving the SPA and proxying /api). docker-compose.yml wires them to PostgreSQL. Production requires APP_ENCRYPTION_KEY, COOKIE_SECURE=true (serve over HTTPS) and MAIL_TRANSPORT=smtp; the API refuses to start without them. Run migrations as a one-off job before starting new versions (node dist/db/migrate.js).