Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mareaalcalina.com/llms.txt

Use this file to discover all available pages before exploring further.

​
DRAFT — marea-alcalina-cloud-functions/AGENTS.md

Coordinated PR target (BL-DOC-5): Agent A owns marea-alcalina-cloud-functions/. PRD-12 (this repo) is responsible for drafting the engineer-side AGENTS.md content; Agent A reviews + commits it to the cloud-functions repo. Do NOT directly write into the cloud-functions repo from here. Once Agent A merges this draft to marea-alcalina-cloud-functions/AGENTS.md, delete this file from marea-alcalina-docs/coordination/.

​
AGENTS.md — Marea Cloud Functions

​
What this repo is

Firebase Cloud Functions backing Marea Alcalina (catalog + orders + WhatsApp + email + payments). Public REST API at api.mareaalcalina.com/v1/* (PRD-1+).

​
Architecture

  • Express + middleware chain (PRD-1 §10.x — 12 middleware in fixed order).
  • Firestore for data; Cloud Tasks for webhook delivery.
  • Two-tier API keys: mk_dev_* (developer; can bootstrap) + mk_user_* (per-user; cannot bootstrap) — PRD-1 + PRD-6.

​
Repo conventions

  • All v1 endpoints in src/api/v1/.
  • Refactored cores in src/api/services/ (PRD-2 + PRD-3).
  • Middleware in src/api/middleware/.
  • Zod schemas drive request validation AND OpenAPI generation (PRD-1 §10.3 via @asteasolutions/zod-to-openapi).
  • NEVER scan full Firestore collections — Firestore reads cost money. Always use targeted queries (see feedback_firestore_reads.md in user memory).
  • NEVER invent MRR / pricing / plan facts — pull from Stripe API or plan-limits.shared.ts only (see feedback_no_invent_match_stripe.md).

​
Where to find specs

  • PRDs: Strategic-2026-Plan/prds/PRD-{03..13}-public-api-*.md
  • Playbook: Strategic-2026-Plan/prds/00-PUBLIC-API-V1-IMPLEMENTATION-PLAYBOOK.md
  • RFC: Strategic-2026-Plan/rfcs/RFC-public-api-v1.md
  • Strategy: Strategic-2026-Plan/05-PUBLIC-API-V1-EXECUTION-STRATEGY.md

​
Key invariants (BL locks)

  • Idempotency cross-instance race protection (PRD-1).
  • 6-digit verification code is PLAIN, not bcrypt-hashed (PRD-3 BL-BOOT-3 — intentional: enables read-aloud variant).
  • hardDeleteUserAccount is atomic (PRD-3 BL-BOOT-8).
  • Publish endpoint middleware order: planLimits → requireTosAccepted → idempotency (PRD-7 BL-TOS-3).
  • bootstrapRpd: 50 per mk_dev_* key per day (PRD-1).
  • 5-minute replay window on webhook signatures (PRD-8).

​
Testing & deploy

  • npm run build after non-trivial changes (per feedback_always_build_to_verify.md — tsc alone misses Angular template / i18n / Tailwind issues; for cloud-functions it catches missing imports + Zod schema drift).
  • Validate CI configs before push (per feedback_validate_before_push.md).
  • Production deploy is gated on Stage-0 ship checklist in playbook §9.