Release 1 — Foundations
Companion: Roadmap Index · Product Overview · Risks & Tradeoffs · ADR-0001 core stack · ADR-0003 Electron offline-first
R1 is the wave that proves the platform thesis with real tenants. Horizon: ~6 months. Geography: Afghanistan + Tajikistan (Iran deferred to R2 under sanctions-aware boundary). Scale target: 5 tenants live, 100 reservations/day across them. Operational target: 24-hour offline operation without operator workaround on the Electron desktop. Commercial target: first revenue and three reference customers for the R2 push.
R1 is deliberately narrow. We resist the gravitational pull of "while we're at it" features. The R2 and R3 wave files exist precisely so that R1 can stay scoped.
1. Vision & Outcomes
1.1 Vision
A small hotel in Kabul or Dushanbe runs its property end-to-end on Ghasi Melmastoon. The front desk uses the Electron desktop offline through the regular morning power outage and is reconciled by the time the first walk-in arrives. The GM sees yesterday's occupancy and revenue without opening Excel. A guest discovering the property on the consumer meta site books on the tenant's own themed site without leaving our platform, pays cash on arrival or by card if they prefer, and gets a key issued through TTLock or via the generic Wiegand encoder we shipped with the install kit.
1.2 Outcomes — measurable
| Outcome | Target | Measurement |
|---|---|---|
| Tenants live in production | 5 tenants (3 in Afghanistan, 2 in Tajikistan) | Tenant onboarding tracker |
| Daily reservations across cohort | 100 reservations/day, sustained 14-day rolling | reservation-service aggregations |
| Sync reliability | 99% of offline mutations sync on first reconnect attempt | Sync telemetry dashboard |
| Desktop cold-start | < 4 s on a baseline laptop (Intel i5 8th gen / 8 GB / SSD) | Per-launch RUM |
| Front-desk check-in time | < 90 s p75 (walk-in including key issuance) | Desktop event telemetry |
| Direct-booking share | > 50% of confirmed reservations from direct + meta channels | reservation-service channel attribution |
| NPS (post-stay, weighted) | > 30 | notification-service survey + analytics-service rollup |
| Tenant onboarding time | < 30 days kickoff to first live booking | Tenant onboarding tracker |
| Pilot abandonment | 0 of 5 (1 acceptable but not desired) | Tenant lifecycle status |
| Per-property monthly GCP cost | < $80 USD per tenant during pilot | FinOps dashboard |
1.3 Vision boundary
We are not trying to ship every capability in the strategic spec in R1. The wave is "foundation" — the scaffold on which R2 builds. If a capability is not on the IN list in §2, it is not in R1 even if it is in the spec.
2. Scope (in / out)
2.1 IN
2.1.1 Backend services (15 of 22)
| Service | R1 capability surface |
|---|---|
iam-service | Email + password + TOTP; passkey foundation (UI in R2); device binding for Electron; per-tenant role catalog (Owner, GM, FrontDesk, Housekeeping, Maintenance, Finance) |
tenant-service | Tenant create/update/suspend; per-tenant config snapshot for downstream services; assisted onboarding wizard (control plane) |
property-service | Single property per tenant (chain support deferred to R2); rooms + room types + amenities + geo |
theme-config-service | 3 layout presets (Hero+Rooms, Hero+Promo+Rooms, Hero+Story+Rooms); ~10 content blocks (about, policies, FAQ, gallery, location, contact, amenities, restaurant placeholder, transport, COVID-style notice); brand tokens (logo, color, typography); RTL/LTR toggle |
bff-tenant-booking-service | Tenant booking flow; room+rate selection; date+guest adjustments; special requests; payment selection; confirm |
bff-consumer-service | Meta search list + map; provider transition into tenant booking |
bff-backoffice-service | Desktop-facing surface; auth; sync endpoint; operator workflows |
reservation-service | Booking lifecycle (book → confirm → check-in → check-out → cancel/no-show); walk-ins; modifications |
pricing-service | Manual rate plans (BAR + government + corporate + non-refundable); seasonal calendars; AI suggestions deferred to R2 |
inventory-service | Availability + allocation + overbooking guard; room state lifecycle |
billing-service | Folio + charges + taxes + refunds; FX snapshot at confirm; cash-drawer accounting; EOD reconciliation |
payment-gateway-service | Adapters: Stripe, cash-on-arrival, AfghanPaisa MFS pilot; bank-transfer capture; reconciliation tooling |
housekeeping-service | Basic board (room turnover queue, status transitions, assignment); manual prioritization (AI optimization in R2) |
maintenance-service | Basic work-order queue; asset registry minimal; preventive scheduler deferred to R2 |
notification-service | Email + SMS via 2 providers (Resend + Twilio fallback); WhatsApp + push deferred to R2; outbox + retry |
file-storage-service | Property + room photos; invoices PDF; ID documents (KYC); signed URLs; per-tenant lifecycle policies |
lock-integration-service | TTLock vendor adapter + Generic Wiegand adapter; key lifecycle (issue → update → revoke); offline issuance window where vendor supports |
reporting-service | 5 standard templates: Occupancy, ADR/RevPAR, Channel Mix, Payment Mix, EOD reconciliation |
Excluded R1 services (deferred to R2 or later):
staff-service— minimal HR; staff records viaiam-serviceonly in R1; full surface in R2.analytics-service— basic stats only; full BigQuery sink + dashboards in R2.ai-orchestrator-service— wired only for desktop edge ONNX (anomaly detection); cloud AI deferred to R2.ai-gateway(any cloud LLM surface) — out.search-aggregation-service— basic implementation for meta in R1; full aggregation surface in R2.
2.1.2 Surfaces
- Consumer Meta Web — list view + map view (Leaflet); search-by-location, dates, guests; basic filters (price band, amenities, rating); transition into tenant booking. In.
- Consumer Mobile (React Native) — browse + book only; multi-tenant aware; offline cache for last results; payment flows online-only. In.
- Tenant Booking Web — Next.js shared codebase; runtime theming; full booking flow including Stripe + cash + MFS; receipts via email + SMS. In.
- Backoffice Desktop (Electron) — alpha at M5; beta at M6; offline-first with full operational surface for the IN services. In.
- Tenant Booking Mobile — same React Native binary, tenant context. In.
- Control plane — minimal admin for platform staff to onboard tenants, review themes, manage flags. In.
2.1.3 Lock vendors
- TTLock (cloud + Bluetooth offline-issuance via vendor SDK).
- Generic Wiegand encoder (USB or RS-232 attached to the desktop machine; supports the long tail of cheap regional encoders that present a Wiegand interface).
Excluded: Salto, Assa Abloy, mobile-key full integration — all R2.
2.1.4 Payments
- Stripe (cards, where the tenant has a working merchant account).
- Cash-on-arrival (first-class, with drawer + EOD).
- AfghanPaisa MFS pilot (one tenant initially, expand if successful).
- Bank-transfer capture (manual reconciliation surface).
Excluded: PayPal, EasyPaisa, M-PESA, Pamir-Pay — all R2.
2.1.5 AI
- Edge ONNX on desktop, anomaly detection only. Specifically: payment-anomaly heuristic, key-event anomaly heuristic, late-checkout pattern heuristic.
- No cloud AI in R1. Pricing AI, message-drafting AI, demand forecasting AI, image moderation, voice transcription, embeddings/RAG — all R2.
2.1.6 Infrastructure
- Single GCP region: asia-south1 (Mumbai). Multi-region in R2.
- Cloud Run for compute; Cloud SQL HA; Pub/Sub; Memorystore (Redis); Cloud Storage; Secret Manager; KMS; Cloud Logging/Monitoring/Trace.
- IaC scaffolding (Terraform); CI/CD (GitHub Actions); per-service deploy.
- Observability stack: OTel traces, dashboards per service, runbooks per service.
- BigQuery sink: scaffolded but minimal in R1 (full in R2).
2.2 OUT (deferred to R2 or later)
- Chain multi-tenant switcher (R2).
- PayPal (R2).
- Full vendor matrix for locks beyond TTLock + Generic Wiegand (R2).
- Full dynamic pricing AI; pricing in R1 is manual rate plans plus per-tenant seasonal calendars; AI suggestions on rate plans deferred to R2.
- Maintenance preventive scheduler (R2).
- Marketing campaigns module via notification-service (R2).
- Advanced analytics dashboards via Looker (R2 reporting templates only in R1).
- Voice transcription, AI image, AI content generation (R3).
- White-label reseller program (R3).
- Native staff sub-app on mobile (R3).
- Iran tenant onboarding (R2 exploratory; R3 production).
- GCC, Europe expansion (R3).
3. Epics included
The full epic catalog lives in docs/07-epics-and-user-stories.md (alongside the strategic spec). R1 includes the foundation epics; the table below maps R1 epics to their owning surfaces.
| Epic ID | Epic name | Owning service(s) | Surface(s) |
|---|---|---|---|
| EP-MEL-01 | Tenant onboarding & configuration | tenant-service, theme-config-service, control plane | Control plane |
| EP-MEL-02 | Identity, roles, device binding | iam-service | Desktop, all BFFs |
| EP-MEL-03 | Property, room, room-type catalog | property-service | Desktop |
| EP-MEL-04 | Tenant booking site (theming + flow) | theme-config-service, bff-tenant-booking-service | Web + Mobile |
| EP-MEL-05 | Consumer meta search (list + map) | search-aggregation-service, bff-consumer-service | Web + Mobile |
| EP-MEL-06 | Reservation lifecycle (book → check-out) | reservation-service, inventory-service | Desktop, Tenant Booking, Mobile |
| EP-MEL-07 | Manual rate plans + seasonal calendars | pricing-service | Desktop |
| EP-MEL-08 | Folio, taxes, refunds, EOD | billing-service | Desktop |
| EP-MEL-09 | Payments — Stripe + cash + MFS pilot | payment-gateway-service, billing-service | Tenant Booking, Desktop |
| EP-MEL-10 | Housekeeping board (manual) | housekeeping-service | Desktop |
| EP-MEL-11 | Maintenance basic work orders | maintenance-service | Desktop |
| EP-MEL-12 | Notifications (email + SMS) | notification-service | All surfaces |
| EP-MEL-13 | File storage (photos, invoices, IDs) | file-storage-service | All surfaces |
| EP-MEL-14 | Lock integration — TTLock + Wiegand | lock-integration-service | Desktop |
| EP-MEL-15 | Reporting — 5 standard templates | reporting-service | Desktop, control plane |
| EP-MEL-16 | Electron desktop shell + sync engine | bff-backoffice-service, desktop | Desktop |
| EP-MEL-17 | Edge ONNX anomaly detection | desktop only | Desktop |
| EP-MEL-18 | Pilot launch readiness + ops runbooks | All services | All surfaces |
R2 epics begin at EP-MEL-19. R3 epics begin at EP-MEL-21 (see 03-release-3-and-beyond.md).
4. Service rollout order
R1 is six months. We rollout in monthly tracks; each month has a primary set of services to bring to first-pass readiness and a secondary set of services to keep moving in the background. The order below is the ground-truth order; deviations require explicit Release Captain sign-off.
4.1 Month 1 — Platform foundations
Primary: iam-service, tenant-service, file-storage-service. Control-plane skeleton.
- GCP project setup; IAM hierarchy; KMS hierarchy; Secret Manager scaffold; Artifact Registry.
- IaC (Terraform) scaffolding.
- CI/CD (GitHub Actions) per-service template.
- Postgres schemas with RLS for the 3 services.
iam-serviceissues JWTs withtidclaim; refresh tokens; device-binding token issuance.tenant-servicecreate + suspend; per-tenant config snapshot publish.file-storage-servicesigned URL upload + read; per-tenant lifecycle policies.
Secondary background work: Service template scaffolding for the other 12 services; runbook templates; SLO templates.
Exit criteria for M1: Two-tenant CI fixture loadable; tenant create end-to-end via control plane; one engineer can sign in to a stub backoffice and exchange JWT.
4.2 Month 2 — Property + theme + tenant booking shell
Primary: property-service, theme-config-service, bff-tenant-booking-service, web booking shell.
property-servicerooms + room types + amenities + geo.theme-config-servicetoken model + 3 layout presets + ~10 content blocks; per-tenant theme draft → review → publish flow.- Tenant booking site shell (Next.js App Router) with runtime theming via
theme-config-service. - Observability stack: OTel traces correlate across the M1 + M2 services; dashboards per service; runbooks per service.
- KMS + Secret Manager wired into all services.
Secondary: reservation-service and inventory-service domain modeling.
Exit criteria for M2: A tenant created in M1 can be themed and a hello-world booking site renders under the tenant subdomain in 3 locales (EN + Pashto + Dari); RTL toggling works.
4.3 Month 3 — Reservation, pricing, inventory, billing happy path
Primary: reservation-service, pricing-service, inventory-service, billing-service — happy-path booking → confirm → check-in → check-out → folio close.
reservation-serviceaggregates + state machine; saga orchestration scaffold.pricing-servicerate plans; seasonal calendars; per-jurisdiction tax model.inventory-serviceavailability + overbooking guard.billing-servicefolio with charges, taxes, refunds (manual); EOD scaffold.- Pub/Sub topology stood up; per-service outbox; per-service consumers.
- Cloud SQL HA validated; PITR drill executed.
Secondary: notification-service skeleton; receipt email flow.
Exit criteria for M3: A reservation booked on the tenant booking site flows through inventory + pricing + billing to a confirmed state and an emailed receipt; refund manual; EOD report renders.
4.4 Month 4 — Payments + notifications
Primary: payment-gateway-service (Stripe + cash + AfghanPaisa MFS pilot), notification-service (email + SMS via Resend + Twilio).
- Stripe adapter with sandbox + production credentials; webhook handling.
- Cash-on-arrival flow including drawer + EOD reconciliation.
- AfghanPaisa MFS adapter — pilot integration with one tenant initially.
- Bank-transfer capture path (manual reconciliation surface).
- Notification outbox + retry; per-tenant template authoring; receipt + confirmation + cancellation flows.
- Per-tenant payment-method enable/disable.
Secondary: housekeeping-service board scaffold; maintenance-service work-order scaffold.
Exit criteria for M4: A tenant can take a Stripe payment online, a cash payment at front desk, and a MFS payment via AfghanPaisa; receipts ship in 3 channels (email, SMS, in-app); EOD reconciles; refunds processed end-to-end.
4.5 Month 5 — Housekeeping + maintenance + lock integration + Electron alpha
Primary: housekeeping-service, maintenance-service, lock-integration-service (TTLock + Generic Wiegand), Electron desktop alpha.
- Housekeeping board: room turnover queue, manual assignment, status transitions.
- Maintenance: basic work-order queue, asset registry minimal.
lock-integration-servicewith TTLock adapter (cloud + Bluetooth offline-issuance via vendor SDK).- Generic Wiegand adapter wrapped in a Node native module deployable on Windows.
- Electron desktop alpha: shell + sign-in + device binding + sync engine first-pass + reservation + check-in/out + folio + housekeeping board + lock integration.
- Edge ONNX runtime in main process; first three anomaly heuristics shipped.
- BigQuery sink scaffolded (analytics surface in R2).
- Security audit #1 (security-reviewer subagent + external pen-test pass on alpha scope).
Secondary: Consumer mobile (React Native) build; reporting-service 3 of 5 templates.
Exit criteria for M5: Internal team can take a reservation, check in a guest, issue a TTLock or Wiegand key, run the property's day, close the drawer, and reconcile EOD on the Electron desktop with the laptop in airplane mode for at least 4 hours of the day, then sync.
4.6 Month 6 — Mobile, meta search, hardening, pilot launch
Primary: Consumer mobile (React Native) browse + book; search-aggregation-service basic; Electron desktop beta; pilot launch.
- Consumer mobile: browse list + map; transition to tenant booking; payment flows online-only; offline cache for last results.
search-aggregation-servicebasic: cross-tenant denormalized read model; query by location + dates + guests + price band.- Electron desktop beta: address bugs from internal alpha; full RTL/LTR pass; performance pass; auto-update channel set up.
reporting-servicefinal 2 of 5 templates.- Pilot tenant onboarding: 5 tenants live (3 AF, 2 TJ).
- Final security audit before pilot launch (security-reviewer subagent + external pen-test).
- Operator quick-cards printed in 3 locales.
Exit criteria for M6: All 5 pilot tenants onboarded, taking real bookings, with the Electron desktop installed and used daily; first revenue collected; first reference customer agreed.
4.7 R1 ASCII timeline
M1 M2 M3 M4 M5 M6
┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐ ┌────┐
Platform │████│ │░░░░│ │░░░░│ │░░░░│ │░░░░│ │░░░░│
iam/tenant/file │████│ │░░░░│ │ │ │ │ │ │ │ │
Property + theme │ │ │████│ │░░░░│ │░░░░│ │░░░░│ │░░░░│
bff-tenant-bk │ │ │████│ │░░░░│ │░░░░│ │░░░░│ │░░░░│
Reservation core │ │ │░░░░│ │████│ │░░░░│ │░░░░│ │░░░░│
pricing/inv/bill │ │ │░░░░│ │████│ │░░░░│ │░░░░│ │░░░░│
Payments + notif │ │ │ │ │░░░░│ │████│ │░░░░│ │░░░░│
Housekeeping/maint │ │ │ │ │ │ │░░░░│ │████│ │░░░░│
Lock-integration │ │ │ │ │ │ │░░░░│ │████│ │░░░░│
Electron desktop │ │ │ │ │░░░░│ │░░░░│ │█a██│ │█b██│
Consumer mobile RN │ │ │ │ │ │ │ │ │░░░░│ │████│
Search-aggregation │ │ │ │ │ │ │ │ │░░░░│ │████│
Reporting (5 tmpl) │ │ │ │ │ │ │ │ │░██░│ │████│
Pilot onboarding │ │ │ │ │ │ │ │ │░░░░│ │████│
└────┘ └────┘ └────┘ └────┘ └────┘ └────┘
GCP set Theme + Resv.+ Pay+ H/M+ Mobile+
KMS+CI web shell bill+pay notif locks+ pilot
Electron launch
alpha beta
█ = primary build ░ = secondary / hardening
a = alpha b = beta + pilot
The timeline is the contract; deviations are change-orders that cost downstream months.
4.8 Cross-functional swim-lane (M1 → M6)
┌──────────────┬──────┬──────┬──────┬──────┬──────┬──────┐
│ Lane │ M1 │ M2 │ M3 │ M4 │ M5 │ M6 │
├──────────────┼──────┼──────┼──────┼──────┼──────┼──────┤
│ Backend │ FND │ THM │ RES │ PAY │ LCK │ HRD │
│ Web │ - │ SHL │ BKG │ PAY │ HRD │ PLT │
│ Mobile (RN) │ - │ - │ SHL │ BKG │ HRD │ PLT │
│ Desktop │ - │ - │ SCF │ SYNC │ ALPH │ BETA │
│ Infra/SRE │ GCP │ OBS │ HA │ FLW │ DR │ AUD │
│ AI │ - │ - │ - │ - │ ANOM │ EVAL │
│ Security │ KMS │ SEC │ RLS │ AUDP │ PEN1 │ PEN2 │
│ Data/BI │ - │ - │ - │ SINK │ BQ │ DASH │
│ Compliance │ JUR1 │ JUR2 │ KYC │ TAX │ DPA │ READ │
│ Field ops │ HIRE │ HIRE │ TRAIN│ TRAIN│ ONBD │ LIVE │
└──────────────┴──────┴──────┴──────┴──────┴──────┴──────┘
FND=foundations THM=theme RES=reservation PAY=payments
LCK=lock-integration HRD=hardening SHL=shell BKG=booking
SCF=scaffold SYNC=sync engine ALPH=alpha BETA=beta
GCP=project setup OBS=observability HA=Cloud SQL HA FLW=Pub/Sub flow
DR=disaster-recovery drill AUD=security audit EVAL=eval harness
KMS=KMS+SecretMgr SEC=secret rotation RLS=RLS test pattern AUDP=audit pipeline
PEN1/PEN2=external pen-tests SINK=BigQuery sink BQ=BigQuery datasets DASH=dashboards
JUR1/JUR2=jurisdictional adapters TAX=tax model DPA=data-processing agreements
READ=readiness sign-off HIRE=field rep hires TRAIN=operator training ONBD=onboarding LIVE=pilot live
The lanes run in parallel; each lane has an owner; the Release Captain owns the cross-lane critical path.
5. Frontend rollout
| Surface | M1 | M2 | M3 | M4 | M5 | M6 |
|---|---|---|---|---|---|---|
| Tenant booking web | — | Shell + theming | Booking flow alpha | Booking flow + payments | Hardening | Pilot |
| Tenant booking mobile (RN) | — | — | Shell | Booking flow | Hardening | Pilot |
| Consumer meta web | — | — | — | List view alpha | List + map | Pilot |
| Consumer mobile (RN) | — | — | — | — | Browse + book alpha | Pilot |
| Electron desktop | — | — | Renderer scaffold | Sync engine + auth | Alpha | Beta + pilot |
| Control plane | Skeleton | Tenant CRUD + theme review | + Reservation peek | + Payment ops | + Lock ops | + Tenant playbook |
5.1 Design-system and i18n cadence
@ghasi/ui-melmastoondesign tokens established M1; first-class RTL/LTR.- i18n bundles for EN, Pashto, Dari finalized M2; Tajik (Persian script variant) added M5.
- All screens reviewed in RTL by a locale champion before M6 pilot launch.
5.2 Performance budgets
| Surface | Metric | R1 budget |
|---|---|---|
| Tenant booking web | LCP p75 (3G fast) | < 2.5 s |
| Tenant booking web | TTI p75 | < 4 s |
| Consumer mobile | Cold start (mid-tier Android) | < 3 s |
| Electron desktop | Cold start | < 4 s |
| Electron desktop | Reservation list render (200 rows) | < 200 ms |
| Tenant booking mobile | Booking flow step transition | < 300 ms |
6. Infrastructure milestones
| Milestone | Target month | Owner | Acceptance criteria |
|---|---|---|---|
| GCP project setup (asia-south1) | M1 | SRE | Terraform applied; IAM hierarchy; org policies enforced |
| IaC scaffolding (Terraform) | M1 | SRE | All shared infra modules versioned; per-service module template |
| CI/CD per-service (GitHub Actions) | M1 | Platform | Service template ships with build + test + deploy + observability lint |
| KMS + Secret Manager hierarchy | M2 | Security | Per-tenant DEKs wrapped by KEK; secrets retrieved via service-account-bound IAM |
| Observability stack | M2 | SRE | OTel collector live; per-service dashboards; runbooks committed |
| Pub/Sub topology + outbox pattern | M3 | Platform | Topics + subscriptions per service; outbox in each service; replay tooling |
| Cloud SQL HA + PITR drill | M3 | SRE | HA primary + standby; PITR restore drill executed |
| BigQuery sink (scaffold) | M5 | Platform | Per-service event sink to BigQuery via Pub/Sub subscription |
| Security audit #1 | M5 | Security | External pen-test on alpha scope; findings closed before M6 |
| Security audit #2 (pre-launch) | M6 | Security | External pen-test on full R1 scope; findings closed |
| FinOps dashboard | M6 | Finance + SRE | Per-service, per-tenant cost; budget alerts |
6.1 Region strategy
R1 ships in asia-south1 (Mumbai) only. Latency from Kabul, Dushanbe, and Mashhad to asia-south1 is acceptable for staff and consumer flows (< 200 ms RTT in measured samples). Multi-region (asia-south1 + asia-southeast1) lands in R2.
6.2 Backup and DR
- Cloud SQL HA primary + standby in asia-south1, separate zones.
- Daily backups + PITR enabled; PITR restore drill executed in M3 and M6.
- Cloud Storage with multi-region bucket for media in R1; per-region in R2.
- Pub/Sub message retention 7 days; replay scripts per consumer.
- Outbox tables in every service; nightly archival job from M3.
7. Pilot tenant program
The R1 pilot is the most important commercial event of the year. It is run as a formal program, not as ad-hoc onboarding.
7.1 Tenant selection
Five pilot tenants. Mix designed to stress different surfaces:
| # | City | Country | Rooms | Reason for selection |
|---|---|---|---|---|
| 1 | Kabul | AF | 28 | Urban; mixed language Pashto/Dari; cash-heavy; established operator open to change |
| 2 | Mazar-i-Sharif | AF | 15 | Provincial; intermittent power; conservative operator; tests offline rigor |
| 3 | Herat | AF | 22 | Cross-border guest mix (Iranian visitors); tests multi-currency + KYC |
| 4 | Dushanbe | TJ | 35 | Urban; mixed Tajik + Russian + English; tests Salto-adjacent encoder ecosystem |
| 5 | Khujand | TJ | 18 | Provincial; tests Generic Wiegand on long-tail encoder |
All five tenants are paid feedback partners under a 12-month outcomes-aligned contract.
7.2 Onboarding playbook
Per tenant, ~30 days from kickoff to first live booking:
| Day | Activity | Owner |
|---|---|---|
| D-30 | Discovery call + property data collection (CSV templates) | Field rep + Tenant |
| D-25 | Tenant created in control plane; theme draft initiated | Field rep + Theme reviewer |
| D-20 | Property + rooms + room types + amenities loaded; rate plans configured | Field rep + Tenant |
| D-15 | Theme review + publish; tenant booking site goes live in staging | Theme reviewer + Tenant |
| D-10 | Lock vendor procurement complete; Electron desktop installed; staff trained on day-1 workflows | Field rep + Tenant + Vendor |
| D-5 | Tenant booking site goes live in production with payment provider tested end-to-end | Field rep + Platform |
| D-0 | Go-live; first reservations taken | Tenant + Field rep on-site |
| D+7 | First weekly check-in: usage, feedback, blockers | Field rep + PM |
| D+30 | Pilot review: NPS, KPIs, retention decision | Founder + PM + Tenant |
7.3 Weekly check-in
For the duration of R1, every pilot tenant has a 30-minute weekly check-in with the field rep and a PM. Standing agenda: usage stats from the previous week, blockers, feature requests, sync incidents, lock incidents, payment incidents, training gaps. Every check-in produces a written summary in the tenant's case folder.
7.4 Success criteria for pilot
A pilot is successful and the tenant transitions to GA terms when:
- ≥ 30 days continuous use with no abandonment incident.
- ≥ 80% of bookings handled end-to-end on the platform (not paper).
- Sync conflict rate ≤ 5/1k mutations/week.
- EOD variance ≤ 2× pre-Ghasi baseline.
- Operator NPS ≥ 30.
- Owner agrees to public reference.
If a pilot does not meet criteria within 60 days of go-live, we run a recovery cycle (joint review, intervention plan, 30-day retry) before deciding whether to exit the tenant.
7.5 Exit-into-GA
Once a pilot meets success criteria, the tenant moves from pilot pricing (concessionary) to GA pricing (tiered SaaS) and signs a standard MSA. Five referenceable case studies become the R2 marketing surface.
7.6 R1 staffing plan
R1 is delivered by a small, owner-operator-style team. Roles below are full-time-equivalent commitments unless marked fractional.
| Role | FTE | Lane | Hire by |
|---|---|---|---|
| Founder / CTO | 1 | All; final architectural sign-off | Day 0 |
| Platform engineer (lead) | 1 | iam, tenant, file, RLS, Pub/Sub, Cloud SQL | Day 0 |
| Backend engineer #1 | 1 | reservation, pricing, inventory, billing | M1 |
| Backend engineer #2 | 1 | payment-gateway, notification, lock-integration | M2 |
| Backend engineer #3 | 1 | housekeeping, maintenance, reporting, search-aggregation | M3 |
| Web engineer (lead) | 1 | Next.js tenant booking, theming, control plane | M1 |
| RN engineer | 1 | Consumer mobile | M3 |
| Desktop engineer (lead) | 1 | Electron renderer + main; sync engine | M2 |
| Desktop engineer #2 | 1 | Electron native modules; lock SDKs; ONNX worker | M3 |
| SRE | 1 | GCP, IaC, observability, on-call rota | Day 0 |
| AI engineer | 0.5 | Anomaly heuristics + ONNX worker; eval harness | M4 |
| QA engineer | 1 | Test harness, two-tenant fixture, contract tests, manual ad-hoc | M2 |
| Local QA contractors | 2 (fractional) | Per-locale UAT (Pashto/Dari, Tajik) | M3 |
| Designer | 0.5 | Token model, component library, RTL/LTR, theme presets | M1 |
| PM | 1 | Roadmap, pilot ops, decision log | Day 0 |
| Field rep — Kabul | 1 | Pilot tenants 1, 2, 3 onboarding + weekly check-ins | M2 |
| Field rep — Dushanbe | 1 | Pilot tenants 4, 5 onboarding + weekly check-ins | M2 |
| Compliance / counsel | 0.25 | Per-jurisdiction adapters; KYC; sanctions | M1 |
| Finance / FinOps | 0.25 | Cost attribution, invoicing, pricing | M3 |
R1 total: ≈ 13.25 FTE plus fractional roles. The on-call rota is shared across SRE + Platform + Backend + Desktop with two timezones covered (CET-adjacent + IST-adjacent).
7.7 Operator training curriculum
Every pilot tenant's staff completes the curriculum below before go-live (D-5). Materials in EN + Pashto + Dari (Tajik on best-effort).
| Module | Duration | Audience | Format |
|---|---|---|---|
| Day-1 desktop tour: sign-in, device binding, navigation | 30 min | All staff | Live + recording |
| Take a reservation (online + walk-in) | 45 min | Front-desk | Live + workbook |
| Check-in flow: ID capture, key issuance (TTLock + Wiegand), folio open | 60 min | Front-desk | Live + workbook |
| Check-out flow: folio close, payment, receipt, key revocation | 45 min | Front-desk | Live + workbook |
| Cash-drawer open + close + EOD reconciliation | 45 min | Front-desk + GM | Live + workbook |
| Stripe payment + reversal | 20 min | Front-desk | Recorded |
| MFS payment (AfghanPaisa) capture + reconciliation | 30 min | Front-desk + accountant | Recorded |
| Housekeeping board: status transitions, assignments | 30 min | Housekeeper + GM | Live |
| Maintenance work-order: open, assign, close | 20 min | Maintenance + GM | Live |
| Operating offline: what works, what queues, what to do at sync time | 45 min | All staff | Live (rehearsal) |
| Lock issuance fallback: when TTLock or Wiegand fails | 30 min | Front-desk | Live (rehearsal) |
| Reading the GM dashboard | 30 min | GM | Live |
| Multi-tenant safety: never share credentials; device binding; lost-device protocol | 20 min | All staff | Live |
Total: ≈ 7 hours per staff member spread across 3 days. Refresher every 90 days. Operator quick-cards (laminated, 3 locales) live next to the desktop.
7.8 Pilot escalation matrix
Tier the support response so a non-trivial incident does not languish.
| Tier | Trigger | Response time | Path |
|---|---|---|---|
| T1 | Booking flow broken; payments down; lock issuance broken; sync stalled > 30 min | < 15 min ack; < 1 h mitigation | Field rep → on-call → Founder |
| T2 | Recurring sync conflicts; payment-method-specific failure; reporting wrong | < 1 h ack; < 4 h mitigation | Field rep → service owner |
| T3 | UX complaints; minor data corrections; training requests | Same business day | Field rep → PM |
| T4 | Feature requests; non-blocking suggestions | Weekly check-in | PM → roadmap |
Every T1 in R1 produces a written postmortem within 5 business days.
8. Quality gates
R1 inherits the platform quality bars from docs/testing/01-testing-strategy-qa.md. The release-specific gates below must all be green before pilot launch in M6.
8.1 Functional
- All R1 epics' acceptance criteria met.
- End-to-end booking, check-in, check-out, EOD on staging passes for all 3 R1 currencies (AFN, TJS, USD).
- Five pilot tenants' staging environments configured and exercised by the field rep.
8.2 Non-functional
- Tenant booking web LCP p75 < 2.5 s on the simulated 3G profile.
- Electron desktop cold start < 4 s on baseline laptop.
- API p95 < 250 ms on core BFF routes.
- Sync push p95 < 5 s under simulated 3G + 5% packet loss.
- Cloud SQL HA failover < 60 s; PITR drill restored a sample tenant within 30 min RTO.
8.3 Security
- Two-tenant isolation suite green on every endpoint.
- External pen-test #1 (M5) and #2 (M6) findings closed.
- KMS hierarchy live; per-tenant DEK live.
- SQLCipher on the desktop store verified by red-team (file copied off disk is unreadable).
- WebAuthn / passkey foundation in place even if TOTP is the default for R1.
8.4 Multi-tenant
tenant_idmandatory on every row in every R1 service.- RLS policies on every table;
FORCE ROW LEVEL SECURITYon the table owner role. - JWT
tidclaim required on every tenant-scoped endpoint. - Cross-tenant CI test coverage 100% of R1 endpoints.
8.5 Observability
- SLOs per R1 service (availability, latency, error).
- OTel traces correlate across services via
traceparent. - Dashboards for every R1 service.
- Runbooks for every R1 service.
- On-call rota and PagerDuty escalation set up for two timezones.
8.6 Documentation
SERVICE_OVERVIEW.md,API_CONTRACTS.md,EVENT_SCHEMAS.md,DATA_MODEL.md,SECURITY_MODEL.md,OBSERVABILITY.md,FAILURE_MODES.md,LOCAL_DEV_SETUP.md,SERVICE_READINESS.md,SERVICE_RISK_REGISTER.mdfor every R1 service.- ADR-0001, ADR-0002, ADR-0003 published.
- Operator quick-cards printed in EN, Pashto, Dari.
- Runbooks for sync incidents, payment incidents, lock incidents, security incidents.
8.7 Offline
- Airplane-mode E2E green: a property runs for 4 simulated hours offline including check-in, check-out, folio adjustments, housekeeping updates, lock issuance via cached TTLock window; on reconnect, all mutations sync within target.
- Sync conflict UX exercised with intentional divergence; operator can resolve.
- Pre-merge backup recoverable for 7 days locally.
8.8 AI
- Edge ONNX runtime initializes on app start; signed model loads or app refuses to load.
- Three anomaly heuristics produce telemetry; HITL gate enforced (no auto-action).
- No cloud AI calls happen anywhere in R1 surfaces.
9. Risks specific to R1
These are the risks that materialize first in R1; the full register is in docs/12-risks-and-tradeoffs.md.
9.1 Pilot tenant churn
A pilot abandoning mid-cycle damages our R2 reference base. Mitigations: assisted onboarding, weekly check-ins, recovery cycle before exit, paid-partner contract.
Watchpoint: any pilot tenant flagged amber on the weekly KPI review for two consecutive weeks.
9.2 Lock vendor delivery delays
TTLock and Generic Wiegand encoder procurement in Afghanistan and Tajikistan can slip on customs and shipping. Mitigations: order encoders during M3 for M5 install; ship spare encoder per property; mechanical-key fallback documented.
Watchpoint: any property without encoder by D-15 of its onboarding plan.
9.3 GCP service availability in Iran
We do not onboard Iranian tenants in R1 specifically because GCP availability and sanctions posture are not yet validated. This avoids the risk in R1; R2 carries it.
9.4 Staff training time
The modal R1 operator is not a digital native. Training time can extend onboarding. Mitigations: in-language printed quick-cards, in-app tour, 1-day on-site training in the onboarding playbook.
Watchpoint: any tenant with onboarding > 45 days.
9.5 R1 risk-register slice
R1-specific subset of the platform register:
| ID | Description | R1 mitigation |
|---|---|---|
| R-MEL-001 | Multi-tenant data leakage | Two-tenant CI fixture loaded M1; runs on every PR |
| R-MEL-002 | Saga compensation gap | Booking saga state machine M3; chaos test M4 |
| R-MEL-003 | Sync conflict bugs | Per-aggregate policy M5; pre-merge backup; conflict UX |
| R-MEL-005 | Electron auto-update signature breach | electron-updater + code-signing cert from M5 |
| R-MEL-006 | SQLite key loss on device wipe | keytar + documented re-pair flow from M5 |
| R-MEL-101 | Cash-drawer close forgotten | Forced close on logout from M4 |
| R-MEL-103 | Offline window > grace | 75/90% warning bands from M5 |
| R-MEL-104 | Encoder hardware failure | Mechanical fallback from M5; spare encoder per property |
| R-MEL-201 | Credential phishing on staff | Passkey foundation M5; TOTP default; phishing drill before pilot |
| R-MEL-301 | Daily guest-registration mandate change | Per-jurisdiction adapter from M3 |
| R-MEL-401 | Pilot tenant financial fragility | Pilot pricing concession; pause-not-cancel clause |
| R-MEL-403 | Card unavailability under sanctions | Stripe + cash-on-arrival + AfghanPaisa MFS pilot |
| R-MEL-601 | TTLock API breaking change | Adapter pattern + nightly contract test from M5 |
| R-MEL-701 | Hiring locale-fluent QA | Local QA pool engaged M2; per-locale gate M6 |
10. Cost envelope
R1 is a cost-conscious release. The pilot must demonstrate that per-tenant unit cost is sustainable at SMB pricing.
10.1 Target monthly GCP cost (during pilot, 5 tenants)
| Component | Monthly USD (pilot) |
|---|---|
| Cloud Run (15 services, min-instance config) | ~$220 |
| Cloud SQL HA (asia-south1, db-custom-2-7680) | ~$280 |
| Memorystore (Redis, 1 GB) | ~$50 |
| Pub/Sub | ~$30 |
| Cloud Storage (media, invoices) | ~$15 |
| Cloud Logging/Monitoring/Trace | ~$40 |
| Networking (egress) | ~$30 |
| BigQuery (scaffold, low usage) | ~$10 |
| Other (KMS, Secret Manager, Artifact Registry) | ~$15 |
| Total | ~$690 |
| Per-tenant per-month | ~$138 |
R1 target is < $80 USD/tenant/month as the cohort grows beyond 5; the pilot starts at ~$138 and decreases as Cloud SQL HA, Cloud Run min instances, and shared infra amortize across more tenants.
10.2 Per-tenant unit cost target
The R1 contract terms must permit a positive unit margin even at the pilot cost level. Concessionary pricing is acceptable for the pilot; the GA pricing established for R2 must clear unit cost by ≥ 3×.
10.3 FinOps cadence
- Weekly cost review during R1 (Founder + SRE + Finance).
- Per-tenant cost attribution from M5.
- Budget alerts at 80% and 100% of monthly target.
11. Dependencies & decision points
11.1 External dependencies
| Dependency | Required by | Status / action |
|---|---|---|
| Stripe merchant account in Afghanistan / Tajikistan | M4 | Application initiated M2; legal counsel confirms eligibility |
| AfghanPaisa MFS sandbox + production access | M4 | Partnership conversation initiated M1; sandbox access target M3 |
| TTLock distributor agreement | M5 | Distributor identified M2; commercial terms finalized M4 |
| Generic Wiegand encoder shortlist (3 models tested) | M5 | Procurement test M3-M4; certified models published M5 |
| Twilio SMS in Afghanistan + Tajikistan | M4 | Twilio coverage validated M2; backup provider identified |
| Resend / SendGrid email | M4 | Resend account opened M1 |
| GCP partnership / startup credits | M1 | Application M1 |
| Local counsel partner per jurisdiction | M2 | Engagement letters signed M1-M2 |
| Field rep hires (Kabul + Dushanbe) | M3 | Recruitment open M1 |
| Local QA pool (Kabul + Dushanbe) | M5 | Pool engaged M2-M3 |
| Code-signing certificate (Windows + macOS) | M5 | Procurement M3 |
11.2 Decision points
| Decision | Latest decision date | Inputs needed |
|---|---|---|
| Tenant 4 + 5 selection (TJ) | End of M1 | Field rep input; commercial terms |
| Stripe vs. fallback card processor | End of M3 | Stripe account approval result |
| AfghanPaisa MFS go / no-go | End of M3 | Sandbox stability evaluation |
| Add a second MFS provider in R1 | End of M4 | AfghanPaisa stability + tenant demand |
| Add Salto adapter to R1 (vs. defer to R2) | End of M4 | Vendor SDK availability + tenant demand |
| Multi-region in R1 (vs. defer to R2) | End of M4 | Latency measurements; cost projection |
| Cloud AI in R1 (vs. defer to R2) | End of M4 | Vertex AI availability in asia-south1; cost projection; eval data readiness |
R1 default for each: defer the optional capability to R2 unless the inputs justify pulling it forward. R1 wins by being narrow.
12. Definition of R1 done
R1 is done when all of the following are true. Partial completion is not done.
- All 15 R1 services deployed to production in asia-south1.
- All 5 pilot tenants live with real reservations for ≥ 30 days continuous.
- North-star metric (gross booking volume retained in-platform) measured per tenant per month.
- All R1 outcomes (§1.2) measured against target; ≥ 4 of 5 pilots meet success criteria.
- Two-tenant CI fixture green; cross-tenant test 100% of endpoints; pen-test #2 findings closed.
- Sync reliability ≥ 99% on the cohort over 14-day rolling window.
- Desktop cold-start < 4 s on baseline laptop; sync push p95 < 5 s under 3G profile.
- Cash-drawer reconciliation flow proven daily by all 5 pilots.
- TTLock + Generic Wiegand key issuance success rate ≥ 99% per attempt across the cohort.
- All R1 services have all 17 doc files filled (or explicitly stubbed with rationale).
- All ADRs (0001, 0002, 0003) published and signed off.
- On-call rota in place across two timezones; runbooks for every R1 service.
- FinOps dashboard live; per-tenant cost attribution.
- Operator quick-cards printed in EN + Pashto + Dari (and Tajik if available).
- R2 plan reviewed against R1 learnings; epic catalog for R2 confirmed.
When all boxes are checked, R1 is closed; R2 begins. R1 retrospective produces written learnings folded into the risk register and the next wave's plan.