1. Backend Architecture Design

The OBS MVP backend is a monolithic Node.js/Express API deployed in Docker, backed by a single PostgreSQL database. This approach minimises operational complexity for an early-stage product while laying the groundwork for future service extraction.

1.1 Technology Choices

1.2 Database Schema (Core Tables)

All tables include created_at, updated_at timestamps and soft-delete via deleted_at where applicable.

Users & Auth

Treks & Inventory

Bookings & Payments

Documents & Pre-Trek

Loyalty & Referrals

Support

1.3 API Route Structure

RESTful API with /api/v1 prefix. JWT Bearer token required on all protected routes (marked *).

Auth Routes (/api/v1/auth)

Trek Routes (/api/v1/treks)

Booking Routes (/api/v1/bookings)

Payment Routes (/api/v1/payments)

User Routes (/api/v1/users)

Misc Routes

1.4 Admin Routes (/api/v1/admin)

All admin routes require admin JWT (separate role claim). Admin panel is a separate Next.js app consuming these.

1.5 Key Backend Flows

Booking Flow

Referral Flow

1.6 Security Considerations

• Rate limiting via Redis on all auth endpoints (5 OTP attempts per 10 minutes per phone)
• Razorpay webhook signature verification (HMAC-SHA256) before any payment state change
• S3 document uploads use presigned URLs — backend never streams files through the API server
• All user-uploaded content scanned for malware via ClamAV or AWS Macie before approval
• Row-level security on booking queries — users can only access their own bookings
• Admin routes protected by separate role claim in JWT; admin panel on separate subdomain
• HTTPS enforced everywhere; HSTS headers on website and API
• Database credentials, JWT secrets, Razorpay keys stored in environment variables; never in code

2. Website Sitemap (Next.js)

The website is the primary discovery and booking channel. Built with Next.js App Router using SSG for trek detail pages (fast load, SEO-optimised) and RSC+Client components for interactive booking flows.

2.1 Public Pages (No Auth Required)

2.2 Auth Pages

2.3 Booking Flow (Auth Required)

2.4 User Dashboard (Auth Required — /dashboard)

2.5 Admin Panel (Separate Next.js App — admin.ohbhaisahab.com)

3. Mobile App Sitemap (React Native Expo)

The Expo app uses Expo Router (file-based routing) with a 5-tab bottom navigation structure as defined in the PRD. Authentication state is managed via Zustand + Secure Store for JWT persistence.

3.1 Unauthenticated Stack

3.2 Main App — Bottom Tab Navigator

Tabs: Explore | My Treks | Profile (MVP scope — Tribe and Memories are post-MVP)

Tab 1: Explore

Tab 2: My Treks

Tab 3: Profile

3.3 Booking Flow (Modal Stack — overlays any tab)

3.4 Offline Strategy

• Itinerary PDFs are auto-cached to device storage 48 hours before trek start date (background fetch)
• Packing checklist state is persisted locally via SQLite (expo-sqlite); synced to server when online
• Trek detail page hero images and essential content cached via react-query persistent cache
• Offline indicator banner shown when network is unavailable; core app features remain usable
• Document upload queued locally when offline; auto-uploads when connectivity restored

4. Cloud & Infrastructure Cost Estimation

Estimates are in Indian Rupees (INR) per month at MVP scale (0–500 bookings/month, ~2,000 active users). Costs scale with usage — this is a conservative early-stage baseline. 1 USD ≈ ₹84.

4.1 Cloud Hosting — Backend API & Database

4.2 Website Hosting (Next.js)

4.3 File Storage (Trek Media + User Documents)

4.4 Communication Services

4.5 Payment Processing

4.6 Developer Accounts (One-Time Costs)

4.7 Monitoring & DevOps

4.8 Total Monthly Cost Summary

4.9 One-Time Setup Costs

4.10 Cost Scaling Guidance

• At 500 bookings/month (≈ ₹25L GMV): payment gateway fees ≈ ₹50,000; infrastructure stays in low range
• At 2,000 bookings/month: upgrade VPS to 4 vCPU / 8GB RAM (≈ +₹1,680/mo); consider managed Postgres (≈ +₹3,360/mo)
• At 10,000+ users: add Redis Cluster, CDN caching layer, consider Kubernetes or ECS; budget ₹50,000+/mo
• Mobile app OTA updates via Expo EAS Update are free on hobby tier; upgrade to production plan ($99/mo) at scale
• WhatsApp Business API becomes cost-effective over SMS above ₹100/customer LTV — factor in at Phase 2

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.

4.4 Guide-facing mobile routes

5. Frontend — Ongoing Treks Feature

5.1 Website: Ongoing Treks section

A new section on the Home page and a standalone /treks/ongoing page showing all batches currently in_progress or assembling.

5.2 Mobile app: Trek Leader screens

A new 'Leader HQ' section appears in the app for users with trek_leader role on any upcoming or active batch.

5.3 Mobile app: Guide screens

5.4 Participant-facing: ongoing trek card

In the My Treks tab, a booking with an active batch shows an enhanced card:

• Live status banner: 'Your trek is in progress — Day 3 of 7'
• Last update timestamp from status_updated_at
• Guide contact buttons (tap-to-call/WhatsApp for each guide)
• Trek leader name and emergency contact
• Incident note shown as a non-alarmist update banner if present (e.g. 'Short rest stop due to weather — continuing shortly')

6. Loyalty Credit on Trek Completion

6.1 Credit rules

Multipliers applied on top of base points:

6.2 BullMQ job: credit_loyalty_on_completion

Enqueued when batch status transitions to completed. Runs asynchronously — does not block the status update response.

6.3 Points→tier recomputation

Tier is recomputed from the cumulative SUM of all positive loyalty_points rows for a user. The tier levels (from the loyalty_tiers table) are evaluated after every credit. A downgrade on tier is not applied automatically — only upgrades happen automatically (prevents punishing users for redemptions).

7. Admin Panel Additions

7.1 Batch staff assignment UI

• On any batch detail page in admin, a 'Staff' tab shows current assignments
• 'Assign staff' button opens a user search modal; select user → pick role → save
• Enforce business rules in UI: warn if no trek_leader assigned; warn if fewer guides than recommended (trek.min_guides from trek config)
• 'Replace leader' flow: assigns new leader, marks old one is_active=false, adds a status_history note

7.2 Live batch monitor

New /admin/live page showing all batches with status in_progress or assembling in a real-time table (polling 30s):

• Batch name, trek, day N of M, leader name, participant count, last status update
• Quick-expand to see incident notes and full status history
• 'Contact leader' button (WhatsApp deep link or in-app message)
• Admin can force-complete or cancel any running batch from here (with mandatory reason)

7.3 Loyalty audit dashboard

• Table of all loyalty_pending_credits rows filterable by status
• 'Failed' rows shown prominently with error_detail and a manual retry button
• Batch completion summary: which batches have been credited, how many users, total points awarded

8. Migration Plan (Existing Data)

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.

4.4 Guide-facing mobile routes

5. Frontend — Ongoing Treks Feature

5.1 Website: Ongoing Treks section

A new section on the Home page and a standalone /treks/ongoing page showing all batches currently in_progress or assembling.

5.2 Mobile app: Trek Leader screens

A new 'Leader HQ' section appears in the app for users with trek_leader role on any upcoming or active batch.

5.3 Mobile app: Guide screens

5.4 Participant-facing: ongoing trek card

In the My Treks tab, a booking with an active batch shows an enhanced card:

• Live status banner: 'Your trek is in progress — Day 3 of 7'
• Last update timestamp from status_updated_at
• Guide contact buttons (tap-to-call/WhatsApp for each guide)
• Trek leader name and emergency contact
• Incident note shown as a non-alarmist update banner if present (e.g. 'Short rest stop due to weather — continuing shortly')

6. Loyalty Credit on Trek Completion

6.1 Credit rules

Multipliers applied on top of base points:

6.2 BullMQ job: credit_loyalty_on_completion

Enqueued when batch status transitions to completed. Runs asynchronously — does not block the status update response.

6.3 Points→tier recomputation

Tier is recomputed from the cumulative SUM of all positive loyalty_points rows for a user. The tier levels (from the loyalty_tiers table) are evaluated after every credit. A downgrade on tier is not applied automatically — only upgrades happen automatically (prevents punishing users for redemptions).

7. Admin Panel Additions

7.1 Batch staff assignment UI

• On any batch detail page in admin, a 'Staff' tab shows current assignments
• 'Assign staff' button opens a user search modal; select user → pick role → save
• Enforce business rules in UI: warn if no trek_leader assigned; warn if fewer guides than recommended (trek.min_guides from trek config)
• 'Replace leader' flow: assigns new leader, marks old one is_active=false, adds a status_history note

7.2 Live batch monitor

New /admin/live page showing all batches with status in_progress or assembling in a real-time table (polling 30s):

• Batch name, trek, day N of M, leader name, participant count, last status update
• Quick-expand to see incident notes and full status history
• 'Contact leader' button (WhatsApp deep link or in-app message)
• Admin can force-complete or cancel any running batch from here (with mandatory reason)

7.3 Loyalty audit dashboard

• Table of all loyalty_pending_credits rows filterable by status
• 'Failed' rows shown prominently with error_detail and a manual retry button
• Batch completion summary: which batches have been credited, how many users, total points awarded

8. Migration Plan (Existing Data)

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.

4.4 Guide-facing mobile routes

5. Frontend — Ongoing Treks Feature

5.1 Website: Ongoing Treks section

A new section on the Home page and a standalone /treks/ongoing page showing all batches currently in_progress or assembling.

5.2 Mobile app: Trek Leader screens

A new 'Leader HQ' section appears in the app for users with trek_leader role on any upcoming or active batch.

5.3 Mobile app: Guide screens

5.4 Participant-facing: ongoing trek card

In the My Treks tab, a booking with an active batch shows an enhanced card:

• Live status banner: 'Your trek is in progress — Day 3 of 7'
• Last update timestamp from status_updated_at
• Guide contact buttons (tap-to-call/WhatsApp for each guide)
• Trek leader name and emergency contact
• Incident note shown as a non-alarmist update banner if present (e.g. 'Short rest stop due to weather — continuing shortly')

6. Loyalty Credit on Trek Completion

6.1 Credit rules

Multipliers applied on top of base points:

6.2 BullMQ job: credit_loyalty_on_completion

Enqueued when batch status transitions to completed. Runs asynchronously — does not block the status update response.

6.3 Points→tier recomputation

Tier is recomputed from the cumulative SUM of all positive loyalty_points rows for a user. The tier levels (from the loyalty_tiers table) are evaluated after every credit. A downgrade on tier is not applied automatically — only upgrades happen automatically (prevents punishing users for redemptions).

7. Admin Panel Additions

7.1 Batch staff assignment UI

• On any batch detail page in admin, a 'Staff' tab shows current assignments
• 'Assign staff' button opens a user search modal; select user → pick role → save
• Enforce business rules in UI: warn if no trek_leader assigned; warn if fewer guides than recommended (trek.min_guides from trek config)
• 'Replace leader' flow: assigns new leader, marks old one is_active=false, adds a status_history note

7.2 Live batch monitor

New /admin/live page showing all batches with status in_progress or assembling in a real-time table (polling 30s):

• Batch name, trek, day N of M, leader name, participant count, last status update
• Quick-expand to see incident notes and full status history
• 'Contact leader' button (WhatsApp deep link or in-app message)
• Admin can force-complete or cancel any running batch from here (with mandatory reason)

7.3 Loyalty audit dashboard

• Table of all loyalty_pending_credits rows filterable by status
• 'Failed' rows shown prominently with error_detail and a manual retry button
• Batch completion summary: which batches have been credited, how many users, total points awarded

8. Migration Plan (Existing Data)

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.

4.4 Guide-facing mobile routes

5. Frontend — Ongoing Treks Feature

5.1 Website: Ongoing Treks section

A new section on the Home page and a standalone /treks/ongoing page showing all batches currently in_progress or assembling.

5.2 Mobile app: Trek Leader screens

A new 'Leader HQ' section appears in the app for users with trek_leader role on any upcoming or active batch.

5.3 Mobile app: Guide screens

5.4 Participant-facing: ongoing trek card

In the My Treks tab, a booking with an active batch shows an enhanced card:

• Live status banner: 'Your trek is in progress — Day 3 of 7'
• Last update timestamp from status_updated_at
• Guide contact buttons (tap-to-call/WhatsApp for each guide)
• Trek leader name and emergency contact
• Incident note shown as a non-alarmist update banner if present (e.g. 'Short rest stop due to weather — continuing shortly')

6. Loyalty Credit on Trek Completion

6.1 Credit rules

Multipliers applied on top of base points:

6.2 BullMQ job: credit_loyalty_on_completion

Enqueued when batch status transitions to completed. Runs asynchronously — does not block the status update response.

6.3 Points→tier recomputation

Tier is recomputed from the cumulative SUM of all positive loyalty_points rows for a user. The tier levels (from the loyalty_tiers table) are evaluated after every credit. A downgrade on tier is not applied automatically — only upgrades happen automatically (prevents punishing users for redemptions).

7. Admin Panel Additions

7.1 Batch staff assignment UI

• On any batch detail page in admin, a 'Staff' tab shows current assignments
• 'Assign staff' button opens a user search modal; select user → pick role → save
• Enforce business rules in UI: warn if no trek_leader assigned; warn if fewer guides than recommended (trek.min_guides from trek config)
• 'Replace leader' flow: assigns new leader, marks old one is_active=false, adds a status_history note

7.2 Live batch monitor

New /admin/live page showing all batches with status in_progress or assembling in a real-time table (polling 30s):

• Batch name, trek, day N of M, leader name, participant count, last status update
• Quick-expand to see incident notes and full status history
• 'Contact leader' button (WhatsApp deep link or in-app message)
• Admin can force-complete or cancel any running batch from here (with mandatory reason)

7.3 Loyalty audit dashboard

• Table of all loyalty_pending_credits rows filterable by status
• 'Failed' rows shown prominently with error_detail and a manual retry button
• Batch completion summary: which batches have been credited, how many users, total points awarded

8. Migration Plan (Existing Data)

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.

4.4 Guide-facing mobile routes

5. Frontend — Ongoing Treks Feature

5.1 Website: Ongoing Treks section

A new section on the Home page and a standalone /treks/ongoing page showing all batches currently in_progress or assembling.

5.2 Mobile app: Trek Leader screens

A new 'Leader HQ' section appears in the app for users with trek_leader role on any upcoming or active batch.

5.3 Mobile app: Guide screens

5.4 Participant-facing: ongoing trek card

In the My Treks tab, a booking with an active batch shows an enhanced card:

• Live status banner: 'Your trek is in progress — Day 3 of 7'
• Last update timestamp from status_updated_at
• Guide contact buttons (tap-to-call/WhatsApp for each guide)
• Trek leader name and emergency contact
• Incident note shown as a non-alarmist update banner if present (e.g. 'Short rest stop due to weather — continuing shortly')

6. Loyalty Credit on Trek Completion

6.1 Credit rules

Multipliers applied on top of base points:

6.2 BullMQ job: credit_loyalty_on_completion

Enqueued when batch status transitions to completed. Runs asynchronously — does not block the status update response.

6.3 Points→tier recomputation

Tier is recomputed from the cumulative SUM of all positive loyalty_points rows for a user. The tier levels (from the loyalty_tiers table) are evaluated after every credit. A downgrade on tier is not applied automatically — only upgrades happen automatically (prevents punishing users for redemptions).

7. Admin Panel Additions

7.1 Batch staff assignment UI

• On any batch detail page in admin, a 'Staff' tab shows current assignments
• 'Assign staff' button opens a user search modal; select user → pick role → save
• Enforce business rules in UI: warn if no trek_leader assigned; warn if fewer guides than recommended (trek.min_guides from trek config)
• 'Replace leader' flow: assigns new leader, marks old one is_active=false, adds a status_history note

7.2 Live batch monitor

New /admin/live page showing all batches with status in_progress or assembling in a real-time table (polling 30s):

• Batch name, trek, day N of M, leader name, participant count, last status update
• Quick-expand to see incident notes and full status history
• 'Contact leader' button (WhatsApp deep link or in-app message)
• Admin can force-complete or cancel any running batch from here (with mandatory reason)

7.3 Loyalty audit dashboard

• Table of all loyalty_pending_credits rows filterable by status
• 'Failed' rows shown prominently with error_detail and a manual retry button
• Batch completion summary: which batches have been credited, how many users, total points awarded

8. Migration Plan (Existing Data)

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.

4.4 Guide-facing mobile routes

5. Frontend — Ongoing Treks Feature

5.1 Website: Ongoing Treks section

A new section on the Home page and a standalone /treks/ongoing page showing all batches currently in_progress or assembling.

5.2 Mobile app: Trek Leader screens

A new 'Leader HQ' section appears in the app for users with trek_leader role on any upcoming or active batch.

5.3 Mobile app: Guide screens

5.4 Participant-facing: ongoing trek card

In the My Treks tab, a booking with an active batch shows an enhanced card:

• Live status banner: 'Your trek is in progress — Day 3 of 7'
• Last update timestamp from status_updated_at
• Guide contact buttons (tap-to-call/WhatsApp for each guide)
• Trek leader name and emergency contact
• Incident note shown as a non-alarmist update banner if present (e.g. 'Short rest stop due to weather — continuing shortly')

6. Loyalty Credit on Trek Completion

6.1 Credit rules

Multipliers applied on top of base points:

6.2 BullMQ job: credit_loyalty_on_completion

Enqueued when batch status transitions to completed. Runs asynchronously — does not block the status update response.

6.3 Points→tier recomputation

Tier is recomputed from the cumulative SUM of all positive loyalty_points rows for a user. The tier levels (from the loyalty_tiers table) are evaluated after every credit. A downgrade on tier is not applied automatically — only upgrades happen automatically (prevents punishing users for redemptions).

7. Admin Panel Additions

7.1 Batch staff assignment UI

• On any batch detail page in admin, a 'Staff' tab shows current assignments
• 'Assign staff' button opens a user search modal; select user → pick role → save
• Enforce business rules in UI: warn if no trek_leader assigned; warn if fewer guides than recommended (trek.min_guides from trek config)
• 'Replace leader' flow: assigns new leader, marks old one is_active=false, adds a status_history note

7.2 Live batch monitor

New /admin/live page showing all batches with status in_progress or assembling in a real-time table (polling 30s):

• Batch name, trek, day N of M, leader name, participant count, last status update
• Quick-expand to see incident notes and full status history
• 'Contact leader' button (WhatsApp deep link or in-app message)
• Admin can force-complete or cancel any running batch from here (with mandatory reason)

7.3 Loyalty audit dashboard

• Table of all loyalty_pending_credits rows filterable by status
• 'Failed' rows shown prominently with error_detail and a manual retry button
• Batch completion summary: which batches have been credited, how many users, total points awarded

8. Migration Plan (Existing Data)

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.

4.4 Guide-facing mobile routes

5. Frontend — Ongoing Treks Feature

5.1 Website: Ongoing Treks section

A new section on the Home page and a standalone /treks/ongoing page showing all batches currently in_progress or assembling.

5.2 Mobile app: Trek Leader screens

A new 'Leader HQ' section appears in the app for users with trek_leader role on any upcoming or active batch.

5.3 Mobile app: Guide screens

5.4 Participant-facing: ongoing trek card

In the My Treks tab, a booking with an active batch shows an enhanced card:

• Live status banner: 'Your trek is in progress — Day 3 of 7'
• Last update timestamp from status_updated_at
• Guide contact buttons (tap-to-call/WhatsApp for each guide)
• Trek leader name and emergency contact
• Incident note shown as a non-alarmist update banner if present (e.g. 'Short rest stop due to weather — continuing shortly')

6. Loyalty Credit on Trek Completion

6.1 Credit rules

Multipliers applied on top of base points:

6.2 BullMQ job: credit_loyalty_on_completion

Enqueued when batch status transitions to completed. Runs asynchronously — does not block the status update response.

6.3 Points→tier recomputation

Tier is recomputed from the cumulative SUM of all positive loyalty_points rows for a user. The tier levels (from the loyalty_tiers table) are evaluated after every credit. A downgrade on tier is not applied automatically — only upgrades happen automatically (prevents punishing users for redemptions).

7. Admin Panel Additions

7.1 Batch staff assignment UI

• On any batch detail page in admin, a 'Staff' tab shows current assignments
• 'Assign staff' button opens a user search modal; select user → pick role → save
• Enforce business rules in UI: warn if no trek_leader assigned; warn if fewer guides than recommended (trek.min_guides from trek config)
• 'Replace leader' flow: assigns new leader, marks old one is_active=false, adds a status_history note

7.2 Live batch monitor

New /admin/live page showing all batches with status in_progress or assembling in a real-time table (polling 30s):

• Batch name, trek, day N of M, leader name, participant count, last status update
• Quick-expand to see incident notes and full status history
• 'Contact leader' button (WhatsApp deep link or in-app message)
• Admin can force-complete or cancel any running batch from here (with mandatory reason)

7.3 Loyalty audit dashboard

• Table of all loyalty_pending_credits rows filterable by status
• 'Failed' rows shown prominently with error_detail and a manual retry button
• Batch completion summary: which batches have been credited, how many users, total points awarded

8. Migration Plan (Existing Data)

OBS EXPERIENCES

Addendum: Trek Batch Roles, Live Status & Loyalty

Extends MVP Architecture v1.0 | June 2026

1. Overview & Design Principles

This addendum extends the OBS MVP architecture to support multi-role batch staffing, a full trek lifecycle with status transitions, live 'ongoing treks' visibility on the frontend, and automated loyalty point crediting on batch completion.

Three principles guide the design:

• Single source of truth — batch status lives in one column on trek_batches; all derived state (frontend cards, loyalty jobs, notifications) reads from it.
• Role separation — Trek Leader owns operational authority (status transitions, incident logging); Guides are operational staff; Coordinators are back-office support. Users see none of this complexity.
• Idempotent loyalty — points are credited by a background job keyed on batch_id + user_id, so retries never double-credit.

2. Database Schema Changes

2.1 Updated trek_batches table

Existing columns carry forward. New and changed columns are marked.

2.2 New table: batch_staff

Replaces the old single guide_id FK on trek_batches. One batch can have multiple staff with distinct roles.

2.3 Enum: batch_staff_role

2.4 New table: batch_status_history

Append-only audit trail of every status transition. Never update or delete rows.

2.5 New table: loyalty_pending_credits

Staging table used by the post-completion loyalty job to ensure idempotency.

3. Trek Batch Status Lifecycle

3.1 Status enum values

3.2 Allowed transitions

3.3 Status transition API

PATCH /api/v1/batches/:id/status

Request body: { to_status, note?, location? }

Authorization: caller must have batch_staff role = trek_leader for operational transitions (assembling → in_progress → paused → completed). Admin JWT can perform any transition.

Server-side logic on this endpoint:

• Validate transition is in the allowed matrix above; return 422 if not
• Check caller is active trek_leader on this batch (or admin)
• Wrap in a transaction: UPDATE trek_batches SET status, status_updated_at, status_updated_by, started_at (if → in_progress), finished_at (if → completed)
• INSERT into batch_status_history
• If → completed: enqueue loyalty_credit BullMQ job with { batch_id, triggered_by, triggered_at }
• If → in_progress or assembling: send push notification to all confirmed participants
• Return updated batch object

4. API Routes — New & Updated

4.1 Batch staff management (Admin)

4.2 Batch status management (Trek Leader / Admin)

4.3 Leader-facing mobile routes

These routes are only visible/accessible to users who have an active batch_staff row with role = trek_leader.