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

Payments delegated to an internal subscription hub
Two-block Claude prompt caching
Distributed rate limiting without library lock-in
Indexes added from a live-DB audit, not guesswork

Read the spec

AdminOS

4 decisions

Tenant claims in service-role-only app_metadata
A four-layer AI cost engine
Fail-closed on ceilings, fail-open on outages
Meta WhatsApp Cloud API direct, not a BSP

Read the spec

K53 Drill Master

3 decisions

Two payment gateways, split by cadence, verified server-side
AI economics moved server-side
A quantified zero-library posture

Read the spec

Sanyu Botanicals

3 decisions

The engine owns inventory truth; the store only mirrors it
Rail-aware reservation expiry
Virtual "Angel" cards replace printed QR cards

Read the spec

The Selves of Us

4 decisions

Three Supabase clients, and the middle one is a footgun
MFA / AAL2 enforced at the edge
The Librarian is a live-archive RAG, not a static bot
Supabase over Firebase

Read the spec

True Access

4 decisions

Supabase is the source of truth; Mapbox is downstream
Separation of duties enforced in the database
A weighted, clause-cited SANS 10400-S score
A seeded audit backlog as a product mechanic

Read the spec

StokvelOS

3 decisions

AI at the edges, a deterministic core
Two-block prompt caching with per-message telemetry
Notion as an auto-provisioned transparency layer

Read the spec

WatchSankofa

3 decisions

Dual-model routing as explicit cost engineering
Split Cloudflare storage with direct-to-origin uploads
Postgres-as-engine, logic in triggers, not app code

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.