Builders

Start with the distinction that governs everything: in Astro the code of a .astro component runs at BUILD time (on your machine or in CI), not in the browser. The output is plain HTML. MOONKEY is exactly this: `astro.config.mjs` declares `i18n` with `fallbackType: 'rewrite'` and does NOT use SSR. When you run `npm run build`, Astro walks `src/pages/`, executes each .astro once per locale, and writes HTML to `dist/`. There's no server in production: Cloudflare Pages serves files. That's what makes `moonkeylab.pages.dev` load in milliseconds.

Build the skeleton from scratch to see it without the magic: `npm create astro@latest mi-sitio -- --template minimal --no-install`, then `cd mi-sitio && npm install && npm run dev`. Open `http://localhost:4321`. Edit `src/pages/index.astro` and watch how a `const hoy = new Date()` printed with `{hoy}` freezes at build time when you run `npm run build`. That's the aha moment: the frontmatter JS (between the `---`) runs once, not on every visit.

Now the fine-grained control: islands. By default a framework component (React/Svelte) in Astro renders to static HTML WITHOUT its JS. Only if you add a `client:*` directive does it hydrate. `client:load` hydrates on load, `client:visible` when it enters the viewport, `client:idle` when the thread is free. Rule of the trade: start with NO directive. Only add `client:visible` when the component genuinely NEEDS real interactivity. In MOONKEY the reveal `IntersectionObserver` lives in `Layout.astro` as a global `<script>`, not as a per-page island — that's the right call: a 15-line script instead of hydrating an entire framework.

Vite is the engine underneath Astro and also the one behind Espejo (which is a pure React SPA: `vite.config.ts`, `@vitejs/plugin-react`). The difference: Espejo DOES ship React to the browser because it needs live interactive state (camera readings with MediaPipe, navigation with react-router). That's the real dividing line of the craft: is the content mostly reading (XNLAB's site, MOONKEY) or is it an app with dense state (Espejo)? The former calls for Astro/SSG; the latter for Vite+SPA. Don't mix religions: don't cram an entire SPA inside Astro when 95% of it is content.

Measure, don't opine. Run `npm run build` and look at the size of `dist/`. In MOONKEY a content-page build should ship ~0KB of page JS (only the shared reveal script). Open DevTools → Network, reload with an empty cache and filter by JS: if you see a framework bundle on a page that's just text, you've added one `client:*` directive too many, or an import that drags a heavy library to the client. The command `npx astro build --verbose` lists what gets prerendered.

Classic failure mode: importing a date/markdown/icon library in the frontmatter thinking it's build-only, but then using it inside a client `<script>` or passing it to an island — and suddenly it ships in the bundle. Another: forgetting that `import.meta.env` in Astro distinguishes `PUBLIC_*` (goes to the client) from the rest (stays in build). If a variable you thought was private shows up in `dist/`, you prefixed it wrong. And the Vite trap: anything under `public/` is copied verbatim, unprocessed — don't put secrets there or expect Vite to optimize those assets.

A design token is a variable with a semantic name, not a raw value repeated. MOONKEY defines its own in `src/styles/global.css`: `--surface-base: #f8fafc`, `--text-primary: #0f172a`, plus the emerald/violet/amber palette. The golden rule: components NEVER use the raw hex, they use the token. That way `--surface-base` appears once; if the palette changes, you change one place. The antipattern is writing `color: #0f172a` in every card — you've coupled 30 files to a value that should have a name.

The most instructive case in the craft is in Espejo, because there the tokens are DYNAMIC per tenant. Look at `src/brand/BrandProvider.tsx`: the `applyTheme(brand)` function does `root.style.setProperty('--brand', brand.accent)` and derives `--brand-soft`, `--brand-line`, `--brand-glow` with a `withAlpha(hex, a)` function that converts the brand hex into rgba with transparency. Espejo's entire public UI paints with `var(--brand)`. The result: the same code serves Luna Rosa (pink `#e58fb0`) and any influencer, by changing ONE `accent` field. That's a design system that is also the white-label engine.

Component vs loose class: a component encapsulates structure + tokens + behavior under a name. MOONKEY has `PromptBlock`, `AnimalIcon`, `MoonkeyLogo`, `FlowDiagram` in `src/components/`. The signal that you need a component: you copy the same block of markup+classes a third time. Up to twice, duplicate; on the third, extract. Don't abstract earlier — the premature abstraction of a component with 8 props 'just in case' is worse than honest duplication.

With Tailwind there's a specific trap that MOONKEY documents explicitly: NEVER interpolate classes like `bg-${theme}`. Tailwind does tree-shaking by scanning the code for COMPLETE class strings at build; a class built at runtime doesn't exist in the generated CSS and renders unstyled. That's why `galaxy.ts` has a `THEME` object mapping each constellation to its literal classes (`violet`, `amber`, `emerald`…) already written out. The lesson: dynamic classes are resolved with a MAP of literal strings, not with interpolation.

Typography as a system token: MOONKEY fixes `font-display` = Space Grotesk for h1–h3, Inter for body, JetBrains Mono for labels (`.label` = mono uppercase tracking-widest emerald-600). That's not loose decoration: it's a decision encoded once that the whole app inherits. If every heading picked its own font, you wouldn't have a brand, you'd have noise. The system lives in the tokens/utilities layer, not in each `<h1>`.

How to verify coherence: grep for raw values that should NOT exist outside the tokens file. `grep -rn '#[0-9a-fA-F]\{6\}' src/components/` in MOONKEY should return almost nothing — if a hex appears in a component, it's a leaked token to replace with `var(--token)`. That grep is your hand-rolled linter for visual coherence, and you should run it before every merge.

Multi-tenant means: one instance of the software, many clients (tenants) who perceive it as their own. White-label adds: each tenant sees it with THEIR brand, with no trace of yours. Espejo is the canonical case — `src/brand/types.ts` says it in the comment: 'each influencer is a tenant with their brand'. The tenant is identified by a `slug` in the URL (`/r/<slug>`) and everything — name, accent, glyph, voice, which readings are offered, the upsell CTA — comes from a `Brand` object. The entire public app is painted from that object.

The architectural heart is the data SEAM. Look at `src/brand/store.ts`: it defines a `Store` interface with async signatures (`getBrand`, `listBrands`, `saveBrand`, `addSubscriber`, `listSubscribers`) and a `LocalStore` implementation over localStorage. The comment makes it explicit: 'Today: localStorage. Tomorrow: Supabase (same signatures). The UI never touches storage directly, only this interface.' That interface is the seam: the UI depends on the ABSTRACTION, not the implementation. Switching backends = writing a new class that implements `Store`, without touching a single component.

How the tenant reaches the UI: `BrandProvider.tsx` receives the `slug`, calls `store.getBrand(slug)`, and if it exists it runs `applyTheme(brand)` and puts the brand into a React Context (`useBrand()`). If it doesn't exist, it marks `notFound`. Clean pattern: one entry point resolves the tenant, applies its theme, and provides it to the whole tree. Any component calls `const brand = useBrand()` and paints its part. No one else touches storage or decides the theme.

Isolation between tenants is the red line of white-label, and here's the real risk: `listSubscribers(slug)` filters by `brandSlug`. In localStorage that's trivial but FRAGILE — everything lives in the same browser, there's no real security boundary. The critical moment is the migration to Supabase: there the isolation MUST move to Postgres RLS (a subscriber row is only visible to its tenant), exactly the discipline MOONKEY applies with `is_admin()` and self-or-admin policies. In real multi-tenant, the `WHERE slug = ...` filter in the client is NOT security; security is RLS in the database.

Per-tenant configuration without code branches: notice that Espejo has no `if (tenant === 'lunarosa')` anywhere. The variation is DATA (`Brand.readings`, `Brand.voice`, `Brand.offer`), not conditional logic. That's the rule of healthy white-label: the differences between clients live in configuration (data), never in code branches. The moment you write the first `if (client X)` you've started forking the product and losing the model's economics.

There's a specific ethical guardrail in Espejo that is not optional: the project memory states that NO covert lead siphoning or sale of personal/biometric data is to be built — only consented first-party data and anonymized aggregates. In a multi-tenant product that handles your clients' end-users' data, the consent model (`types.ts` has the version of the accepted consent text and `Brand.legal.responsible`) is part of the architecture, not a legal add-on bolted on later. The data controller is the influencer-tenant, and that must be modeled in the data.

MOONKEY runs 6 locales — `['es','en','th','fr','it','ch']` (config in `src/i18n/config.ts`). ES lives at the root; the rest under a prefix (`/en/`, `/th/`, `/fr/`, `/it/`, `/ch/`). The piece that avoids duplicating pages is Astro i18n with `fallbackType: 'rewrite'` in `astro.config.mjs`: during the build, Astro REWRITES each page with each locale's context, so a single `index.astro` generates 6 translated HTML files. There's no `pages/en/index.astro`, `pages/fr/index.astro`… there's ONE. That's the central rule: one template, N outputs.

The fallback is what makes the system robust without translating everything at once: `astro.config.mjs` declares `fallback: { en:'es', th:'es', fr:'es', it:'es', ch:'es' }`, and the `useTranslations` function in `src/i18n/utils.ts` implements the same chain: `dict[key] ?? base[key] ?? key`. That is: if a key is missing in French, it falls back to Spanish; if it's not there either, it returns the key itself (visible, easy to spot). This lets you SHIP with partial translations without breaking anything — French shows Spanish where you haven't translated yet, not a broken page.

MOONKEY uses THREE i18n patterns and CLAUDE.md warns about the inconsistency, which is a lesson of the craft in itself: (1) a `src/i18n/ui.ts` dictionary with `t('key')` for short chrome/nav (~240 keys); (2) inline content objects with `cLocale = (es|th) ? locale : 'en'` that collapses FR/IT/CH to EN, for heavy content like the curriculum; (3) `src/pages/en/*.astro` pages that override ONLY in English. Pattern 3 is debt: there are 5 root pages hardcoded in Spanish, so `/th/fr/it/ch` show ES on them. Lesson: pick ONE dominant pattern (the dictionary with fallback) and treat the others as debt to pay down, not as healthy variety.

The most expensive bug in prefixed i18n is the raw href. If you write `<a href='/cuenta'>` from a page under `/fr/`, you send the user out of their language. That's why MOONKEY has `localizedPath(pathname, target)` in `utils.ts`: it strips the current locale prefix, rebuilds the path and prepends the target (`/fr/cuenta`), leaving ES at the root. CLAUDE.md marks it as mandatory: 'use `localizedPath('/ruta', locale)`, never raw `/ruta`'. Internalize this: on a site with language prefixes, EVERY link passes through the localization function, no exceptions.

Detecting the active locale has a subtlety that `utils.ts` resolves: `resolveLocale(currentLocale, pathname)` prefers `Astro.currentLocale` over URL-based detection, because during a fallback rewrite the URL may have lost the prefix and only Astro's context knows the real locale. If you detect locale solely by `pathname.split('/')` you get it wrong precisely on the pages that use fallback. Rule: trust the framework context first, the URL as a backup.

The language selector needs two separate dictionaries: `LOCALE_LABELS` (ES, EN, TH…) for the compact switcher and `LOCALE_NAMES` (Español, ไทย, Italiano…) for the full dropdown. And watch the odd cases: 'ch' here is Deutsch (CH), Swiss German, not Chinese — a comment in `config.ts` clarifies it. That kind of ambiguity (a code that looks like another language) is exactly what you document in the code so nobody translates into the wrong language six months later.

MOONKEY deploys on Cloudflare Pages (`moonkeylab.pages.dev`) from the repo `garciafradepablo-pixel/xop`. The base flow: you connect the GitHub repo to Cloudflare Pages, set the build command (`npm run build`) and the output directory (`dist/` in Astro). Every push to main triggers a build in CI and publishes. You don't upload files by hand: the deploy is a consequence of git push. That gives you reproducibility — what's in production is exactly what's in the commit.

For a pure SSG like MOONKEY, Cloudflare just serves the static HTML from the build; there's no server runtime. This is key to the security model (you'll see it in Ops): since there's no server-side handler, the only env that matters in production is what was injected AT BUILD time. If your app needs server logic (not the case for MOONKEY or content-XNLAB), that's where Cloudflare Functions/Workers come in — but don't add them if you don't need them.

The secrets boundary is THE lesson of this module. In Astro/Vite, `PUBLIC_*` (Astro) or `VITE_*` (pure Vite like Espejo) variables are injected into the client bundle — they're VISIBLE to anyone who opens DevTools. Everything else stays in build. MOONKEY puts the Supabase anon key as public on purpose: CLAUDE.md says 'anon key only' in `src/lib/supabase.ts`, because the anon key is DESIGNED to be public (its power is limited by RLS, not by secrecy). The absolute rule: the `service_role` key NEVER carries a public prefix, NEVER goes to a static site. If you put it there, it's in the bundle, and it's game over.

On Cloudflare you configure the env vars in the dashboard (Settings → Environment variables), separating Production from Preview. The ones your build needs to expose to the client carry the correct prefix; the ones only the build process uses (third-party API tokens to generate content) don't carry it and don't end up in `dist/`. Mandatory post-deploy verification: download your production JS and run `grep -ri 'service_role\|secret\|sk_'` over `dist/`. If anything shows up, you have a leak to rotate immediately.

Custom domain: in Cloudflare Pages, Custom domains → add your domain, Cloudflare creates the DNS records (if the domain is on Cloudflare it's automatic; if not, you add a CNAME to the `*.pages.dev`). HTTPS is automatic. The `.pages.dev` keeps working as a backup URL. For previews, each PR/branch generates its own ephemeral URL — use them to review changes before merging to main, without touching production.

Real deploy failure modes: (1) the build passes locally but fails in CI because a dependency was in your local `node_modules` but not in `package.json` — run `npm ci` (not `install`) on a clean tree to reproduce CI. (2) Variables that exist locally (`.env`) but you didn't configure in the dashboard → the build passes but the app fails at runtime with undefined. (3) The cosmetic Astro warning about `Astro.request.headers` in static builds with i18n rewrite — `astro.config.mjs` documents it as harmless, the build passes. Don't chase warnings the config already flagged as expected.

Recall the seam from BD-03: in Espejo `src/brand/store.ts` defines a `Store` interface with async signatures and `LocalStore` implements it over localStorage. The comment is the module's entire thesis: 'Today: localStorage. Tomorrow: Supabase (same signatures).' Because the interface is ALREADY async (`Promise<Brand | null>`), the UI doesn't notice the difference between reading from memory or from the network — the `await` is already there. A synchronous API would have made the migration impossible without touching every call. Designing the seam async from day one is the decision that pays off here.

The concrete swap: you write a `SupabaseStore implements Store` class. `getBrand(slug)` goes from reading localStorage to `await supabase.from('brands').select().eq('slug', slug).single()`. `addSubscriber` goes from `write()` to `.insert()`. The signatures are IDENTICAL. In the end, one line changes the world: `export const store: Store = new SupabaseStore()` instead of `new LocalStore()`. Zero components touched. That's what 'changing the data layer without rewriting the app' means: the rest of the code depends on `Store`, not on localStorage.

But migrating the storage is the easy half. The serious half is SECURITY, and here the whole model changes. In localStorage there are no boundaries: everything lives in the user's browser. In Supabase, since the client only carries the anon key (MOONKEY: `src/lib/supabase.ts`, 'anon key only'), the authority is NOT the client — it's Postgres RLS. MOONKEY puts it without ambiguity: 'authority = RLS, not the client'. When Espejo migrates the subscribers, the `WHERE brandSlug = slug` filter it does today in JS MUST become an RLS policy guaranteeing that a tenant only reads ITS subscribers. The client filter was convenience; RLS is security.

Reference RLS pattern in MOONKEY: the `profiles/progress/feedback/proofs` tables have a 'self-or-admin' SELECT via `is_admin()` (a SECURITY DEFINER function), verified by impersonation — a non-admin can't read other people's rows. `proofs` INSERT requires a session and ties `user_id = auth.uid()` (the `proofs_insert_self` policy). Sensitive columns (`role`, `founder_badge`) are immutable for non-admins via a trigger guard, so no one self-escalates. That's the mental template for any migration: every operation (SELECT/INSERT/UPDATE) needs a policy that holds EVEN IF the attacker controls the client.

Data-migration hygiene: you need a schema (a `brands` table, a `subscribers` table with `brand_slug`), applied as a versioned MIGRATION (not loose SQL in the console — MOONKEY: 'RLS/security changes: versioned migration + `get_advisors` afterward'). Then a one-time script that reads the existing localStorage and does a bulk `insert` to the backend, idempotent (so you can re-run it without duplicating). And an optional double-write period if you can't stop the app: you write to both until you confirm parity, then cut over off localStorage.

Watch the ethical boundary Espejo carries: the project memory forbids covert siphoning of personal/biometric data; only consented first-party data and anonymized aggregates. Migrating to a backend INCREASES the power of the data (now it persists, gets cross-referenced, gets exported), so the consent model that in localStorage was almost theoretical becomes real and auditable. The technical migration and the responsibility over the data rise together — don't migrate the storage without also migrating the privacy guarantees.