Skip to main content

Frontend — Ghasi Melmastoon

Parent docs: README · docs/01-product-overview.md · docs/02-enterprise-architecture.md · docs/05-api-design.md

Sibling indices: SERVICE_INDEX · docs/03-microservices/README.md

This folder is the canonical frontend documentation set for Ghasi Melmastoon. Three user-facing surfaces share one design system, one i18n bundle, and one stack of typed BFF clients; this index tells each contributor where to start.

1. Documents in this folder​

#DocumentAudiencePurpose
0101-web-and-mobile-specification.mdWeb devs, mobile devs, QAConsumer meta web, tenant booking web, and consumer mobile (React Native) — stack, routing, state, offline, performance, testing, security
0202-theming-and-tenant-config.mdWeb devs, mobile devs, design system maintainers, tenant-success engineersToken model, layout presets, content blocks, navigation, booking-flow config, email theme, preview/publish/rollback workflows; mirrors theme-config-service
0303-design-system.mdDesign system maintainers, web devs, mobile devs, desktop devs (renderer), QAThe @ghasi/ui-melmastoon package: tokens, primitives, components, hooks, icons, accessibility, RTL toolkit, Storybook + Ladle, distribution
—desktop/06-desktop-app-specification.mdDesktop devs, sync engineers, AI engineers, QAElectron backoffice (Node 20 main + Chromium renderer) + Vite + React + SQLite (better-sqlite3) + ONNX Runtime Node + sync engine. Read separately — not duplicated here.

Per-BFF API contract bundles are owned by each BFF's service folder; cross-link as needed:

Each API_CONTRACTS.md is the source-of-truth wire format. Generated TypeScript clients live in packages/api-clients/ in the implementation monorepo.

2. Audience guide​

RoleRead in this order
Web engineer (Next.js)01-web-and-mobile-specification.md → 02-theming-and-tenant-config.md → 03-design-system.md → relevant BFF API_CONTRACTS.md
Mobile engineer (React Native)01-web-and-mobile-specification.md (§4, §6, §7, §13) → 02-theming-and-tenant-config.md (§11) → 03-design-system.md
Desktop engineer (Electron)desktop/06-desktop-app-specification.md first; then 03-design-system.md for renderer-side primitives; theming spec for token plumbing
Design system maintainer03-design-system.md → 02-theming-and-tenant-config.md → theme-config-service/DOMAIN_MODEL.md
Tenant-success / theme reviewer02-theming-and-tenant-config.md (§14–§17) → theme-config-service/APPLICATION_LOGIC.md
QA / SDET01-web-and-mobile-specification.md (§16) → 03-design-system.md (§14, §15) → docs/testing/01-testing-strategy-qa.md
Product / PM01-web-and-mobile-specification.md (§1, §2, §11, §12, §13) → 02-theming-and-tenant-config.md (§4, §7, §17)
Security reviewer01-web-and-mobile-specification.md (§18) → 02-theming-and-tenant-config.md (§9, §15) → BFF SECURITY_MODEL.md
AI / ML engineerdesktop/06-desktop-app-specification.md (edge ONNX) → 01-web-and-mobile-specification.md (§17) → docs/08-ai-architecture.md

3. Surface-to-doc matrix​

SurfaceStackPrimary BFFSpecs you must read
Consumer Meta Web (Trivago-like discovery)Next.js 14 App Router + TS + Tailwind + React Query + Leaflet + PWAbff-consumer-service01 · 03 · BFF contracts
Tenant Booking Web (per-tenant branded)Next.js 14 App Router + TS + Tailwind + React Querybff-tenant-booking-service01 · 02 · 03 · BFF contracts
Consumer Mobile (single React Native app)React Native 0.74+ + Expo + TS + React Navigation + React Query + MMKV + Reanimated 3bff-consumer-service (browse) + bff-tenant-booking-service (book)01 · 02 · 03
Backoffice Desktop (operator)Electron + Vite + React + SQLite + ONNX Runtime Node + electron-builder + electron-updaterbff-backoffice-servicedesktop/06-desktop-app-specification.md · 03

4. Non-negotiables (frontend slice)​

  • Three frontends, one design system. All three apps consume @ghasi/ui-melmastoon; raw hex / arbitrary fonts / bespoke spacing in app code are linted out.
  • All tenant variation is data, not code. Per-tenant code paths in shared apps are forbidden; theming/config flows through theme-config-service only.
  • All API access goes through a BFF. Direct calls from web/mobile to domain services are forbidden.
  • RTL + LTR are first-class. Pashto, Dari, Persian, Arabic, English, French day-one. Logical CSS properties everywhere; mirrored iconography is explicit.
  • Offline behavior is opinionated. Web has a PWA browse cache; mobile caches recent results in MMKV; desktop is genuinely offline-first with a real local DB and a real sync engine — see the desktop spec.
  • Performance budgets are enforced in CI (see 01-web-and-mobile-specification.md §15).

5. Implementation monorepo (separate repo)​

The frontend code does not live in this documentation repo. Implementation lives in the ghasi-melmastoon monorepo with this layout (detailed in 01-web-and-mobile-specification.md §5):

apps/web-meta            apps/web-tenant-booking            apps/mobile
apps/desktop-backoffice  (Electron renderer hosts a Vite-React app)
packages/ui-melmastoon   packages/i18n   packages/api-clients   packages/icons
packages/feature-meta-search   packages/feature-booking-flow

Tooling: pnpm, Turborepo, Changesets, ESLint, Prettier, TypeScript strict. CI runs typecheck, lint, unit + component + visual regression + e2e on every PR; performance budgets are gated by Lighthouse-CI on web, Reassure on mobile.