Ring:pre Dev Trd Creation

TRD Creation - Architecture Before Implementation

Foundational Principle

Architecture decisions (HOW/WHERE) must be technology-agnostic patterns before concrete implementation choices.

Specifying technologies in TRD creates:

• Vendor lock-in before evaluating alternatives
• Architecture coupled to specific products
• Technology decisions made without full dependency analysis

The TRD answers: HOW we'll architect the solution and WHERE components will live. The TRD never answers: WHAT specific products, frameworks, versions, or packages we'll use.

⛔ HARD GATE: Design Validation Prerequisite (Step -1)

This check MUST happen BEFORE any TRD work begins.

Step -1.1: Detect if Feature Has UI

Read PRD from docs/pre-dev/{feature}/prd.md and check for UI indicators:

• User stories with: "see", "view", "click", "navigate", "page", "screen", "button", "form"
• Features involving: login, dashboard, settings, profile, reports, notifications, UI, interface
• Any direct user-facing interaction

Step -1.2: If Feature Has UI → Verify Design Validation

⛔ HARD GATE: If feature has UI, design-validation.md MUST exist and show VALIDATED verdict.

Check: docs/pre-dev/{feature}/design-validation.md

If file NOT FOUND:
  → STOP. Cannot proceed to TRD.
  → Message: "Design Validation (Gate 1.5/2.5) not completed.
             Run ring:pre-dev-design-validation before TRD."

If file FOUND but verdict is NOT "DESIGN VALIDATED":
  → STOP. Cannot proceed to TRD.
  → Message: "Design Validation failed with gaps.
             Fix design gaps and re-run validation before TRD."

If file FOUND and verdict is "DESIGN VALIDATED":
  → PASS. Proceed to Step 0.

Step -1.3: If Feature Has NO UI → Skip to Step 0

Backend-only features do not require design validation. Proceed directly to tech stack definition.

Anti-Rationalization for Design Validation Check

Pressure Resistance for Design Validation Check

⛔ HARD BLOCK: Tech Stack Definition (Step 0)

This is a HARD GATE. Do NOT proceed without defining the tech stack.

Step 0.1: Auto-Detect or Ask User

Auto-detection: go.mod exists → Go | package.json with react/next → Frontend TS | package.json with express/fastify/nestjs → Backend TS

If ambiguous, AskUserQuestion: "What is the primary technology stack?" Options: Go (Backend), TypeScript (Backend), TypeScript (Frontend), Full-Stack TypeScript

Step 0.2: Load Ring Standards via WebFetch

Step 0.3: Read PROJECT_RULES.md

Check: docs/PROJECT_RULES.md → docs/STANDARDS.md (legacy) → STOP if not found

Step 0.4: Analyze PRD and Suggest Technologies

Read PRD, extract requirements, suggest technologies that address each, present to user for confirmation. Document in TRD metadata for Gate 6 to create PROJECT_RULES.md.

AskUserQuestion: "What deployment model?" Options: Cloud, On-Premise, Hybrid

Step 0.5: Document in TRD Metadata

TRD header must include: feature, gate: 3, deployment.model, tech_stack.primary, tech_stack.standards_loaded[], project_technologies[] (category, prd_requirement, choice, rationale per technology decision)

This metadata flows to Gates 4-6.

Pressure Resistance for Step 0

Mandatory Workflow

Explicit Rules

✅ DO Include

System architecture style (patterns, not products), component design with responsibilities, data architecture (ownership, flows - conceptual), API design (contracts, not protocols), security architecture (layers, threat model), integration patterns (sync/async, not tools), performance targets, deployment topology (logical)

❌ NEVER Include

Technology products (PostgreSQL, Redis, Kafka), framework versions (Fiber v2, React 18), language specifics (Go 1.24, Node.js 20), cloud services (AWS RDS, Azure Functions), packages (bcrypt, zod, prisma), container orchestration (Kubernetes, ECS), CI/CD details, IaC specifics

Technology Abstraction Rules

Rationalization Table

Red Flags - STOP

If you catch yourself writing any of these in a TRD, STOP:

• Specific product names with version numbers
• Package manager commands (npm install, go get, pip install)
• Cloud provider service names (RDS, Lambda, Cloud Run, etc.)
• Framework-specific terms (Fiber middleware, React hooks, Express routers)
• Container/orchestration specifics (Docker, K8s, ECS)
• Programming language version constraints
• Infrastructure service names (CloudFront, Cloudflare, Fastly)
• CI/CD tool names (GitHub Actions, CircleCI, Jenkins)

When you catch yourself: Replace the product name with the capability it provides. "PostgreSQL 16" → "Relational Database with ACID guarantees"

Gate 3 Validation Checklist

Gate Result: ✅ PASS → API Design | ⚠️ CONDITIONAL (remove product names) | ❌ FAIL (too coupled)

Common Violations

Pagination Strategy (Required for List Endpoints)

If feature includes list/browse, decide during TRD:

Document in TRD: API Patterns → Pagination → Strategy + Rationale

Authentication/Authorization Architecture (If Required)

If feature requires authentication or authorization (as determined in Question 2 of pre-dev command):

Document in TRD: Security Architecture → Authentication/Authorization → Strategy + Implementation Reference

Key Implementation Pattern (for TRD reference):

• Every protected endpoint requires middleware authorization
• Pattern: auth.Authorize(applicationName, resource, action) on each route
• Engineers will implement per-route protection following the referenced standard

Note for Go Services: Lerian's Access Manager (plugin-auth + identity + lib-auth) is the standard authentication system. Reference golang/security.md → Access Manager Integration section in the TRD so engineers know where to find implementation patterns including route middleware protection.

License Manager Architecture (If Required)

If feature is a licensed product/plugin (as determined in Question 3 of pre-dev command):

Document in TRD: Security Architecture → Licensing → Strategy + Implementation Reference

Key Architecture Pattern (for TRD reference):

• License validation as global middleware (applied early in chain)
• Fail-fast on startup: service refuses to start without valid license
• Graceful shutdown integration for license manager resources
• Built-in skip paths for health/readiness endpoints

Note for Go Services: Lerian's License Manager (lib-license-go) is the standard licensing system. Reference golang/security.md → License Manager Integration section in the TRD so engineers know where to find implementation patterns including global middleware and graceful shutdown.

Frontend-Backend Integration Pattern (If Fullstack)

⛔ HARD GATE: If the feature is fullstack (topology.scope: fullstack), this section is MANDATORY in the TRD.

Step 1: Read api_pattern from research.md

The api_pattern was determined during Topology Discovery (Q7) and persisted in research.md frontmatter.

# From research.md frontmatter
topology:
  scope: fullstack
  api_pattern: bff | none  # bff if dynamic data, none if static

Step 2: Document Pattern in TRD

TRD must include an ## Integration Patterns section:

## Integration Patterns

### Frontend-Backend Communication

**Pattern:** [direct | bff | other]

**Rationale:** [Why this pattern was chosen]

**Architecture Implications:**
- [List architectural decisions driven by this pattern]

Pattern-Specific Documentation

If api_pattern: none (Static Frontend):

### Frontend Architecture

**Pattern:** Static Frontend (no dynamic data)

**Rationale:** Pure static content, no server-side data fetching needed.

**Architecture Implications:**
- Static site generation (SSG) or client-side rendering of static content
- No API routes needed
- No backend integration
- Content embedded at build time or loaded from static files

**Data Flow:**
Build Process → Static HTML/JS → Browser

If api_pattern: bff (MANDATORY for dynamic data):

### Frontend-Backend Communication

**Pattern:** BFF (Backend-for-Frontend) layer

**Rationale:** [Multiple backend services | Complex data aggregation | Sensitive keys to hide | Request optimization needed]

**Architecture Implications:**
- Frontend calls BFF API routes (Next.js API Routes recommended)
- BFF aggregates data from multiple backend services
- Sensitive API keys stored server-side in BFF
- Response transformation happens in BFF layer
- Frontend receives optimized, frontend-specific data shapes

**Data Flow:**
Frontend Component → BFF API Route → Backend Service(s) → Database(s)

**BFF Responsibilities:**
- Data aggregation from multiple services
- Response transformation for frontend consumption
- Authentication token management (httpOnly cookies with Secure and SameSite attributes)
- Rate limiting and caching
- Error normalization

BFF Contract Specification (MANDATORY for BFF Pattern)

⛔ HARD GATE: If api_pattern: bff, this section MUST be included in TRD.

When This Applies

BFF Contract Structure

TRD MUST include a ## BFF Contracts section:

## BFF Contracts

### Purpose
Define typed contracts between BFF layer and Frontend components.

### Contract Per Feature

#### Feature: {feature_name}

**BFF Route:** `/api/{feature}/[operation]`

**Frontend Consumer:** `{ComponentName}`

**Request Contract:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| param1 | string | Yes | Description |
| param2 | number | No | Description |

**Response Contract:**
| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| data | object | No | Main response data |
| data.id | string | No | Entity identifier |
| data.name | string | No | Display name |

**Error Contract:**
| Error Code | Condition | Frontend Handling |
|------------|-----------|-------------------|
| VALIDATION_ERROR | Invalid input | Show field errors |
| NOT_FOUND | Resource missing | Show empty state |
| UNAUTHORIZED | Session expired | Redirect to login |

BFF-to-Backend Mapping

Document how BFF routes map to backend APIs:

### Backend API Mapping

| BFF Route | Backend APIs Called | Aggregation Logic |
|-----------|---------------------|-------------------|
| /api/dashboard | GET /users/:id, GET /orders?userId= | Merge user + recent orders |
| /api/profile | GET /users/:id, GET /preferences/:userId | Merge user + preferences |

Frontend-only BFF Creation

If topology.scope: frontend-only AND api_pattern: bff:

The feature requires creating a NEW BFF layer to consume existing backend APIs.

TRD MUST document:

1. BFF Location: Where BFF code will live (e.g., app/api/ for Next.js)
2. Existing APIs to Consume: List of backend endpoints (from PRD Data Sources)
3. BFF Routes to Create: New routes that aggregate/transform data
4. Type Definitions Location: Where shared types will be defined

### BFF Creation Plan (Frontend-only)

**BFF Framework:** Next.js API Routes / tRPC / Custom

**Existing Backend APIs (from PRD):**
- User API: GET /api/v1/users/:id
- Orders API: GET /api/v1/orders?userId=

**New BFF Routes:**

| Route | Purpose | Backend Calls | Response Shape |
|-------|---------|---------------|----------------|
| /api/dashboard | Dashboard data | users + orders | DashboardData type |
| /api/export/pdf | Generate PDF | orders | Blob |

**Type Definitions:**
- `types/api/dashboard.ts` - DashboardData, DashboardRequest
- `types/api/orders.ts` - Order, OrderList

Rationalization Table for BFF Contracts

BFF Task Ownership (MANDATORY for BFF Pattern)

⛔ HARD GATE: If api_pattern: bff, TRD MUST specify task ownership.

Task Assignment Rules

TRD MUST include a ## Task Ownership section when BFF is involved:

## Task Ownership

### BFF Implementation

| Task Type | Owner | Rationale |
|-----------|-------|-----------|
| BFF route creation | Frontend Engineer | BFF serves frontend, owned by consumer |
| BFF type definitions | Frontend Engineer | Types consumed by frontend components |
| Backend API integration | Frontend Engineer | BFF calls existing APIs |
| Error normalization | Frontend Engineer | Frontend defines error UX |
| Caching strategy | Frontend Engineer | Frontend knows cache requirements |

### Collaboration Points

| Activity | Frontend | Backend | Notes |
|----------|----------|---------|-------|
| BFF contract review | Author | Reviewer | Backend validates API assumptions |
| Type definitions | Author | Contributor | Shared types may exist |
| Error mapping | Author | Consultant | Backend clarifies error semantics |

Why Frontend Owns BFF

When Backend Should Own BFF

TRD Must Document

### BFF Ownership Decision

**Owner:** [Frontend Engineer | Backend Engineer]

**Rationale:** [Why this assignment]

**Coordination Required:**
- [ ] Backend API documentation review
- [ ] Type definition alignment
- [ ] Error code mapping

Rationalization Table for Task Ownership

Rationalization Table for Integration Patterns

⛔ HARD RULE: BFF is MANDATORY for Dynamic Data

Client-side code MUST NEVER call backend APIs, databases, or external services directly.

"Direct API calls" is FORBIDDEN. There is no api_pattern: direct option.

Design System & Styling (For Frontend Features)

⛔ HARD GATE: If the feature includes any user-facing UI, this section is MANDATORY.

Step 1: Detect UI Library

Auto-detection from package.json:

If no UI library detected, AskUserQuestion: "What UI component library will this project use?" Options: shadcn/ui (Recommended), Chakra UI, Material UI, Headless UI, Custom components

Step 2: Document Styling Configuration

TRD must include a ## Design System Configuration section:

## Design System Configuration

### UI Library
- **Library:** [Detected or chosen library]
- **Version:** [Package version from package.json]

### CSS Framework
- **Framework:** [TailwindCSS v4 / CSS Modules / Styled Components / etc.]
- **Config File:** [tailwind.config.ts / postcss.config.js / etc.]

### Theme Integration
- **CSS Variables Required:** Yes/No
- **Dark Mode:** prefers-color-scheme / class-based / not supported
- **Source Directive:** @source path for component styles

### Required CSS Imports
List CSS files that MUST be imported in globals.css:
- `@import "tailwindcss";`
- `@import "@library/dist/components/ui/button/styles.css";`
- etc.

### Theme Variables
Document required CSS custom properties:
- Color scale (zinc, shadcn)
- Spacing variables
- Component-specific variables (button, input, dialog)

Step 3: Component Availability Matrix

TRD MUST document which components exist in the chosen UI library:

### Component Availability

| Component Needed | Available in Library | Notes |
|------------------|---------------------|-------|
| Button | ✅ Yes | Variants: primary, secondary, outline |
| Dialog/Modal | ✅ Yes | Use DialogTrigger pattern |
| Form | ✅ Yes | Requires Form context wrapper |
| Input | ⚠️ Partial | Requires FormField context |
| IconButton | ✅ Yes | Separate component for icon-only |
| Toast | ✅ Yes | Requires Toaster provider |
| Table | ✅ Yes | Use TableHeader, TableBody, etc. |

### Missing Components (Must Create)
- [ ] Component X - not available, need custom implementation

Step 4: Variant Mapping

TRD MUST document available variants to prevent implementation errors:

### Button Variants (Example)

| Design Intent | Correct Variant | WRONG (Don't Use) |
|---------------|-----------------|-------------------|
| Primary action | `variant="primary"` | `variant="default"` |
| Secondary action | `variant="secondary"` | - |
| Cancel/neutral | `variant="outline"` | `variant="ghost"` |
| Destructive | `variant="primary" className="bg-red-600"` | `variant="destructive"` |
| Icon-only | Use `<IconButton>` | `<Button size="icon">` |

Rationalization Table for Design System

Red Flags - STOP

If reviewing a TRD for a UI feature and you see NONE of these, STOP and add them:

• No UI library specified
• No CSS framework documented
• No theme variables listed
• No component availability matrix
• No variant mapping

Gate 3 Validation Addition for UI Features

ADR Template

**ADR-00X: [Pattern Name]**
- **Context**: [Problem needing solution]
- **Options**: [List with trade-offs - no products]
- **Decision**: [Selected pattern]
- **Rationale**: [Why this pattern]
- **Consequences**: [Impact of decision]

Confidence Scoring

Action: 80+ present autonomously | 50-79 present options | <50 request clarification

Document Placement

trd.md is a shared document - it defines architecture for the entire feature.

Multi-repo handling:

# Read topology from research.md frontmatter
if [[ "$structure" == "multi-repo" ]]; then
    # Write to both repositories
    mkdir -p "{backend.path}/docs/pre-dev/{feature}"
    mkdir -p "{frontend.path}/docs/pre-dev/{feature}"

    # Write TRD to primary (backend)
    # Then copy to frontend
    cp "{backend.path}/docs/pre-dev/{feature}/trd.md" "{frontend.path}/docs/pre-dev/{feature}/trd.md"
fi

Sync footer for multi-repo:

---
**Sync Status:** Architecture document maintained in both repositories.

Output & After Approval

Output to:

• single-repo/monorepo: docs/pre-dev/{feature-name}/trd.md
• multi-repo: Both {backend.path}/docs/pre-dev/{feature}/trd.md AND {frontend.path}/docs/pre-dev/{feature}/trd.md

1. ✅ Lock TRD - architecture patterns are now reference
2. 🎯 Use as input for API Design (ring:pre-dev-api-design)
3. 🚫 Never add technologies retroactively
4. 📋 Keep architecture/implementation strictly separated

The Bottom Line

If you wrote a TRD with specific technology products, delete those sections and rewrite abstractly.

The TRD is architecture patterns only. Period. No product names. No versions. No frameworks.

Technology choices go in Dependency Map. That's the next phase. Wait for it.

Stay abstract. Stay flexible. Make technology decisions in the next phase with full analysis.