Decision Records

An architecture decision record states what was chosen, why, and what it costs — so a decision can be understood, and challenged, long after the moment it was made. These are the real, locked decisions for this platform. The reversals are recorded too, because pretending a decision was always obvious is how teams forget what they learned.

mirembemuse.co.za

Platform decisions

8 accepted records for this system. Each names its context, the decision, and the consequence we now live with.

ADR-0001Accepted2026-06-15

next-intl with as-needed locale prefixes

Context: The studio serves a multilingual audience (English, isiZulu, Afrikaans, French now; isiXhosa and Swahili planned) and an international diaspora. URLs had to stay clean for the default language while still being shareable per-locale.
Decision: All routes live under /app/[locale]/ behind next-intl with localePrefix: "as-needed" — the default locale has no prefix, the others do (/zu, /af, /fr).
Consequences: Clean canonical URLs for English; SEO-correct alternates per locale; every new page is multilingual by construction. The cost is that typed-route Links must be locale-aware and middleware mediates every request.

ADR-0002Accepted2026-06-18

Supabase Postgres with row-level security on every table

Context: The platform holds leads, orders, referrals and personal data under POPIA. Application-layer company_id filtering is one missed clause away from a cross-tenant leak.
Decision: Postgres on Supabase with RLS ENABLEd on all ten core tables. Public reads are gated by explicit policies (active products, approved testimonials, published content); private tables have no public policy and are reachable only via the service role.
Consequences: Isolation is enforced by the database, independent of developer discipline — defence in depth behind Arcjet, middleware and Zod. The cost is that every privileged write must consciously use the service role, never the cookie-bound client.

ADR-0003Accepted2026-06-19

PayFast for all payments — local and international

Context: An earlier plan used LemonSqueezy for international cards alongside a local gateway, doubling the integration and reconciliation surface. PayFast was confirmed to accept international cards.
Decision: PayFast handles every payment — ZAR and international — with MD5-signed ITN verification. A single gateway, deposit-first for all client work.
Consequences: One webhook, one reconciliation path, near-zero SA friction (EFT, no card required). The trade-off is SA-gateway coupling and ZAR as the settlement currency.
Supersedes: The earlier two-gateway plan (LemonSqueezy for international) — permanently removed.

ADR-0004Accepted2026-06-19

JarvisOS integration over signed webhooks only — never a shared database

Context: The private operating system, JarvisOS, runs the studio and lives institutionally within the business, but a shared database would couple two isolated security domains and blast-radius any incident across both.
Decision: The public site and JarvisOS communicate exclusively over HMAC-signed, replay-resistant webhooks with a timing-safe secret compare. No direct database access in either direction; each system owns its own Supabase project and auth.
Consequences: The engine stays a separate, isolated project surfaced only through signed callbacks — it appears ghosted in the architecture diagram. The cost is eventual-consistency semantics and idempotency keys instead of transactional reads.

ADR-0005Accepted2026-06-20

@react-pdf/renderer for documents — never headless Chromium

Context: Certificates, the press kit and the self-qualifying business-case PDF all need server-side document generation. Puppeteer/headless Chromium is heavy, slow to cold-start on serverless, and a large attack surface.
Decision: All PDFs render through @react-pdf/renderer via server-side renderToBuffer, behind Arcjet rate limits, recomputing values from trusted inputs rather than from client-supplied numbers.
Consequences: Fast, dependency-light generation that fits serverless cold-starts; documents are React components under version control. The trade-off is @react-pdf’s narrower layout model versus full HTML/CSS.

ADR-0006Accepted2026-06-18

Arcjet on every public API route; HMAC on every webhook

Context: Every public /api/* route is an open pipe — to bots, to abuse, and (for the AI routes) to the model itself. Webhooks are spoofable without signature verification.
Decision: Arcjet (bot detection, rate limiting, shield) guards every public API route; every inbound webhook verifies an HMAC signature with a timing-safe compare and, where applicable, a replay window. Secrets are never logged or exposed client-side.
Consequences: A consistent security floor across the whole API surface. The cost is an Arcjet decision on the hot path of every request — mitigated by its edge execution.

ADR-0007Accepted2026-06-21

Anthropic Claude as the primary AI provider, exceptions stated honestly

Context: The platform and its sibling apps lean heavily on LLMs. A single primary provider simplifies prompt-caching strategy, cost modelling and operational knowledge — but a blanket "Anthropic everywhere" rule would misrepresent products that deliberately chose otherwise.
Decision: Anthropic Claude (Haiku for this site’s assistant, streamed over SSE) is the primary provider across the platform. Deliberate exceptions are stated honestly per product — K53 Drill Master uses OpenAI gpt-4o-mini by design.
Consequences: Shared caching and cost discipline where it pays off, with an honest per-product provider note in every spec. No product ever claims a provider it does not use.
Supersedes: The earlier absolute "Anthropic for everything" — softened to "primary, with stated exceptions".

ADR-0008Accepted2026-06-22

Dependency-free, GrowthBook-compatible feature flags

Context: The homepage CTA needed an A/B test and the studio wanted feature flags, but adding a hosted flagging SDK meant another vendor, another secret and client-bundle weight.
Decision: A small in-repo flag evaluator using the GrowthBook rule format — no SDK dependency — drives the homepage CTA experiment and any future flags.
Consequences: Zero added vendor surface and a migration path to hosted GrowthBook if scale ever demands it. The trade-off is that advanced targeting must be hand-rolled until then.

Across the ecosystem

Per-product decisions

Each product keeps its own decision record, drawn from that product’s build journals and documented in full on its spec — context, choice and consequence per decision.

VarsityOS

4 decisions

App Router + RSC over Pages Router
Two-block Claude prompt caching
Trusted Web Activity, not a native app
RLS from day one; service role only in the ITN webhook

Read the spec

AdminOS

4 decisions

Multi-tenancy via Postgres RLS at the engine level
Three-layer AI cost architecture
Meta WhatsApp Cloud API direct, not a BSP
PayFast, ZAR-only, MD5-signed ITN

Read the spec

K53 Drill Master

3 decisions

Routerless SPA
PayFast over Stripe
gpt-4o-mini, temperature 0, cached

Read the spec

Sanyu Botanicals

3 decisions

The engine is authoritative for inventory
Two distinct webhook auth schemes
Best-effort, non-blocking, no-op without secrets

Read the spec

The Selves of Us

4 decisions

Supabase over Firebase
Edge auth in middleware
Cookieless admin client behind explicit role checks
ISR on public pages, fresh reads for admin

Read the spec

True Access

4 decisions

A universal Expo Router app
Supabase is the source of truth for locations, not Mapbox
A weighted SANS 10400-S compliance score
Offline + data-light first

Read the spec

StokvelOS

3 decisions

WhatsApp as the primary interface, not the app
Notion as the transparency layer
Confirmation-gated, receipt-numbered transactions

Read the spec

WatchSankofa

3 decisions

Server components + client islands only for the players
Zustand persist for the audio player, not Redux/Context
A custom video player over react-player

Read the spec

Decisions, made legible

See the same thinking across three lenses — business, engineering and human — on the build page.

How we build Data & Schema →

Decision Records

Platform decisions

8 accepted records for this system. Each names its context, the decision, and the consequence we now live with.

ADR-0001Accepted2026-06-15

next-intl with as-needed locale prefixes

Context: The studio serves a multilingual audience (English, isiZulu, Afrikaans, French now; isiXhosa and Swahili planned) and an international diaspora. URLs had to stay clean for the default language while still being shareable per-locale.
Decision: All routes live under /app/[locale]/ behind next-intl with localePrefix: "as-needed" — the default locale has no prefix, the others do (/zu, /af, /fr).
Consequences: Clean canonical URLs for English; SEO-correct alternates per locale; every new page is multilingual by construction. The cost is that typed-route Links must be locale-aware and middleware mediates every request.

ADR-0002Accepted2026-06-18

Supabase Postgres with row-level security on every table

Context: The platform holds leads, orders, referrals and personal data under POPIA. Application-layer company_id filtering is one missed clause away from a cross-tenant leak.
Decision: Postgres on Supabase with RLS ENABLEd on all ten core tables. Public reads are gated by explicit policies (active products, approved testimonials, published content); private tables have no public policy and are reachable only via the service role.
Consequences: Isolation is enforced by the database, independent of developer discipline — defence in depth behind Arcjet, middleware and Zod. The cost is that every privileged write must consciously use the service role, never the cookie-bound client.

ADR-0003Accepted2026-06-19

PayFast for all payments — local and international

Context: An earlier plan used LemonSqueezy for international cards alongside a local gateway, doubling the integration and reconciliation surface. PayFast was confirmed to accept international cards.
Decision: PayFast handles every payment — ZAR and international — with MD5-signed ITN verification. A single gateway, deposit-first for all client work.
Consequences: One webhook, one reconciliation path, near-zero SA friction (EFT, no card required). The trade-off is SA-gateway coupling and ZAR as the settlement currency.
Supersedes: The earlier two-gateway plan (LemonSqueezy for international) — permanently removed.

ADR-0004Accepted2026-06-19

JarvisOS integration over signed webhooks only — never a shared database

Context: The private operating system, JarvisOS, runs the studio and lives institutionally within the business, but a shared database would couple two isolated security domains and blast-radius any incident across both.
Decision: The public site and JarvisOS communicate exclusively over HMAC-signed, replay-resistant webhooks with a timing-safe secret compare. No direct database access in either direction; each system owns its own Supabase project and auth.
Consequences: The engine stays a separate, isolated project surfaced only through signed callbacks — it appears ghosted in the architecture diagram. The cost is eventual-consistency semantics and idempotency keys instead of transactional reads.

ADR-0005Accepted2026-06-20

@react-pdf/renderer for documents — never headless Chromium

Context: Certificates, the press kit and the self-qualifying business-case PDF all need server-side document generation. Puppeteer/headless Chromium is heavy, slow to cold-start on serverless, and a large attack surface.
Decision: All PDFs render through @react-pdf/renderer via server-side renderToBuffer, behind Arcjet rate limits, recomputing values from trusted inputs rather than from client-supplied numbers.
Consequences: Fast, dependency-light generation that fits serverless cold-starts; documents are React components under version control. The trade-off is @react-pdf’s narrower layout model versus full HTML/CSS.

ADR-0006Accepted2026-06-18

Arcjet on every public API route; HMAC on every webhook

Context: Every public /api/* route is an open pipe — to bots, to abuse, and (for the AI routes) to the model itself. Webhooks are spoofable without signature verification.
Decision: Arcjet (bot detection, rate limiting, shield) guards every public API route; every inbound webhook verifies an HMAC signature with a timing-safe compare and, where applicable, a replay window. Secrets are never logged or exposed client-side.
Consequences: A consistent security floor across the whole API surface. The cost is an Arcjet decision on the hot path of every request — mitigated by its edge execution.

ADR-0007Accepted2026-06-21

Anthropic Claude as the primary AI provider, exceptions stated honestly

Context: The platform and its sibling apps lean heavily on LLMs. A single primary provider simplifies prompt-caching strategy, cost modelling and operational knowledge — but a blanket "Anthropic everywhere" rule would misrepresent products that deliberately chose otherwise.
Decision: Anthropic Claude (Haiku for this site’s assistant, streamed over SSE) is the primary provider across the platform. Deliberate exceptions are stated honestly per product — K53 Drill Master uses OpenAI gpt-4o-mini by design.
Consequences: Shared caching and cost discipline where it pays off, with an honest per-product provider note in every spec. No product ever claims a provider it does not use.
Supersedes: The earlier absolute "Anthropic for everything" — softened to "primary, with stated exceptions".

ADR-0008Accepted2026-06-22

Dependency-free, GrowthBook-compatible feature flags

Context: The homepage CTA needed an A/B test and the studio wanted feature flags, but adding a hosted flagging SDK meant another vendor, another secret and client-bundle weight.
Decision: A small in-repo flag evaluator using the GrowthBook rule format — no SDK dependency — drives the homepage CTA experiment and any future flags.
Consequences: Zero added vendor surface and a migration path to hosted GrowthBook if scale ever demands it. The trade-off is that advanced targeting must be hand-rolled until then.