Ref-007: SDS Template Structure & Authoring Process

Type

Reference Documentation

Purpose

Defines the canonical template structure for Software Design Specifications (SDS) and the process for generating them within the SEA-Forge™ ecosystem.

Template Structure

Required Sections

SDS-XXX — [Component/System Name]

System Overview

Purpose: What this component/system does
Scope: Boundaries and responsibilities
Architecture Pattern: Hexagonal, Layered, Microservices, Event-Driven, etc.
Status: Draft Review Approved Implemented

Component Architecture

Component: [Component Name]

Responsibilities: Key functions this component handles
Interfaces: APIs, contracts, ports (inbound/outbound)
Dependencies: What it depends on
Data Flow: How data moves through this component

Data Architecture

Data Model: Key entities and relationships
Storage: Database, file system, cache, etc.
Persistence Strategy: How data is stored and retrieved

API Specifications

Endpoint: [HTTP_METHOD] /api/path
- Purpose: What this endpoint does
- Request: Request format (schema, content-type)
- Response: Response format (schema, status codes)
- Error Codes: Possible errors and meanings

Non-Functional Requirements

Performance: Latency, throughput targets
Scalability: Growth expectations and horizontal/vertical scaling strategy
Security: Security measures, authentication, authorization, encryption
Reliability: Uptime targets, fault tolerance, disaster recovery

Technology Stack

Languages: Programming languages used
Frameworks: Key frameworks
Libraries: Important libraries and their purposes

PRD: [PRD-XXX]
ADR: [ADR-XXX]
TS: [TS-XXX]

Authoring Process

Generation Methods

SDS documents can be generated through the following approved workflows:

Chat Mode Integration
- Use @workspace #spec.lean for focused SDS generation
- Use @workspace #spec.wide for comprehensive context-aware SDS
Prompt-Based Generation
- Execute .github/prompts/spec.plan.sds.prompt.md
- Ensures consistency and completeness
Manual Creation
- Follow the template structure defined above
- Ensure all required sections are populated

Status Lifecycle

Draft → Review → Approved → Implemented

Each transition should be documented with rationale and date.

Architecture Patterns

Common Patterns Referenced

Pattern	When to Use
Hexagonal Architecture	Domain-driven design, clear boundaries, testability
Layered Architecture	Traditional n-tier applications, clear separation of concerns
Microservices	Independent scaling, team autonomy, bounded contexts
Event-Driven	Asynchronous processing, decoupling, real-time systems
CQRS	Read/write optimization, complex domains, event sourcing

Hexagonal Architecture (Ports & Adapters)

The example SDS demonstrates Hexagonal Architecture:

Domain Core: Pure business logic (AuthenticationService)
Inbound Ports: Interfaces for external access (IAuthenticationPort)
Outbound Ports: Interfaces for infrastructure (IUserRepositoryPort)
Adapters: Infrastructure implementations (OAuth2Adapter)

Component Architecture Guidelines

Responsibilities

Define a clear, single purpose for each component
Avoid overlap with other components
Follow Single Responsibility Principle

Interfaces

Document all ports (inbound/outbound in Hexagonal Architecture)
Specify contracts, DTOs, and API signatures
Include error handling strategies

Dependencies

Explicitly list dependencies to manage coupling
Prefer dependencies on abstractions (interfaces) over concrete implementations
Document transitive dependencies when critical

Data Flow

Describe the complete path of data through the component
Include transformations, validations, and enrichments
Note asynchronous vs. synchronous flows

Data Architecture Guidelines

Data Model

List key entities with attributes
Define relationships (1:1, 1:N, N:N)
Document constraints and invariants

Storage

Specify storage technology (PostgreSQL, MongoDB, Redis, S3, etc.)
Justify choice based on access patterns and NFRs

Persistence Strategy

Define patterns (Repository, Active Record, DAO)
Document transaction boundaries
Specify caching strategy if applicable

API Specification Guidelines

Endpoint Documentation

Use standard HTTP methods (GET, POST, PUT, PATCH, DELETE)
Include full path with parameters
Document authentication and authorization requirements

Request/Response Formats

Provide JSON schemas or TypeScript interfaces
Specify content types
Include example payloads

Error Codes

Document all possible error responses
Include HTTP status codes and error message formats
Provide guidance for error handling

Non-Functional Requirements (NFRs)

Performance Targets

Specify latency targets (e.g., p50, p95, p99)
Define throughput requirements (requests/second)
Document resource constraints

Scalability

Define growth expectations
Specify scaling strategy (horizontal, vertical, auto-scaling)
Document capacity planning

Security Requirements

List authentication mechanisms
Define authorization rules
Specify encryption requirements (at rest, in transit)
Document compliance requirements (GDPR, HIPAA, etc.)

Reliability Targets

Define SLA/SLO (e.g., 99.9% uptime)
Specify fault tolerance mechanisms
Document disaster recovery procedures

Technology Stack Documentation

Languages

List primary and secondary languages
Justify language choices

Frameworks

Document major frameworks
Include version constraints

Libraries

List critical dependencies
Note security or licensing considerations

Traceability Requirements

Each SDS MUST:

Link to originating PRDs (product requirements)
Reference architectural ADRs that constrain design
Cross-reference related Technical Specs (TS)
Maintain bidirectional links for audit trails

Example: Authentication Service

See template source for canonical example (SDS-001):

Pattern: Hexagonal architecture
Components: AuthenticationService (domain), OAuth2Adapter (infrastructure)
Data: PostgreSQL with repository pattern
API: POST /auth/login with OAuth2 flow
NFRs: <200ms validation, 99.9% uptime, PKCE security
Tech Stack: TypeScript, Express.js, Passport.js