02 — Enterprise Architecture

Companion: 01 Product Overview · 03 Microservices Catalog · 04 Event-Driven Architecture · 05 API Design · 07 Security & Tenancy · 08 AI Architecture · 09 Lock & Key Integration · 12 Desktop Spec · ADR-0001 Core Stack · ADR-0002 Multi-Tenancy · ADR-0003 Electron Offline-First · ADR-0004 Lock Abstraction

This document is the canonical enterprise-architecture view of Ghasi Melmastoon. It defines business architecture, application layering, bounded contexts, microservice topology, BFF strategy, multi-tenancy, the event backbone, the offline-sync model, AI placement, GCP reference topology, security posture, resilience and cost posture, compliance, and the anti-patterns we explicitly forbid. All downstream documents (per-service bundles, ADRs, frontend, journeys, testing) defer to this document for strategic architecture statements.

1. Business Architecture

1.1 Stakeholders & Personas

Side	Persona	Primary Goals
Guest	Independent Traveler	Find a room near a place, in budget, on dates; book without leaving the platform; pay how the local market allows
Guest	Business Traveler	Book repeatedly with the same tenant; folio receipt; smooth check-in even on poor network
Tenant	Hotel Owner	Onboard property fast; control branding; see revenue truthfully across channels and currencies
Tenant	General Manager	Daily KPIs; AI insights; staff productivity; intervention on at-risk reservations
Tenant	Front Desk	Check-in / out; walk-in booking; key issuance; folio updates even when offline
Tenant	Housekeeping	Receive room assignments; flip status; raise maintenance tickets
Tenant	Maintenance	Triage tickets; close work orders with parts/labor
Tenant	Finance / Admin	Reconcile cash + card + MFS; invoices; tax exports; payouts
Tenant	Chain Operator	Cross-property views; central rate strategy; consolidated reporting
Internal	Platform Admin	Tenant lifecycle; billing reconciliation; abuse handling
Internal	Compliance Officer	Audit logs; AI provenance review; data subject requests; lock-credential isolation audits
Partner	Lock Vendor	Pluggable adapter implementing the `LockPort`; no platform code changes per vendor
Partner	Payment Provider	Pluggable adapter via `payment-gateway-service`; cash, card, MFS, PayPal, VISA

1.2 Value Streams

The platform is organized around four value streams. Each is a sequence of capabilities; each capability is owned by one or two bounded contexts.

Discover → Book (Guest stream) — meta-search, filter, compare, map, select, render tenant theme, choose room/rate, capture details, pay (PayPal / Visa / Debit / cash-on-arrival / MFS), confirm.
Operate → Sync → Optimize (Backoffice stream) — open shift, work the day from the Electron desktop app (offline if needed), check guests in, dispatch housekeeping, reconcile folios, sync deltas back to the cloud, surface AI insights for the next shift.
Configure → Theme → Launch (Tenant onboarding stream) — create tenant, attach property, define rooms / rate plans / policies, customize theme tokens, choose layout presets, content blocks, locales (RTL/LTR), payment + lock vendors, go live.
Audit → Comply (Platform stream) — capture immutable audit log, surface AI provenance, run data-residency proofs, fulfill GDPR DSARs, isolate lock credentials, isolate PCI scope, anchor tamper evidence daily.

1.3 Capability Map (top-level)

┌───────────────────────────────────────────────────────────────────────────────┐
│ Identity & Access  │ Tenant & Property Mgmt │ Catalog & Discovery │ Pricing  │
│ Reservations       │ Inventory & Availability│ Housekeeping        │ Mainten. │
│ Folio & Billing    │ Payments (multi-rail)   │ Lock & Key          │ Comms    │
│ Theming & Content  │ Search Aggregation      │ AI Orchestration    │ Sync     │
│ Reporting & BI     │ File / Media            │ Notifications       │ Audit    │
└───────────────────────────────────────────────────────────────────────────────┘

Every capability maps to one owning context (no shared aggregates) and is delivered by one owning microservice (no shared schemas). Cross-capability work happens through events, never through cross-service DB joins.

2. Application Architecture (Clean / Hexagonal)

Every backend microservice follows the same Clean / Hexagonal layering. Frontend apps follow the analogous mirror.

┌──────────────────────────── Presentation ─────────────────────────────────┐
│ NestJS Controllers · WebSocket / SSE handlers · Sync HTTP handlers        │
│ Problem+JSON error shaping · OpenAPI emission                             │
└──────────────┬────────────────────────────────────────────────────────────┘
               │
┌──────────────▼ Application ───────────────────────────────────────────────┐
│ Use-Cases · Command / Query handlers · DTOs · Mappers                     │
│ Ports: AIClient · EventPublisher · Clock · IdGenerator · LockPort         │
│        PaymentPort · NotificationPort · SyncClient · IdentityResolver     │
└──────────────┬────────────────────────────────────────────────────────────┘
               │
┌──────────────▼ Domain (pure TypeScript) ──────────────────────────────────┐
│ Aggregates · Entities · Value Objects · Domain Events · Domain Services   │
│ Invariants enforced here; zero framework imports; zero I/O                │
└──────────────┬────────────────────────────────────────────────────────────┘
               │
┌──────────────▼ Infrastructure ────────────────────────────────────────────┐
│ Postgres repos (Drizzle / pg) · Pub/Sub adapter · Cloud Storage adapter   │
│ Redis (Memorystore) cache · Outbox publisher · Saga engine                │
│ Vendor adapters: TTLock · Salto · Assa Abloy · Generic Wiegand            │
│ Vendor adapters: PayPal · Stripe · MFS · Cash · Vertex AI · ONNX Runtime  │
└───────────────────────────────────────────────────────────────────────────┘

Strict dependency rule — outer layers depend inward only:

Presentation → Application
Application → Domain
Infrastructure → Application (for ports) and Domain (for types only)
Domain depends on nothing.

This is enforced in CI by dependency-graph analysis. Any import of NestJS, Pub/Sub client, pg, axios, fetch, process.env, or vendor SDKs from inside /domain fails the build.

Per-service module structure (every service identical):

services/<service-name>/
├── src/
│   ├── presentation/          # controllers, ws, sse, health
│   ├── application/
│   │   ├── ports/             # interfaces only
│   │   ├── use-cases/
│   │   └── dto/
│   ├── domain/                # pure TS — no framework imports
│   │   ├── aggregates/
│   │   ├── entities/
│   │   ├── value-objects/
│   │   ├── events/
│   │   └── services/
│   └── infrastructure/
│       ├── adapters/          # vendor SDKs live here, only here
│       ├── repositories/
│       ├── outbox/
│       ├── pubsub/
│       ├── http-clients/
│       └── config/
├── test/                      # unit (domain), integration (testcontainers), contract (pact)
├── openapi.json               # emitted from controllers
└── module.ts                  # NestJS DI wiring (composition root)

The frontend mirror (Next.js, React Native, Electron renderer):

app/      → presentation (routes, components)
hooks/ + services/ → application (use-cases, queries, mutations)
lib/domain/        → pure TS domain models — no React, no fetch
lib/adapters/      → HTTP clients, IndexedDB / SQLite, sync, AI client

3. Bounded Contexts

Ghasi Melmastoon is decomposed into 20 bounded contexts grouped by domain class. The full DDD treatment (aggregates, invariants, ubiquitous language, conflict policies) lives in the per-service deep docs.

3.1 Context List

#	Context	One-line purpose
1	Identity & Access	Authenticate users; issue + rotate JWTs; SSO (OIDC/SAML); WebAuthn; device binding
2	Tenant	Tenant lifecycle, plan, settings, RBAC roles, memberships, data residency pin
3	Property	Properties, room types, rooms, amenities, geo, photos, policies
4	Reservation	The authoritative booking aggregate (state machine, holds, modifications, cancellations)
5	Inventory	Per-room-per-night availability and allocation; oversell guards
6	Pricing	Rate plans, BAR / weekly / corporate, dynamic price hints, currency conversion
7	Housekeeping	Tasks, assignments, room status transitions, SLAs
8	Maintenance	Work orders, tickets, parts/labor, escalation
9	Folio & Billing	Folio ledger per reservation; charges, taxes, refunds; immutable financial entries
10	Payments	Multi-rail payment orchestration: PayPal, Visa/Debit, cash-on-arrival, MFS
11	Lock & Key	Vendor-agnostic key lifecycle (issue / update / revoke / suspend) over `LockPort`
12	Notification & Communication	Email / SMS / push / WhatsApp via pluggable adapters; preference management
13	Theme & Content	Tenant branding tokens, layout presets, content blocks, RTL/LTR defaults
14	Search & Discovery	Cross-tenant meta-search index (the only legitimate cross-tenant read path)
15	AI Services	The single AI gateway: cloud (Vertex AI) + edge (ONNX Runtime); prompts; provenance; HITL
16	File & Media	Image upload, optimization, signed URLs, virus scan, invoice PDFs
17	Reporting	Templated reports, exports, scheduled deliveries
18	Analytics	Aggregations, dashboards, occupancy, revenue, channel mix, forecasts
19	Audit & Compliance	Immutable append-only log; daily Merkle anchoring; DSAR fulfilment orchestration
20	Offline Sync	The single sync protocol consumed by the Electron desktop app

Domain class: Core (Reservation, Inventory, Pricing, Lock & Key, AI Services, Offline Sync, Search), Supporting (Property, Housekeeping, Maintenance, Folio & Billing, Theme & Content, Reporting, Analytics), Generic (Identity, Tenant, Payments, Notification, File & Media, Audit).

3.2 Context Map (relationships)

Every cross-context relationship is one of: SK (Shared Kernel — value objects only), CS (Customer/Supplier), CF (Conformist), ACL (Anti-Corruption Layer), OHS (Open Host Service), PL (Published Language), PA (Partnership). No "direct dependency" outside this taxonomy.

                          ┌──────────────┐
                          │   Tenant     │   SK: TenantId, OrgUnitId
                          └──────┬───────┘
                                 │
       ┌───────────────┐         │         ┌──────────────────┐
       │   Identity    │─── CF ──┼── CF ───│  Notification    │
       │  (JWT, SSO)   │         │         └──────────────────┘
       └───────┬───────┘         │
               │                 │
        ┌──────┴───────┐    ┌────▼────────┐    ┌──────────────────┐
        │   Property   │    │  Theme &    │    │   File & Media   │
        │  (CS → Inv)  │    │  Content    │    │   (CS via PL)    │
        └──────┬───────┘    │  (PL)       │    └──────────────────┘
               │            └────┬────────┘
        ┌──────▼────────┐        │
        │  Inventory    │◄───────┴── consumed by Tenant Booking + Search
        │  (CS → Resv)  │
        └──────┬────────┘
               │
        ┌──────▼────────┐    ┌──────────────┐    ┌──────────────────┐
        │  Reservation  │◄───│   Pricing    │    │    AI Services   │
        │   (Core +     │ CS │  (CS → Resv) │    │  (OHS + PL via   │
        │    saga hub)  │    └──────────────┘    │   AIProvenance)  │
        └──┬─────┬───┬──┘                        └──────────────────┘
           │     │   │                                    ▲
   ┌───────▼┐  ┌─▼─────────┐  ┌──────────────┐           │
   │ Folio  │  │ Lock &    │  │ Housekeeping │ ── OHS ───┘
   │ (CS,   │  │ Key       │  │ + Maintenance│
   │  ACL)  │  │ (OHS, PL) │  └──────┬───────┘
   └────┬───┘  └─────┬─────┘         │
        │            │               │
   ┌────▼─────┐  ┌───▼────────────┐  │
   │ Payments │  │ Vendor adapters│  │
   │  (ACL)   │  │ TTLock / Salto │  │
   └──────────┘  │ AssaAbloy /    │  │
                 │ Generic        │  │
                 └────────────────┘  │
                                     │
   ┌──────────────────┐   ┌──────────▼────────────┐
   │  Search & Disco  │◄──┤   Reservation +       │  projection only
   │  (cross-tenant   │CS │   Inventory + Pricing │
   │   read model)    │   └───────────────────────┘
   └──────────────────┘
                                     │
   ┌──────────────────┐   ┌──────────▼────────────┐
   │  Reporting +     │◄──┤   All write contexts  │  projection only
   │  Analytics (CS)  │   └───────────────────────┘
   └──────────────────┘
                                     │
   ┌──────────────────┐               │
   │  Offline Sync    │── OHS + CF ───┘   one protocol, every replicable context conforms
   │  (cross-cutting) │
   └──────────────────┘
                                     │
   ┌──────────────────┐               │
   │  Audit &         │── append-only consumer of every domain event
   │  Compliance      │
   └──────────────────┘

Key relationship notes:

External lock vendors → Lock & Key is an ACL: vendor SDK types never leak past the adapter. Internal shape is a single KeyCredential value object regardless of vendor.
External payment processors → Payments is an ACL for the same reason.
Vertex AI / ONNX Runtime → AI Services is an ACL; downstream services see only AICompletion, Embedding, AIArtifact, and AIProvenance.
Search & Discovery is the only context that legitimately reads across tenants, and it does so via projected read models — never through cross-tenant joins.

4. Microservices Topology

22 microservices, each owning one bounded context (or a slice of one). All NestJS, all TypeScript, all on Cloud Run. Grouped here by capability cluster.

4.1 Identity & Tenancy

Service	Owns	Consumes	Produces
`iam-service`	Users, sessions, credentials, JWT/JWKS, MFA, WebAuthn, device bindings	tenant.created.v1	iam.user.created.v1, iam.session.issued.v1, iam.device.bound.v1
`tenant-service`	Tenant, plan, settings, OrgUnit, Role, Membership, residency pin	iam.user.created.v1	tenant.created.v1, tenant.role.granted.v1, tenant.settings.changed.v1

4.2 Property

Service	Owns	Consumes	Produces
`property-service`	Property, RoomType, Room, Amenity, geo, photos, policies	tenant.created.v1	property.created.v1, property.room.added.v1, property.room.archived.v1

4.3 Reservations & Inventory

Service	Owns	Consumes	Produces
`reservation-service`	Reservation aggregate, holds, state machine, modifications	inventory.allocated.v1, payment.captured.v1, lock.key.issued.v1	reservation.held.v1, reservation.confirmed.v1, reservation.cancelled.v1, reservation.checkout.v1, reservation.dates_changed.v1
`inventory-service`	Per-room-per-night availability; allocation ledger	property.room.added.v1, reservation.confirmed.v1, reservation.cancelled.v1	inventory.allocated.v1, inventory.released.v1, inventory.oversell_blocked.v1

4.4 Pricing

Service	Owns	Consumes	Produces
`pricing-service`	Rate plans, calendars, currency conversion, dynamic price hints	property.created.v1, ai.pricing_hint.completed.v1	pricing.rate_plan.changed.v1, pricing.calendar.updated.v1

4.5 Operations

Service	Owns	Consumes	Produces
`housekeeping-service`	Tasks, assignments, room-status flow, SLAs	reservation.checkout.v1, property.room.added.v1	housekeeping.task.assigned.v1, housekeeping.room.status_changed.v1
`maintenance-service`	Work orders, parts, labor, escalation	housekeeping.task.flagged.v1	maintenance.ticket.opened.v1, maintenance.ticket.closed.v1

4.6 Finance

Service	Owns	Consumes	Produces
`billing-service`	Folio, charges, taxes, refunds, invoices	reservation.confirmed.v1, payment.captured.v1, payment.refunded.v1	folio.charge.posted.v1, folio.refund.posted.v1, invoice.issued.v1
`payment-gateway-service`	Payment intents; PayPal / Visa / cash-on-arrival / MFS adapters	folio.charge.posted.v1	payment.intent.created.v1, payment.captured.v1, payment.refunded.v1, payment.failed.v1

4.7 Communication

Service	Owns	Consumes	Produces
`notification-service`	Templates, preferences, multi-channel send (email / SMS / push / WhatsApp)	reservation.confirmed.v1, payment.failed.v1, lock.key.issued.v1	notification.delivered.v1, notification.bounced.v1

4.8 AI

Service	Owns	Consumes	Produces
`ai-orchestrator-service`	The single AI gateway: completion, embedding, vision, moderation, TTS; cloud (Vertex AI) + edge dispatch; provenance; HITL records	(called via port `AIClient` by every service)	ai.gateway.call.completed.v1, ai.pricing_hint.completed.v1, ai.anomaly.detected.v1, ai.inference.local.completed.v1

4.9 Theming

Service	Owns	Consumes	Produces
`theme-config-service`	Branding tokens, layout presets, content blocks, locale defaults, RTL/LTR	tenant.created.v1, tenant.settings.changed.v1	theme.preset.published.v1, theme.tokens.changed.v1

4.10 Lock

Service	Owns	Consumes	Produces
`lock-integration-service`	The `LockPort`; vendor adapters (TTLock, Salto, Assa Abloy, Generic Wiegand); key lifecycle saga	reservation.confirmed.v1, reservation.cancelled.v1, reservation.checkout.v1, reservation.dates_changed.v1	lock.key.issued.v1, lock.key.updated.v1, lock.key.revoked.v1, lock.key.suspended.v1, lock.vendor.error.v1

4.11 Search

Service	Owns	Consumes	Produces
`search-aggregation-service`	Cross-tenant searchable read model; geo + availability + price; pgvector for semantic	property.created.v1, inventory.allocated.v1, pricing.calendar.updated.v1	search.index.refreshed.v1

4.12 Cross-Cutting

Service	Owns	Consumes	Produces
`file-storage-service`	Upload, optimization, signed URLs, virus scan, PDF render	(called via port)	file.uploaded.v1, file.scanned.v1
`reporting-service`	Templated reports, scheduled exports	(consumes everything via projections)	report.generated.v1
`analytics-service`	Aggregations, dashboards, occupancy, revenue, channel mix	(consumes everything via projections)	analytics.snapshot.computed.v1
`audit-service`	Immutable append-only audit log; Merkle daily anchor; DSAR orchestration	(consumes every `*.v1`)	audit.dsar.fulfilled.v1, audit.merkle.anchored.v1
`sync-service`	The single `/sync/v1/pull	push` protocol; conflict resolution; outbox cursors	(consumes every replicable event)

4.13 BFFs (Backends-for-Frontend)

Service	Owns	Consumes	Produces
`bff-consumer-service`	Meta layer aggregation; map-friendly bounding-box queries; cross-tenant pricing rollups	search.index.refreshed.v1 (read)	none (read-only)
`bff-tenant-booking-service`	Per-tenant booking funnel: room/rate/dates/guests/payment; theme injection	theme.tokens.changed.v1 (read)	bff.booking.intent.captured.v1
`bff-backoffice-service`	Electron desktop session shape; sync façade; AI surface; dashboard composition	sync.cursor.advanced.v1 (read)	bff.backoffice.session.opened.v1

Topology total: 2 + 1 + 2 + 1 + 2 + 2 + 1 + 1 + 1 + 1 + 1 + 5 + 3 = 22 services.

5. Three BFFs

We deliberately ship three Backends-for-Frontend rather than one. Each surface has different audience semantics, different latency budgets, different security posture, and different data shapes; collapsing them into one BFF either over-fetches or under-protects.

BFF	Audience	Auth surface	Hot read shape	Why it cannot be merged
`bff-consumer-service`	Anonymous + low-trust guests on web/mobile	Anonymous + soft session	Cross-tenant geo-bounded availability + min/max price + amenity facets	Cross-tenant by design; aggressive cache; never sees a tenant JWT; never touches lock/payment internals
`bff-tenant-booking-service`	Guest scoped to one tenant; in-funnel	Anonymous + booking session token; payment-scoped JWT at checkout	Per-tenant theme + room/rate/availability + funnel state	Tenant-scoped cache; payment redirect orchestration; theme hot-injection; one tenant per request
`bff-backoffice-service`	Authenticated staff; long-lived; offline-first	Tenant JWT + device binding + role+attribute checks	Per-staff dashboard; sync façade; AI surface; lock control	Strong auth; full RBAC/ABAC; sync protocol surface; never exposed to anonymous traffic; talks to `lock-integration-service`

A single BFF would either (a) leak privileged shapes to anonymous consumers, (b) bloat anonymous responses with staff-only fields, or (c) force one cache policy on three incompatible workloads. Three BFFs let each one be tuned, rate-limited, and scaled independently on Cloud Run, and let edge security policy at Kong/Cloud Armor differ per surface.

6. Multi-Tenancy Architecture

Multi-tenancy is enforced at four layers; every layer is a defense in depth.

Layer	Mechanism	Failure mode if breached
API edge	JWT carries `tenant_id`; gateway sets `RequestContext.tenant`; deny if absent on tenant-scoped routes	Request rejected at gateway
Application	Use-cases require `TenantId` parameter; cross-tenant references rejected at constructor	`DomainError.CrossTenant` thrown before persistence
Domain	`TenantId` is a value object on every aggregate root; aggregates refuse construction without it	Domain layer refuses to materialize
Database	`tenant_id` column + Postgres Row-Level Security policies; PgBouncer-init sets `app.tenant_id`; service accounts cannot bypass except for declared ops jobs	Even a bug in app code cannot leak rows

6.1 Hybrid Tenancy Model (canonical — see ADR-0002)

Service	Model	Why
Most services (20 of 22)	Shared schema + `tenant_id` + RLS	Operationally sane at 1000+ tenants; cheap; standard tooling
`billing-service`	Schema-per-tenant	Easier financial audit; clean tenant export/delete on offboarding; per-tenant retention pins
`payment-gateway-service`	Schema-per-tenant	PCI scope minimization per tenant; vendor token isolation; simpler regulatory per-tenant proofs

Cross-tenant queries go only through search-aggregation-service, which holds projected read models (no PII, no payment details). No other service has cross-tenant read paths.

6.2 Tenant Context Propagation

JWT  ──►  Kong (validates signature, copies `tenant_id` into X-Tenant-Id)
      ──►  NestJS RequestContext middleware (binds AsyncLocalStorage)
      ──►  Use-case receives TenantId param explicitly (not implicit)
      ──►  Repository sets `app.tenant_id` on Postgres connection (via PgBouncer init or session_authorization)
      ──►  RLS policies filter every row
      ──►  Outbox writer validates payload `tenantId` matches request context before commit

6.3 Cross-Tenant Safe Paths

The only legitimate cross-tenant reads are:

search-aggregation-service — projects from property-service, inventory-service, pricing-service events; serves the consumer meta layer.
Platform-admin reports under explicit elevation (audit logged, one-time tokens).
audit-service — append-only by design; reads gated by compliance role and DSAR scope.

Everything else — including chain operators — uses tenant-scoped APIs and joins client-side under explicit per-tenant tokens.

7. Event-Driven Backbone

7.1 Backbone

GCP Pub/Sub is the messaging substrate. Subject pattern: {service}.{aggregate}.{event}.v{N}. Examples:

reservation.confirmed.v1
inventory.allocated.v1
payment.captured.v1
lock.key.issued.v1
ai.gateway.call.completed.v1
sync.cursor.advanced.v1

7.2 Transactional Outbox

Every write that produces an event uses the outbox pattern:

BEGIN
  UPDATE reservation SET state='confirmed' WHERE ...;
  INSERT INTO outbox (id, topic, payload, headers, created_at) VALUES (...);
COMMIT

A separate publisher process drains the outbox to Pub/Sub. This guarantees at-least-once delivery; consumers are required to be idempotent (keyed by eventId + content hash).

7.3 Saga: Booking → Inventory → Payment → Key Issuance

The booking saga is the most-trafficked multi-service orchestration in the platform.

[Guest hits Pay]
    │
    ▼
bff-tenant-booking-service  ──►  reservation-service
                                       │
                                       │ (1) reservation.held.v1  (TTL 10 min)
                                       ▼
                                inventory-service  ──►  inventory.allocated.v1
                                       │
                                       │ (2) charge intent
                                       ▼
                                payment-gateway-service  ──►  payment.captured.v1 / payment.failed.v1
                                       │
                                       ├─ on captured ──►  reservation.confirmed.v1
                                       │                          │
                                       │                          ▼
                                       │                  lock-integration-service ──► lock.key.issued.v1
                                       │                          │
                                       │                          ▼
                                       │                  notification-service ──► email/SMS confirmation + key
                                       │
                                       └─ on failed ──►  inventory.released.v1 + reservation.cancelled.v1

Compensation paths are first-class. Every forward step has a declared compensation (release inventory, void payment intent, revoke key). The orchestrator (reservation-service) tracks saga state in its own DB; saga state is never stored in another service.

7.4 Dead-Letter & Replay

Every Pub/Sub subscription has a DLQ. Messages fail-forward into the DLQ after configured retry exhaustion (exponential with jitter, max 5 attempts). The DLQ is monitored; a replay tool re-publishes after fix. Consumers idempotency keys ensure replay is safe.

8. Sync & Offline Architecture

The Electron desktop app is offline-first, not "offline-tolerant". The sync engine is owned by sync-service and consumed via /sync/v1/pull|push. (Web/mobile guest surfaces are online-first with PWA browse cache; only the desktop app is true offline-first.)

8.1 Protocol Surface

POST /sync/v1/pull
  Headers:  Authorization, X-Tenant-Id, X-Device-Id, X-Sync-Cursor
  Body:     { scopes: ['reservation','room','folio_draft', ...], maxBatch: 500 }
  Response: { deltas: [...], nextCursor: '...', heartbeat: ... }

POST /sync/v1/push
  Headers:  Authorization, X-Tenant-Id, X-Device-Id, Idempotency-Key
  Body:     { mutations: [{ clientMutationId, aggregate, op, payload, baseVersion, vectorClock }] }
  Response: { results: [{ clientMutationId, status, serverState? , conflict? }] }

8.2 Per-Aggregate Conflict Policy

Every replicable aggregate declares exactly one policy. The matrix below is canonical for Melmastoon; new aggregates must be added here.

Aggregate	Policy	Why
`Reservation` (state)	server_authoritative	Booking state is server-issued
`Reservation` (notes)	lww by `updatedAt`	Free-text notes rarely conflict
`Folio` charges	append_only	Money never overwrites; only adds
`Folio` payments	append_only	Same
`Inventory`	server_authoritative	Allocation must come from authority; client cannot decide
`Room.status`	max-of by status priority `clean<dirty<OOO<OOS` then by timestamp	Worse status wins; protects guest experience
`HousekeepingTask.assignment`	lww by `updatedAt`	Assignment churn is fine
`HousekeepingTask.completion`	append_only	Audit trail
`MaintenanceTicket` events	append_only	Audit
`KeyCredential` lifecycle	server_authoritative	Lock vendor + saga is the source
`Guest` profile	lww by `updatedAt`	Multi-device staff edits
`StaffSchedule`	server_authoritative	Manager-issued
`Notification.preferences`	lww	User-set
`AI insight ack`	append_only	Append-only acknowledgement log

Money and inventory never use last-write-wins. This is non-negotiable.

8.3 Device Binding & Cursors

Every device pairs with the platform via iam-service; pairing produces a DeviceId and a device-bound key (stored in OS keychain via keytar).
Sync cursors are scoped to (tenantId, userId, deviceId, scope) and persisted in Firestore (cheap, regional, low-ops).
Outbox cursors per device are stored in Firestore as well; the desktop app's local SQLite outbox is the source of truth pre-sync, Firestore is the post-sync record.

8.4 Failure Modes

Failure	Behavior
Network drop during pull	Cursor unchanged; resume on next attempt
Network drop during push	Idempotency key + `clientMutationId` make resend safe
Conflict	Recorded in `sync.conflicts`; surfaced in UI for human-resolvable cases (notes, profile); auto-resolved per policy otherwise
Device clock skew	Server overrides timestamps for `lww` decisions; vector clocks for ordering
Stale device (revoked or re-paired)	Pull returns 401 with re-pair instructions; local DB stays read-only until re-paired

9. AI Architecture

ai-orchestrator-service is the single AI gateway. No service calls Vertex AI, OpenAI, or any model directly. Every service depends on ports/AIClient, whose default adapter routes to ai-orchestrator-service.

9.1 Routing

caller (any service or BFF)
    │  AIClient.complete({prompt, model, capability, tenantId, ...})
    ▼
ai-orchestrator-service
    │
    ├─ pre-call: moderation, PII redaction, budget check, prompt-version pin
    │
    ├─ route decision:
    │     - cloud (Vertex AI) for heavy LLM, vision, embeddings, TTS
    │     - edge  (ONNX Runtime Node on the desktop main process) for offline / low-latency / sensitive-data
    │
    ├─ post-call: moderation on output, provenance stamping, cost recording
    │
    └─ emit: ai.gateway.call.completed.v1   (with full provenance)

9.2 Edge Inference on Electron

The Electron desktop app ships with a small set of ONNX models executed by ONNX Runtime Node in the main process (Node 20). Renderer never has model bytes; the renderer requests inference via the preload-exposed window.melmastoon.ai.infer(...) IPC. Models are signed; tampering invalidates the signature and the model refuses to load.

Edge-eligible capabilities:

Housekeeping order optimization (small TSP-like model)
Anomaly heuristics (booking, payment, lock)
Demand smoothing for next 7 days
Image quality scoring for property photo upload

Edge inference still emits ai.inference.local.completed.v1 to the local outbox; on next sync the event is replayed for audit.

9.3 Provenance & HITL

Every AI artifact persists with aiProvenance:

interface AIProvenance {
  model: string;              // e.g. 'gemini-1.5-pro' or 'melmastoon-edge-anomaly-v3.onnx'
  version?: string;
  promptId?: string;
  promptVersion?: SemVer;
  traceId: string;            // W3C traceparent
  decisionId?: string;        // ties to HITL acceptance
  local: boolean;             // true if edge
  generatedAt: ISODate;
  reviewedBy?: UserId;
  reviewedAt?: ISODate;
  cost?: { microUSD: number; tokens?: { in: number; out: number } };
  safety: { input: SafetyVerdict; output: SafetyVerdict };
  cacheHit: boolean;
}

HITL gates are required for any irreversible or guest-facing AI action: pricing publish, anomaly-driven cancellation, AI-suggested overbook resolution, AI-drafted guest communication. The action stays in draft_ai state until a human with authority promotes it.

10. GCP Reference Topology

                                  Internet
                                     │
                  ┌──────────────────▼──────────────────┐
                  │  Cloud Load Balancer + Cloud Armor  │  WAF, DDoS, geo-rules
                  └──────────────────┬──────────────────┘
                                     │
                  ┌──────────────────▼──────────────────┐
                  │            Kong Gateway             │  TLS, JWT, rate limit, headers
                  └──────────────────┬──────────────────┘
                                     │
        ┌─────────────────┬──────────┴──────────┬─────────────────┐
        ▼                 ▼                     ▼                 ▼
  ┌──────────┐     ┌──────────────┐     ┌──────────────┐   ┌──────────────┐
  │ Next.js  │     │ bff-consumer │     │ bff-tenant-  │   │ bff-back-    │
  │ SSR      │     │              │     │ booking      │   │ office       │
  │ (Cloud   │     │ (Cloud Run)  │     │ (Cloud Run)  │   │ (Cloud Run)  │
  │  Run)    │     └──────┬───────┘     └──────┬───────┘   └──────┬───────┘
  └──────────┘            │                    │                  │
                          └─────────┬──────────┴──────┬───────────┘
                                    ▼                 ▼
                            ┌─────────────────────────────────┐
                            │  Cloud Run microservices x 19   │
                            │  (NestJS, autoscaled, scale-to- │
                            │   zero on low-traffic services) │
                            └────┬────────┬────────┬──────────┘
                                 │        │        │
              ┌──────────────────┘        │        └─────────────────────┐
              ▼                           ▼                              ▼
       ┌─────────────┐           ┌────────────────┐            ┌─────────────────┐
       │ Cloud SQL   │           │   Pub/Sub      │            │  Cloud Storage  │
       │ (Postgres,  │           │  (topics +     │            │  (media, PDFs,  │
       │  per-svc    │           │   DLQ + sub.)  │            │   theme assets) │
       │  schemas;   │           └────────────────┘            └─────────────────┘
       │  RLS)       │
       └─────────────┘                  │                              │
              │                         │                              │
              │                         │                              │
       ┌─────────────┐           ┌────────────────┐            ┌─────────────────┐
       │ Memorystore │           │ Firestore      │            │  Vertex AI      │
       │ (Redis;     │           │ (sync cursors, │            │  (LLM, vision,  │
       │  cache,     │           │  outbox marks, │            │   embeddings,   │
       │  rate-      │           │  device pair)  │            │   TTS) called   │
       │  limit)     │           └────────────────┘            │  ONLY by ai-    │
       └─────────────┘                                         │  orchestrator   │
                                                               └─────────────────┘

                            ┌─────────────────────────────────┐
                            │  Secret Manager  (all secrets)  │
                            │  KMS             (envelope keys)│
                            │  Cloud Logging / Monitoring /   │
                            │  Trace  (OTel everywhere)       │
                            │  Artifact Registry (images)     │
                            └─────────────────────────────────┘

Notes:

Cloud Run gives us scale-to-zero for low-traffic services (maintenance-service, reporting-service, audit-service).
pgvector runs as an extension inside Cloud SQL; no separate vector DB.
All east-west service traffic stays inside the VPC; only Kong is on the public LB.
Secret Manager fronts every secret; rotated per security policy. No secrets in env files committed to git, no secrets in client bundles.

11. Security Posture

Layer	Control
Transport	TLS 1.3 everywhere; HSTS at edge; mTLS between Cloud Run services where supported, otherwise short-lived service-account JWTs
AuthN	JWT (15-min access, 30-day rotating refresh); OIDC/SAML SSO for chain operators; WebAuthn opt-in; magic link for low-trust onboarding
AuthZ	RBAC (coarse) + ABAC (fine: `tenantId`, `propertyId`, `role`, `data_residency`)
Tenant isolation	RLS on every table; PgBouncer init sets `app.tenant_id`; cross-tenant references rejected at domain layer
At-rest encryption	AES-256 via Google-managed KMS by default; per-tenant CMEK on Plus plan; per-device key for desktop SQLite
Secrets	Secret Manager only; rotated; never in client bundles; never in code; access audited
Lock credentials	Isolated namespace inside `lock-integration-service`; encrypted at rest with a separate KMS key; never logged; never exposed via any other service's API
Payment data	PCI scope minimized to `payment-gateway-service`; tokens only past the boundary; PAN never persisted; schema-per-tenant audit isolation
Desktop	OS keychain via `keytar` for refresh token + device key; SQLite encrypted with device-derived key; `nodeIntegration: false`, `contextIsolation: true`, signed installer + signed updates via electron-updater
Audit	Immutable append-only log (`audit-service`); daily Merkle root anchored externally for tamper evidence
AI	Pre/post moderation; PII redaction before any cloud-bound payload; per-tenant AI budget; HITL gates for irreversible actions

Full detail in 07 Security & Tenancy.

12. Resilience & Performance

Concern	Mechanism
Service-to-service failure	Circuit breaker per port; retry with exponential backoff + jitter; fail-fast budget per request
Backpressure	Pub/Sub buffers absorb spikes; consumer concurrency capped per service; flow-control tokens for sync push
Hot-read latency	Memorystore (Redis) for tenant settings, theme tokens, room/rate snapshots; per-tenant cache namespaces
Edge cache	Cloud CDN for static + tenant theme assets; signed URLs for media
Booking funnel	Idempotency keys on every mutation; reservation hold TTL 10 min; saga compensations always declared
Search	pgvector + GIN indexes on hot facets; bounding-box geo queries; per-tenant cardinality cap on facets
Desktop sync	Per-aggregate conflict policy; batch size cap; resumable cursors; exponential backoff on 5xx
Graceful degradation	Booking flow keeps working with cash-on-arrival when `payment-gateway-service` is degraded; check-in keeps working with offline key issuance queue when `lock-integration-service` is degraded; AI features degrade silently to non-AI defaults when `ai-orchestrator-service` is degraded

13. Cost Posture

The platform must be cheap enough for an 8-room independent guesthouse to afford. Every architectural choice is cost-conscious.

Lever	Choice
Compute	Cloud Run with scale-to-zero on low-traffic services; min-instances only on hot-path services (`reservation-service`, `bff-tenant-booking-service`, `iam-service`)
Database	Cloud SQL right-sized; HA only on hot services; per-service schema avoids monolith bloat
Cache	Memorystore Standard tier (no HA premium) on most services; HA only where staleness is unacceptable
Messaging	Pub/Sub with batch publish; consumer ack deadline tuned per service; DLQ retention 7 days default
Storage	Cloud Storage Standard for hot media; Nearline for invoices > 90 days; Coldline for compliance archives
Vector	`pgvector` inside Cloud SQL (no separate vector DB billing)
AI	Tiered routing in `ai-orchestrator-service`: edge first when feasible; cheaper Vertex AI models first; per-tenant budget caps; per-feature quotas; soft-degrade before hard-stop
Image	Image optimization on upload (`file-storage-service`); WebP / AVIF; multi-resolution variants generated once
Network	Low-bandwidth payload contracts: gzip + brotli; field-level projection on hot endpoints; sync deltas, not full snapshots

14. Compliance & Data Residency

Area	Posture
GDPR	Lawful basis recorded per processing activity; DSAR (export, erasure, portability) implemented as a saga via `audit-service` `gdpr.subject_request.received.v1`
Data residency	Per-tenant residency pin in `tenant-service`; default region preference: `me-central1` / closest GCP region serving Afghanistan; cross-region replication only with explicit opt-in
Audit immutability	`audit-service` is append-only; daily Merkle root anchored to a public timestamp authority
Lock credentials	Isolated KMS key; isolated DB namespace; isolated logs (none); isolated incident-response procedure
Payment data	PCI scope limited to `payment-gateway-service`; schema-per-tenant; PAN never persisted (tokens only); annual scope review
AI	Per-feature risk classification; HITL where required; provenance retained 7 years
Accessibility	WCAG 2.2 AA on all guest + tenant surfaces; backoffice meets AA on critical operational paths
Local regulation	Tax engine pluggable per jurisdiction; invoice numbering compliant per market (e.g., sequential per Iranian or Afghan rules where applicable)

15. Anti-patterns We Explicitly Avoid

Anti-pattern	Why it's banned	What we do instead
Synchronous cross-service chains > 2 hops	Couples availability; hides cascading failure	Async via Pub/Sub + saga; orchestrator in the owning context
Shared database across services	Couples deploys; blurs ownership; defeats RLS	Per-service schema; events project read models
Last-write-wins for money or inventory	Silent data loss; impossible to audit	`append_only` for money; `server_authoritative` for inventory; `max-of` for status
Vendor-locked lock APIs	Strands tenants on one hardware vendor	Single `LockPort`; vendor adapters live in infrastructure (see ADR-0004)
Vendor-locked AI APIs	Same trap, plus model risk	All AI through `ai-orchestrator-service`; provider rotation behind the gateway
Electron with `nodeIntegration: true`	Renderer can `require('child_process')`; XSS becomes RCE	`nodeIntegration: false`, `contextIsolation: true`, narrow `contextBridge` only (see ADR-0003)
Secrets in client bundles	Public by definition	Secret Manager only; clients receive short-lived tokens, never raw credentials
Cross-tenant joins anywhere except `search-aggregation-service`	One bug = one breach	RLS at DB; cross-tenant reads only via projected read models
AI calls outside `ai-orchestrator-service`	Bypasses moderation, provenance, budget	All AI via `ports/AIClient`; CI dependency check forbids vendor SDK imports outside `ai-orchestrator-service`
DB-per-tenant for the entire estate	1000+ databases is operationally untenable	Hybrid: shared schema + RLS for most; schema-per-tenant only for `billing-service` and `payment-gateway-service`
Frontend that talks directly to microservices	Couples client to internal topology; defeats BFF	Three BFFs; clients only call BFFs and the sync surface
Free-text RTL/LTR detection at runtime per-component	Inconsistent direction; layout bugs	Locale → direction at app shell; logical CSS properties only

Cross-references: per-service deep docs live in services/<service-name>/. ADRs live in docs/architecture/. The next document in the strategic set is 04 Event-Driven Architecture.

1. Business Architecture​

1.1 Stakeholders & Personas​

1.2 Value Streams​

1.3 Capability Map (top-level)​

2. Application Architecture (Clean / Hexagonal)​

3. Bounded Contexts​

3.1 Context List​

3.2 Context Map (relationships)​

4. Microservices Topology​

4.1 Identity & Tenancy​

4.2 Property​

4.3 Reservations & Inventory​

4.4 Pricing​

4.5 Operations​

4.6 Finance​

4.7 Communication​

4.8 AI​

4.9 Theming​

4.10 Lock​

4.11 Search​

4.12 Cross-Cutting​

4.13 BFFs (Backends-for-Frontend)​

5. Three BFFs​

6. Multi-Tenancy Architecture​

6.1 Hybrid Tenancy Model (canonical — see ADR-0002)​

6.2 Tenant Context Propagation​

6.3 Cross-Tenant Safe Paths​

7. Event-Driven Backbone​

7.1 Backbone​

7.2 Transactional Outbox​

7.3 Saga: Booking → Inventory → Payment → Key Issuance​

7.4 Dead-Letter & Replay​

8. Sync & Offline Architecture​

8.1 Protocol Surface​

8.2 Per-Aggregate Conflict Policy​

8.3 Device Binding & Cursors​

8.4 Failure Modes​

9. AI Architecture​

9.1 Routing​

9.2 Edge Inference on Electron​

9.3 Provenance & HITL​

10. GCP Reference Topology​

11. Security Posture​

12. Resilience & Performance​

13. Cost Posture​

14. Compliance & Data Residency​

15. Anti-patterns We Explicitly Avoid​