Decisions That Cannot Be Undone

Why Architecture Before Features

Technical founders often pick tools intuitively. "I have used Postgres before, so Postgres." "Auth0 looks fine." "We will figure out multi-tenancy later." This works for prototypes. It fails catastrophically for products built with AI agents, because every agent session inherits those decisions. A bad early decision does not just live in one file. It propagates across every spec, every phase plan, and every AI-generated implementation.

The architecture blueprint is a single document that answers every infrastructure question before any code is written. It has two parts: the research process (how decisions are made) and the decision table (what was decided and why).

The Research Question Method

Before making any decision, identify every open question. Number them. Research them systematically. Document the findings. Then decide.

How It Works

Create a numbered list of research questions. Each question has a standard structure:

RQ-01: [Question title]
Context:    Why this matters for the product
Options:    The alternatives being considered
Criteria:   How we will evaluate (cost, complexity, scalability, DX, community)
Research:   Findings per option (documentation, benchmarks, community reports)
Decision:   What was chosen and why
Revisit:    Under what conditions this decision should be reconsidered

The research process is not "ask the AI which database to use." It is a structured investigation where the AI helps you gather and synthesize information, but you make the decision based on your product's specific needs.

Typical Research Questions

For a SaaS product, expect 15-30 research questions across these categories:

The Decision Table

After research is complete, consolidate every decision into a single table. This table is the reference that every downstream document checks against. If a PRD says "store files in S3" but the decision table says "Cloudflare R2," the PRD is wrong.

Structure

Every row answers: for this concern, what did we choose, what else was considered, why this choice, and when to revisit?

This table is not a suggestion list. It is a binding constraint. Every phase plan, every spec, and every AI agent must use these tools. If a research question arises during implementation ("should we use Redis for caching?"), the answer is either in this table or the table gets formally updated with the same research process.

Multi-Tenancy: The Decision That Touches Everything

Multi-tenancy deserves special attention because it affects every table, every query, every API route, and every test. Get it wrong and you either leak data between tenants (catastrophic) or create a migration nightmare (expensive).

The Three Models

RLS is the recommended default for most SaaS products. It scales, it is database-enforced (meaning application bugs cannot leak data), and it has a single migration path. The tradeoff is discipline: every table needs a tenant_id column, and every query must go through a tenant-scoped connection wrapper.

The Tenant Connection Pattern

The key implementation detail: create a wrapper function that sets the tenant context on every database connection. Every query in the application goes through this wrapper. Never use the raw database client directly.

// Generic pattern (adapt to your ORM)
function tenantDb(tenantId: string) {
  // Set the Postgres session variable that RLS policies read
  return db.$withAuth({ tenantId });
  // Every query through this connection is automatically filtered
  // by: WHERE tenant_id = current_setting('app.tenant_id')
}

// In a tRPC router
const issues = protectedProcedure.query(async ({ ctx }) => {
  const db = tenantDb(ctx.tenantId);
  return db.select().from(issues); // RLS filters automatically
});

Monorepo Structure

For a multi-app product, a monorepo is the natural choice. All apps share types, UI components, database schema, and API contracts. The package structure enforces the centralization principle: apps are consumers, packages are owners.

The key constraints that make this work:

• Apps import from packages, never from other apps. If apps/web needs something from apps/admin, it does not exist. That shared logic belongs in a package.
• packages/api is the sole bridge to infrastructure. Apps never import packages/db directly. They go through tRPC routers in packages/api.
• packages/ui is the sole owner of UI components. No component is defined in an app. All shared UI lives in one place.
• packages/ai is the sole gateway for LLM calls. No app or package calls OpenAI or Anthropic directly. All calls route through the AI gateway for metering, cost tracking, and provider routing.

These constraints are not guidelines. They are enforced by linter rules, import restrictions, and architectural fitness tests (covered in Part 11: Preventing Drift).

AI Pipeline Architecture (If AI-Native Product)

If the product uses AI/LLM capabilities (document extraction, classification, summarization, chat), the AI pipeline needs its own architectural decisions. This is not "call OpenAI." It is a system that meters usage, tracks cost per tenant, routes between providers, handles failures gracefully, and maintains accuracy targets.

The Centralized AI Gateway

All AI calls route through a single package. This gateway handles:

• Provider routing: Choose between OpenAI, Anthropic, or local models based on task type, cost, and availability.
• Metering: Track token usage per tenant per operation. Enforce tier limits.
• Cost tracking: Calculate cost per call. Aggregate per tenant per billing period.
• Fallback: If the primary provider is down, route to the secondary. If all providers are down, queue the request for retry.
• Structured output: Parse LLM responses into typed objects. Validate against schemas. Handle parsing failures.
• Confidence scoring: For extraction tasks, score each field's confidence. Flag low-confidence fields for human review.

Accuracy Targets

For any AI feature that extracts or classifies data, define accuracy targets before implementation. These targets become test assertions in the spec.

What You Leave With

After completing this step, you have one document:

This document is the technical constitution. Every downstream command references it. When a phase plan needs to decide which job framework to use, it checks the architecture blueprint. When a spec needs to know how to structure an API route, it checks the blueprint. When an AI agent is unsure about a tool choice, it checks the blueprint.

Next, the product needs a face. Part 3 covers the brand system, UI component inventory, and UX coherence guidelines that ensure every screen, built by any agent, looks and feels like the same product.