> ## 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.

# Cloud functions AGENTS

# 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.