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 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

Standard	URL	Purpose
golang.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang.md	Go patterns, DDD
typescript.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/typescript.md	TS patterns, async
frontend.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend.md	React, Next.js, a11y
devops.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/devops.md	Docker, CI/CD
sre.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md	Health checks, logging

Tech Stack	Load
Go Backend	golang.md + devops.md + sre.md
TypeScript Backend	typescript.md + devops.md + sre.md
TypeScript Frontend	frontend.md + devops.md
Full-Stack TypeScript	typescript.md + frontend.md + devops.md + sre.md

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

Pressure	Response
"Tech stack doesn't matter for architecture"	"Architecture patterns vary by language. Go patterns ≠ TypeScript patterns. Define stack first."
"We'll decide tech stack later"	"Later = Dependency Map. But architecture NOW needs to know capabilities. Define stack."
"Just use generic patterns"	"Generic patterns miss stack-specific best practices. 5 min to define saves rework."
"Skip to save time"	"Skipping causes Gates 4-6 to ask again. Define once here, inherit everywhere."

---

Mandatory Workflow

Phase	Activities
1. Analysis (After Step 0)	PRD (Gate 1) required; Feature Map (Gate 2) optional; identify NFRs (performance, security, scalability); map domains to components
2. Architecture Definition	Choose style (Microservices, Modular Monolith, Serverless); design components with boundaries; define interfaces; model data architecture; plan integration patterns; design security
3. Gate 3 Validation	All domains mapped; component boundaries clear; interfaces technology-agnostic; data ownership explicit; quality attributes achievable; no specific products named

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

Element	Say This (✅)	Not This (❌)
Database	"Relational Database"	"PostgreSQL 16"
Cache	"In-Memory Cache"	"Redis" or "Valkey"
Message Queue	"Message Broker"	"RabbitMQ"
Object Storage	"Blob Storage"	"MinIO" or "S3"
Web Framework	"HTTP Router"	"Fiber" or "Express"
Auth	"JWT-based Authentication"	"specific library"

Rationalization Table

Excuse	Reality
"Everyone knows we use PostgreSQL"	Assumptions prevent proper evaluation. Stay abstract.
"Just mentioning the tech stack for context"	Context belongs in Dependency Map. Keep TRD abstract.
"The team needs to know what we're using"	They'll know in Dependency Map. TRD is patterns only.
"It's obvious we need Redis here"	Obvious ≠ documented. Abstract to "cache", decide later.
"I'll save time by specifying frameworks now"	You'll waste time when better options emerge. Wait.
"But our project template requires X"	Templates are implementation. TRD is architecture. Separate.
"The dependency is critical to the design"	Then describe the capability needed, not the product.
"Stakeholders expect to see technology choices"	Stakeholders see them in Dependency Map. Not here.
"Architecture decisions depend on technology X"	Then your architecture is too coupled. Redesign abstractly.
"We already decided on the tech stack"	Decisions without analysis are assumptions. Validate later.

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

Category	Requirements
Architecture Completeness	All PRD features mapped; DDD boundaries; single clear responsibilities; stable interfaces
Data Design	Ownership explicit; models support PRD; consistency strategy defined; flows documented
Quality Attributes	Performance targets set; security addressed; scalability path clear; reliability defined
Integration Readiness	External deps identified (by capability); patterns selected (not tools); errors considered; versioning strategy exists
Technology Agnostic	Zero product names; capabilities abstract; patterns named not implementations; can swap tech without redesign

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

Common Violations

Violation	Wrong	Correct
Tech in Architecture	Language: Go 1.24+, Framework: Fiber v2.52+, Database: PostgreSQL 16	Style: Modular Monolith, Pattern: Hexagonal, Data Tier: Relational DB, Key-value store, Object storage
Framework in Components	Fiber middleware for JWT, bcrypt for passwords, passport.js for OAuth2	Auth Component: Purpose, Inbound (HTTP endpoints), Outbound (persistence, notifications), Security (token-based, industry-standard hashing)
Cloud Services in Deployment	Compute: AWS ECS Fargate, Database: AWS RDS, Cache: ElastiCache	Compute: Container-based stateless, Data Tier: Managed DB with backup, Performance: Distributed caching, Traffic: Load balanced with health checks

Pagination Strategy (Required for List Endpoints)

If feature includes list/browse, decide during TRD:

Strategy	Best For	Trade-off	Performance
Cursor-Based	>10k records, infinite scroll, real-time	Can't jump pages	O(1)
Page-Based (Offset)	<10k records, admin interfaces	Degrades with large offsets	O(n)
Page-Based + Total Count	"Page X of Y" UI	Additional COUNT query	2 queries
No Pagination	Very small bounded datasets (<100)	All data at once	-

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):

Auth Type	TRD Description (Abstract)	Implementation Reference
User authentication only	"Token-based authentication with stateless validation"	For Go: golang.md → Access Manager Integration
User + permissions	"Token-based authentication with role-based access control (RBAC)"	For Go: golang.md → Access Manager Integration
Service-to-service	"Machine-to-machine authentication with client credentials"	For Go: golang.md → Access Manager Integration (GetApplicationToken)
Full (user + S2S)	"Dual-layer authentication: user tokens for end-users, client credentials for services"	For Go: golang.md → Access Manager Integration

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.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):

License Type	TRD Description (Abstract)	Implementation Reference
Single-org (global)	"Global license validation at service startup with fail-fast behavior"	For Go: golang.md → License Manager Integration
Multi-org	"Per-request license validation with organization context"	For Go: golang.md → License Manager Integration

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.md → License Manager Integration section in the TRD so engineers know where to find implementation patterns including global middleware and graceful shutdown.

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

Factor	Points	Criteria
Pattern Match	0-40	Exact before: 40, Similar: 25, Novel: 10
Complexity Management	0-30	Simple proven: 30, Moderate: 20, High: 10
Risk Level	0-30	Low proven: 30, Moderate mitigated: 20, High accepted: 10

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

Output & After Approval

Output to: docs/pre-dev/{feature-name}/trd.md

1. ✅ Lock TRD - architecture patterns are now reference
2. 🎯 Use as input for API Design (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.