# 01 — Product Architecture

## Vision

Navi is the trusted travel companion for visitors in the UAE: discover, plan, book, ride, eat, and stay safe — in one premium, multilingual app. The platform is built so that other countries (KSA, Oman, Egypt) can be added without rebuilding the system.

## Apps

| App | Audience | Stack | Notes |
|---|---|---|---|
| `apps/mobile` | Travelers | Expo, React Native, TypeScript, Expo Router, React Query, Zustand, i18next, SecureStore | Primary experience |
| `apps/website` | SEO + partner acquisition | Next.js, TypeScript | Public, indexable |
| `apps/dashboard` | Internal admin + partner staff | Next.js, TypeScript | Auth-gated, RBAC |
| `apps/api` | All clients | NestJS, TypeScript, Prisma, PostgreSQL, Redis, BullMQ | Single source of truth for business rules |

Apps **never** share business logic. They share only types, validators, design tokens, and small platform-agnostic utilities through `packages/`.

## Architecture diagram

```
Mobile  Website  Dashboard
   \      |        /
    \     |       /
     v    v      v
   ┌───────────────────┐
   │  Edge / CDN       │
   └─────────┬─────────┘
             │
   ┌─────────▼─────────┐
   │  API Gateway      │  NestJS, /v1/*
   │  Auth, RBAC,      │
   │  Rate limit, Audit│
   └─────────┬─────────┘
             │
  ┌──────────┼───────────┬──────────┬──────────┬──────────┐
  v          v           v          v          v          v
Identity  Catalog   Booking    Payment    Trip      Support
                                          Planner
  │          │           │          │          │          │
  └──────────┴─────┬─────┴──────────┴──────────┴──────────┘
                   │
        ┌──────────▼─────────┐  ┌───────┐  ┌───────┐
        │ PostgreSQL         │  │ Redis │  │  S3/  │
        │ (multi-tenant)     │  │       │  │  R2   │
        └────────────────────┘  └───────┘  └───────┘

       ┌── Provider Abstractions (swappable) ──┐
       │ Payment · Map · Sms · Ocr · Ai ·       │
       │ Translation · Push · Email · Storage   │
       └────────────────────────────────────────┘
```

## Architecture principles

1. **Separation of concerns by app boundary.** Each client is independently deployable. They communicate with the API only via versioned HTTP.
2. **Permission-based authorization.** Roles are bags of permissions. A user can hold many roles; a partner user can belong to many businesses, each with scoped permissions.
3. **Multi-country from day one.** No country/currency/locale is hardcoded. UAE is seeded.
4. **Provider abstractions for every external dependency.** Payment, map, SMS, OCR, AI, translation, push, email, storage. Default to mock implementations.
5. **Audit-by-default.** Important actions write an `AuditLog` row.
6. **Internationalization first.** EN + AR, RTL-ready. Content is translatable per row.
7. **Stateless API; cache only at the edge or in Redis.**
8. **Frontend never embeds business rules.** Screens call services; services call API clients; API clients hit `/v1/*`.
9. **Secrets only in API.** Frontend apps receive only public config and short-lived tokens.

## Cross-cutting concerns

- **Observability:** structured JSON logs, `traceId` per request, OpenTelemetry-ready, error reporting (Sentry-compatible).
- **Security:** TLS, JWT access (short) + refresh (rotated, hashed at rest), CSRF on cookie-based flows, OWASP-aligned input validation, rate limiting, security headers, dependency scanning, secret rotation.
- **Privacy:** UAE PDPL alignment (data minimization, lawful basis, retention windows, DSR endpoints), consent management.
- **Resilience:** queue-based retries for webhooks, idempotency keys for payments and bookings, dead-letter queues, graceful degradation when a provider is down.

## Out-of-scope for MVP

Multi-currency wallets, marketplace bidding, B2B partner API, live ride telematics, social feed.

## Documented assumptions

1. Launch country: UAE; launch locales: en, ar.
2. Primary currency: AED. Display only AED in MVP. Prices stored as integer minor units.
3. Phone numbers stored in E.164 format.
4. Time zone: `Asia/Dubai`. All timestamps in UTC at rest, formatted in user's locale.
5. Hotel inventory is fed by partners (manual at first, then via partner API).
6. Payments are *intent → confirm* (PSP-style). MVP runs the mock provider.
7. Mobile minimum versions: iOS 15, Android 9 (API 28).