Architecture Overview

This page consolidates the current ignitionstack.pro architecture. It links the living code in ../src, captures our decision process (ADR + RFC), and documents the system with C4 Model diagrams so newcomers can reason about structure before touching code.

How We Document Architecture

Artifact	Purpose	Location
ADR (Architecture Decision Record)	Immutable record of why a structural decision happened.	content/architecture/adr-*.mdx
RFC (Request for Comments)	Proposal for upcoming work. Describe problem, goals, alternatives, rollout plan. Submit as docs/rfc/{id}-{slug}.mdx and link it here once approved.	docs/rfc/ (repo root)
C4 Model Diagrams	Visualise context, containers, and core components. Maintained in this page with Mermaid for repeatability.	This page

When introducing a new subsystem:

1. Draft an RFC that references the relevant C4 diagram block (Context, Container, or Component).
2. Once the RFC graduates to implementation, capture irreversible decisions as ADRs.
3. Update the diagrams and tables below so the visual representation stays in sync with src/app.

C4 Model

Level 1 · Context

Level 2 · Container

Level 3 · Component (Server Action Slice)

Runtime Overview

1. Presentation (App Router) – Everything under src/app/[locale]/ renders via React Server Components. Client-only features (chat input, analytics) use "use client" boundaries and hooks.
2. Application Layer – src/app/actions/* (mutations) and src/app/server/* (queries) orchestrate logic. All mutations must return ActionResult<T> and log via createServiceLogger.
3. Domain/Infrastructure Layer – Repositories in src/app/lib/repositories/* encapsulate Supabase calls, convert to typed entities (src/app/lib/mappers/*), and enforce per-entity validation. Supabase clients live in src/app/lib/supabase/{client,server,admin}.ts and respect RLS vs. admin contexts.
4. Observability – Structured logging through src/app/lib/logger.ts, analytics hooks (src/app/hooks/use-page-view.ts, use-click-tracking.ts), and GA/Playwright instrumentation described in /content/analytics/* and /content/testing/index.mdx.
5. Background/Webhooks – Route handlers (src/app/api/*) receive Stripe/Resend callbacks, call server actions/repositories, and use revalidateTag to keep cached UI in sync.

Module Inventory

Layer	Key Modules	Notes
Presentation	src/app/[locale]/(pages), src/app/components/*, src/app/hooks/*	Always load data via server queries or cached repositories.
Application	src/app/actions/*, src/app/server/*	Server actions are mutation-only; server queries are read-only, both return typed data.
Domain	src/app/lib/repositories/*, src/app/lib/mappers/*, src/app/lib/analytics-events.ts	Repository pattern centralizes Supabase, Analytics registry centralizes GA4 events.
Infrastructure	src/app/lib/supabase/*, supabase/migrations/*, scripts/test-build.sh	Supabase clients, migrations, and operational scripts.
Observability & Quality	content/analytics/*, src/app/test/**/*, playwright.config.ts, vitest.config.ts	Structured logging, GA4 specs, Vitest + Playwright suites.

Reference ADRs & RFCs

ID	Title	Summary	Status
RFC-002 (Planned)	Multi-tenant billing	Defines tenant-boundary caching, per-tenant metadata, and Stripe customer portal flows.	Draft (submit to docs/rfc/002-multitenant-billing.mdx)
RFC-003 (Planned)	AI Chatbot enterprise hardening	Formalizes throttling + retention for /chat.	Draft

Implementation Guidelines

1. Follow the layers – Components never call Supabase directly. Use server queries/actions which delegate to repositories.
2. Mermaid updates – When you introduce a new container or core component (e.g., background worker, new provider), update the diagrams above.
3. ADR before merge – If the change is irreversible or expensive to undo (new data store, protocol, security boundary), add an ADR under content/architecture and link it from the table.
4. RFC for large features – Anything spanning multiple squads or drastically affecting APIs should start life as an RFC. Reference the relevant C4 view and describe blast radius.
5. Zod everywhere – All incoming payloads (server actions, API routes, background jobs) must validate via src/app/lib/validations/* before reaching repositories.
6. Caching discipline – Mutations must call revalidateTag or revalidatePath for every cache tag touched in queries, otherwise stale UI persists.
7. Testing – Introduce or update Vitest/Playwright coverage whenever architecture evolves, per /content/testing/index.mdx.

Related Documents

• AI Chatbot GenAI Guide
• Analytics Architecture
• Testing Strategy

This page is the canonical place for architecture shape; keep it synchronized with src/ so devs, reviewers, and AI agents operate with the same mental model.