halobestie-clone/backend/CLAUDE.md

Halo Bestie — Backend

Fastify.js REST API serving both mobile apps and the internal control center.

See root CLAUDE.md for full project context and architectural decisions.

Stack

• Runtime: Node.js + Fastify.js
• Database: PostgreSQL via GCP Cloud SQL
• Auth: Self-managed JWT (HS256 access, 1h) + opaque refresh token (30d, rotated, bcrypt-hashed in auth_sessions). Firebase Auth removed in Phase 3.4 (commit f860ab6). firebase-admin is kept but only for FCM messaging.
• Payment: Xendit
• Infra: GCP Cloud Run

Two Listeners

Public  (0.0.0.0:3000)   → client_app + mitra_app routes
Internal (private IP:3001) → control_center routes only

Internal listener must never be exposed to the public internet.

Route Namespacing

/api/client/...    → client app routes
/api/mitra/...     → mitra app routes
/api/shared/...    → shared routes (e.g. auth, refresh, logout, anonymous)
/internal/...      → control center routes (internal listener only)

Auth Flow

• Mobile (client/mitra): Authorization: Bearer <access_token> header. Access token is our own JWT (HS256, AUTH_JWT_SECRET), with claims { sub, user_type, session_id }. Refresh via POST /api/shared/auth/refresh with the opaque refresh token in the body.
• Control center: Access token in Authorization: Bearer (kept in memory by the SPA). Refresh token lives in an httpOnly Secure cookie; refresh calls POST /internal/auth/refresh with credentials: 'include'.
• Entry points:
  • Anonymous customer: POST /api/shared/auth/anonymous
  • Phone OTP (customer/mitra): /api/{client,mitra}/auth/otp/{request,verify} — Fazpass is stubbed in otp.service.js; code is logged to the backend console ([OTP STUB] phone=… code=…) until real API docs arrive.
  • Google/Apple: /api/client/auth/{google,apple} (client_app only — creds pending)
  • CC login: POST /internal/auth/login (email + bcrypt password)
• Middleware: authenticate plugin verifies the JWT and attaches request.auth = { userType, userId, sessionId }. WebSocket handshake uses the same verification. No DB lookup on every request — the user ID is encoded in the token.

Key Conventions

• All routes must be authenticated unless explicitly marked public (auth + anonymous routes are the exceptions)
• Internal routes additionally require request.auth.userType === 'cc_user'
• Use Fastify plugins for shared middleware (auth, error handling, logging)
• Business logic lives in services/ — never directly in route handlers
• Never reintroduce Firebase Auth. firebase-admin is FCM-only; do not import .auth() from it.

Config-Source Convention

Two distinct knob-types exist; do not conflate them:

• DB-stored (app_config table, mutable via CC SettingsPage at runtime): used for operator-tunable values that may change between deploys without a code roll — mitra_stale_after_seconds, extension_timeout_seconds, pricing_tiers, support_handles_json, max_customers_per_mitra, etc. Read via getters in services/config.service.js. Cache invalidation goes through valkey pub/sub when needed.
• Env-driven (process.env, set per deployment via .env or Cloud Run env vars): used for deploy-fixed values that should never differ between operator actions — MITRA_HEARTBEAT_CADENCE_SECONDS, FIREBASE_SERVICE_ACCOUNT_PATH, AUTH_JWT_SECRET, DATABASE_URL. Always expose via a getter helper with a sane default + numeric parsing (see getMitraHeartbeatCadenceSeconds in config.service.js for the pattern).

When a new value needs to flow from CC → app, prefer DB. When it's a deploy-fixed contract (e.g. heartbeat cadence the apps must honor, Xendit credentials, callback tokens), prefer env. CC inputs that depend on env values (e.g. min/max validation) read the env-derived value via the same config endpoint that surfaces the DB value, and the PATCH route validates against it.

FCM Channel Convention

Single channel halobestie_chat_v1 is shared by both apps (registered in each app's core/notifications/notification_service.dart) and ships the branded halobestie_notif.ogg sound. Backend FCM payloads should always target this channel ID via android.notification.channelId:

android: { priority: 'high', notification: { channelId: 'halobestie_chat_v1' } }

Do not introduce per-recipient or per-feature channels lightly. If a new sound is required (e.g. payment alert), bump the channel ID (halobestie_chat_v2) and update both apps simultaneously — Android binds channel sound at create-time on API 26+, so mutating the existing channel doesn't pick up the new sound for installed users.