ring:writing-trds

TRD Creation — Architecture Before Implementation

When to use

• PRD passed Gate 1
• Feature Map passed Gate 2 (Large Track only)
• About to design technical architecture

Skip when

• PRD not validated → complete Gate 1 first
• Architecture already documented → proceed to API Design (Large) or plan (Small)
• Pure business requirement change → update PRD

Sequence

Runs before: ring:designing-api-contracts (Large Track) / ring:writing-plans (Small Track) Runs after: ring:mapping-feature-relationships (Large Track) / ring:writing-prds (Small Track)

The TRD designs the technical architecture of the system or feature: components and their boundaries, data flow between them, integration points, and failure modes — using technology-agnostic patterns before concrete technology choices.

Handling Missing Information

When specific details are not provided (tech stack, architecture, team size, deployment model, etc.):

• Infer from project name, context, existing codebase patterns, and git history
• Document assumptions explicitly in a ## Assumptions section at the top of the TRD
• NEVER block execution to ask clarifying questions — assume and proceed
• Flag assumptions that carry high risk for the reader to validate (mark as ⚠️ Assumption:)
• The only valid exception: tech stack ambiguity in Step 0 when auto-detection fails and no codebase files exist to infer from

Step -1: Design Validation Check (UI Features Only, Conditional)

Read PRD and detect UI indicators (user stories with "see", "view", "click", "page", "screen", "button", "form"; features involving login, dashboard, settings, reports, notifications).

If feature has UI:

• Check docs/pre-dev/{feature}/design-validation.md (produced by a standalone ring:validating-ux-completeness run, if one happened)
• If present → honor its verdict: "DESIGN VALIDATED" proceeds; any other verdict means fix the listed design gaps before (or alongside) the TRD
• If absent → proceed and add to ## Assumptions: ⚠️ UX risk: no design validation ran for this UI feature — consider a standalone ring:validating-ux-completeness pass

If backend-only: Skip to Step 0.

Step 0: Tech Stack Definition (HARD GATE)

Step 0.1: Auto-Detect or Ask

• go.mod exists → Go
• package.json with react/next → Frontend TS
• package.json with express/fastify/nestjs → Backend TS
• Ambiguous → AskUserQuestion: "What is the primary technology stack?"

Step 0.2: Load Ring Standards via WebFetch

WebFetch base URL: https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/

Step 0.3: Read PROJECT_RULES.md

Check: docs/PROJECT_RULES.md → docs/STANDARDS.md (legacy) → if neither exists, note the absence and proceed with Ring standards.

Step 0.4: Analyze PRD and Suggest Technologies

Read PRD, extract requirements, suggest technologies per category, confirm with user.

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

Step 0.5: Document in TRD Metadata

TRD header must include: feature, gate: 3 (Large) / gate: 2 (Small), deployment.model, tech_stack.primary, tech_stack.standards_loaded[], project_technologies[] (category, prd_requirement, choice, rationale per decision). On Large Track this flows to Gates 4–6.

Mandatory Workflow

Program Design (Code Structure — MANDATORY)

Every TRD MUST include a ## Program Design section with two mandatory parts: (1) the bounded contexts / vertical slices the feature creates or touches, and (2) the source tree for each. This anchors implementation to Lerian's mandatory modeling — Modular Monolith + DDD + Hexagonal (ports & adapters) + CQRS-light — as shipped in the canonical go-boilerplate-ddd. It is the one place a TRD is concrete about code structure; it stays silent on product choices (see exception note under Technology Abstraction Rules).

Part 1 — Bounded Contexts (Vertical Slices) [MANDATORY]

In the Lerian model a vertical slice = bounded context = one internal/{context}/ module that owns its full stack top to bottom (adapters → ports → services → domain). Identifying them is the highest-leverage modeling decision and the most expensive to get wrong, so the TRD MUST make it explicit before any code is written.

Enumerate every context the feature creates or touches:

Slicing rules:

• Fewest contexts that hold. Extend an existing context by default; create a new one ONLY when the feature introduces a genuinely distinct ubiquitous language / ownership boundary. No speculative contexts.
• One context owns its data. Cross-context access goes through ports/, never by reaching into another context's tables.
• Large Track: contexts MUST be consistent with feature-map.md ## Phases — a phase may deliver one or more contexts; a context never straddles unrelated phases. Small Track: this table is the first place contexts are defined.

Part 2 — Source Tree [MANDATORY]

When tech_stack.primary is Go: render EACH context from Part 1 using the canonical slice layout. Replace {context} with the real bounded-context name (never ship example — that is the boilerplate's teaching scaffold).

internal/{context}/
├── adapters/
│   ├── http/          # driving adapter — thin Huma/HTTP handlers (parse, validate, call service)
│   ├── m2m/           # driving adapter — machine-to-machine (only if service-to-service auth)
│   └── postgres/      # driven adapter — persistence via lib-commons (libPostgres); no raw sql.Open
├── domain/
│   └── entities/      # entities + value objects; pure domain, imports no infrastructure
├── ports/             # interfaces only — driving (service contracts) + driven (repos / gateways)
├── services/
│   ├── command/       # CQRS write side — use cases that mutate state
│   └── query/         # CQRS read side — use cases that read state
├── streaming/         # event producers / consumers (Event-Driven profile only)
└── mocks/             # generated mocks for the ports

Shared/platform code lives OUTSIDE the slice — reference only what the feature touches:

Modeling rules to state alongside the tree:

• Dependencies point inward: adapters → ports ← services → domain. domain imports no infrastructure.
• Interfaces in ports/, implementations in adapters/.
• Keep handlers thin; infrastructure concerns stay in bootstrap, never in the slice.
• tenantId derives from validated request identity — never from JSON payload or path params.

When tech_stack.primary is not Go: mirror the project's equivalent canonical layout (or the existing module structure detected in the repo) and state the same context boundaries, dependency direction, and ports/adapters split. Do not invent a structure the codebase does not already use.

Technology Abstraction Rules

TRD never includes: product names with versions, package manager commands, cloud service names (RDS, Lambda), framework-specific terms, container/orchestration specifics, CI/CD tool names.

Exception — Program Design: the ## Program Design section IS concrete about code structure (layer and adapter folder names that mirror the mandatory boilerplate). Those names describe modeling slots, not product couplings — adapters/postgres/ is the persistence-adapter slot, not a PostgreSQL-version dependency. The abstraction rules above govern product/capability choices (DB engine, broker, cache); they never apply to the code-modeling tree.

Authentication/Authorization Architecture (If Required)

For Go services: reference golang/security.md → Access Manager Integration in TRD so engineers know implementation patterns.

License Manager Architecture (If Required)

For Go services: reference golang/security.md → License Manager Integration.

Frontend-Backend Integration (If Fullstack)

Read api_pattern from research.md frontmatter (bff or none).

If api_pattern: none: Document "Static Frontend — no API layer needed."

If api_pattern: bff: TRD MUST include ## Integration Patterns section:

• Pattern: BFF (Backend-for-Frontend)
• Frontend calls BFF API routes (Next.js API Routes recommended)
• BFF aggregates data from multiple backend services
• Sensitive API keys stored server-side
• Data Flow: Frontend → BFF API Route → Backend Service(s) → Database(s)

BFF Contracts section (MANDATORY when api_pattern: bff):

• BFF Route + Frontend Consumer + Request/Response contracts (flat, no data envelope)
• Error contracts per BFF route
• Backend API mapping (BFF route → backend APIs called → aggregation logic)
• Task ownership: Frontend Engineer owns BFF (consumer proximity, type safety chain)

HARD RULE: Client-side code MUST NEVER call backend APIs directly. api_pattern: direct does not exist for dynamic data.

Design System Configuration (UI Features)

Auto-detect from package.json: @your-org/design-system (your design-system package, if any), @radix-ui/*, @shadcn/ui, @chakra-ui/*, @mui/material, etc.

TRD must include ## Design System Configuration section:

• UI library + version
• CSS framework + config file
• Theme variables (color scale, spacing, component-specific)
• Component availability matrix (table: Component Needed / Available / Notes)
• Variant mapping (Design Intent → Correct Variant → Wrong variant)
• Required CSS imports in globals.css

Pagination Strategy (Required for List Endpoints)

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

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]

Gate Validation Checklist (Gate 3 Large / Gate 2 Small)

Gate Result: ✅ PASS → API Design / Gate 4 (Large) or plan / Gate 3 (Small) | ⚠️ CONDITIONAL (remove product names) | ❌ FAIL (too coupled or failure modes missing)

Document Placement