Technical Architecture v1.3: Conditional Pass at 3.67/5.0

Architecture is the phase where you decide what kind of technical debt you are willing to accept. Every choice closes doors and opens others. We documented ours.

The 5 decisions that shaped everything

Next.js App Router over Pages Router. Server Components as the default rendering strategy. Client components only where we need interactivity. This eliminates the "everything is client-side" pattern that kills performance on content-heavy sites.

Supabase over custom backend. Managed PostgreSQL with built-in auth, Row Level Security, and realtime subscriptions. We do not need a custom auth system. We do not need a custom database layer. We need to ship features.

Zustand over Redux. Our client-side state is simple — theme toggles, filter selections, form wizards. Redux is designed for state that needs time-travel debugging and middleware chains. Ours does not.

CSS Modules + Tailwind hybrid. Design tokens live in CSS custom properties. Layout utilities come from Tailwind. Component-specific styles use CSS Modules. No runtime CSS-in-JS overhead.

TanStack Query for server state. Cache invalidation, optimistic updates, and background refetching — without building a custom data layer.

Refiner score: 3.67/5.0

The Architecture Refiner flagged 4 gaps: incomplete caching strategy, missing rate limiting specification, underspecified error handling patterns, and no disaster recovery plan. All tracked. The conditional pass means we proceed to design while addressing these incrementally — they do not block frontend work.

Schema Deviation Log

We built Phase 2 and 3 tables during Phase 1 development (payments, enrollments, digital products). This is fine if documented. Undocumented schema deviations become landmines when the spec catches up and finds tables it did not expect. So we log every early-build table in the architecture spec.