SDS Authoring Guide

1. Overview

Software Design Specification (SDS) documents describe how the PCR Analysis System implements the requirements defined in the Software Requirements Specification (SRS). Where the SRS defines what the system must do, the SDS documents how it does it -- components, algorithms, data structures, integration points, and design rationale.

The SDS does not satisfy requirements directly -- it documents the design that satisfies them.

This means SDS documents never introduce new testable behavior. They explain the architecture, patterns, and code structures that implement SRS requirements, and they capture the why behind design decisions.

Definitive Format References

Rather than inventing from scratch, study these real documents as format exemplars:

Type	Document	What it demonstrates
System-level	sds/sds-03-architecture-overview.md	Tier 1 synthesis document; layer diagrams, tech stack, architectural patterns
Domain (config-heavy)	sds/domains/sds-domain-audit.md	Configuration-heavy character; entity diagrams, event-driven patterns, API tables
Rule design	sds/rules/sds-rules-engine.md	Algorithmic character; Rule Summary Block, truth tables, execution flowcharts
Reference	sds/reference/sds-ref-config.md	Tier 3 lookup material; config catalogs, precedence documentation
Template/conventions	sds/sds-01-introduction.md	Frozen template defining all section obligations, discharge phrasings, and notation

For repository layout, sidebar configuration, Docusaurus link mechanics, and build commands, see the contributor guide (./contributor-guide.md) if available.

---

2. Document Organization

2.1 Four-Tier Structure

SDS documents are organized into four tiers, each serving a distinct purpose:

Tier	Purpose	Satisfies Requirements?	File Location
Tier 1: System-Level	Cross-cutting concerns, architecture, shared patterns	No -- provides synthesis and constraints	sds/ (root)
Tier 2: Domain Design	How each functional domain works	No -- documents implementation of requirements	sds/domains/ and sds/rules/
Tier 3: Reference	Lookup material (API, database, config, glossary)	No -- factual reference	sds/reference/
Tier 4: Traceability	Mechanical mapping of REQ to Design to Code	No -- generated artifact	sds/traceability/

warning

Tier 1 documents do not satisfy individual requirements directly. No REQ-* identifier should trace primarily to a Tier 1 document. Requirements trace to Tier 2 domain or rule documents.

2.2 File Locations

sds/
├── sds-01-introduction.md          # Template & conventions (frozen)
├── sds-02-system-context.md        # External actors, boundaries
├── sds-03-architecture-overview.md  # High-level architecture
├── sds-04-data-architecture.md      # Global data model
├── sds-05-security-architecture.md  # Auth, authz, audit
├── sds-06-cross-cutting.md          # Logging, errors, config loading
├── sds-master-index.md              # Navigation hub
│
├── domains/                         # Tier 2: Domain design (14 files)
│   ├── sds-domain-audit.md
│   ├── sds-domain-kitcfg.md
│   └── ...
│
├── rules/                           # Tier 2: Rule design (8 files)
│   ├── sds-rules-engine.md
│   ├── sds-rules-classification.md
│   └── ...
│
├── reference/                       # Tier 3: Reference (4 files)
│   ├── sds-ref-api.md
│   ├── sds-ref-database.md
│   ├── sds-ref-config.md
│   └── sds-ref-glossary.md
│
└── sds-master-index.md              # Master document index

2.3 Domain Boundary Rule

Domain boundaries mirror SRS domain ownership. A requirement belongs to exactly one domain design document. Do not move requirements between domains or create hybrid domains. This keeps traceability mechanical and prevents boundary drift over time.

2.4 Master Index

sds-master-index.md serves as the navigation hub for all 34 SDS documents, organized both by topic (authentication, data processing, configuration, etc.) and by tier. When adding new sections or documents, update the master index so readers can find them.

---

3. Key Principles

3.1 Brevity Rule

Hard Rule: Sections exist to be discharged, not filled. Short is correct.

Empty or thin sections are not defects. If a domain has no state management, a one-line discharge ("This domain is stateless.") is the correct content. Reviewers should push back on unnecessary verbosity, not on brevity.

Explicit absence is valuable design information. A section that says "No external integrations" tells the reader something important -- it constrains the design surface area.

3.2 Domain Character Types

Every domain document declares its character in the header metadata. This primes reader expectations and justifies why some sections are heavy and others are discharged.

Character	Description	Typical Section Weight	Real Examples
Thin orchestration	Coordinates other domains, little owned logic	Light behavioral, heavy dependencies	NOTIF, RUNFILE, TABLES, GLOBALUI, REPORTS
Algorithmic	Complex decision logic, rules	Heavy behavioral, truth tables mandatory	REANALYZE, all rule documents
Configuration-heavy	CRUD operations, validation, import/export	Heavy data design, entity ownership	AUDIT, KITCFG, SETTINGS
Stateful	Manages persistent state transitions	State machines mandatory	ANALYTICS, RUNRPT, USERMGMT, FILEIMPORT
Integration	External system communication	Heavy interface design, error handling	CONFIGIO, FILEIMPORT

A thin orchestration document should be shorter than an algorithmic document. This asymmetry is correct -- do not enforce symmetry between documents.

3.3 Standard Discharge Phrasings

When a section does not apply to a domain, use one of these standard phrasings. This keeps brevity intentional and avoids stylistic drift across documents.

Section	Situation	Standard Phrasing
Data Design	No entity ownership	"This domain does not own persistent entities. It consumes read-only data from {X} and {Y}."
Data Design	No state	"This domain is stateless. All operations are request-scoped."
Interface Design	No APIs provided	"This domain does not expose APIs. It consumes data from {X}."
Behavioral Design	No complex logic	"Behavior is straightforward CRUD/delegation. See component responsibilities in section 2.2."
Error Handling	Delegates	"Error handling delegates to {X}. See [link] for error taxonomy."
Configuration	None	"This domain has no configurable behavior."
Performance	No concerns	"No non-obvious performance concerns. Standard query patterns apply."

3.4 Rule Document Specifics

Rule documents have additional mandatory elements beyond the standard template:

• Rule Summary Block (section 1.0): Mandatory at the top of every rule document. Contains Intent, Inputs, Outputs, and Precedence in a table. This lets reviewers orient before diving into truth tables and pseudocode.

• Truth tables: Mandatory for any rule with 2 or more boolean or categorical conditions. Must include Precedence (P1 highest), Default case, and Unreachable annotations.

• Precedence: Rule execution order must be documented. Rules with lower precedence values execute first.

---

4. Document Format

4.1 Header

Every SDS document starts with YAML frontmatter and a metadata blockquote. Domain, system-level, and reference documents each have their own metadata format.

Templates: Header Templates

4.2 Standard Sections (1-11)

The following sections define the structure of a domain or rule SDS document. Each is either mandatory (always present) or conditional (present only when substantive content exists). For copy-pasteable templates and discharge phrasings, see the SDS Document Templates.

Section 1: Overview (Mandatory)

Purpose, scope, domain character declaration, requirements covered, constraints, and dependencies. Rule documents also include a Rule Summary Block at 1.0.

Template and discharge phrasing: Overview

Section 2: Component Architecture (Mandatory)

Component diagram and responsibilities table showing what code implements the domain.

Template and discharge phrasing: Component Architecture

Section 3: Data Design (Conditional)

Present when the domain owns or significantly transforms persistent data.

Template and discharge phrasing: Data Design

Section 4: Interface Design (Conditional)

Present when the domain exposes APIs or consumes external services.

Template and discharge phrasing: Interface Design

Section 5: Behavioral Design (Conditional)

Present when the domain has non-trivial logic. This is where pseudocode algorithms and truth tables live. Truth tables are mandatory for rules with 2+ conditions.

Template and discharge phrasing: Behavioral Design

Section 6: Error Handling (Conditional)

Present when the domain has failure modes beyond "delegate to caller."

Template and discharge phrasing: Error Handling

Section 7: Configuration (Conditional)

Present when the domain has configurable behavior.

Template and discharge phrasing: Configuration

Section 8: Implementation Mapping (Mandatory)

Code locations and requirement traceability. Always present.

Template: Implementation Mapping

Section 9: Design Decisions (Mandatory)

Rationale for key choices. Always present, even if brief.

Template: Design Decisions

Section 10: Performance Considerations (Conditional)

Conditional for rules, optional elsewhere.

Template and discharge phrasing: Performance Considerations

Section 11: Related Documents (Mandatory)

Links to SRS, other SDS, and guides. Always present.

Template: Related Documents

4.3 Cross-Reference Formats

Relative paths depend on the file's location within the sds/ directory tree. For full path examples by source location, see Cross-Reference Formats.

---

5. Operations

5.1 When to Update Each Document Type

Change Type	SDS Documents Affected
Architecture patterns change	sds-03-architecture-overview.md
Data model / schema changes	sds-04-data-architecture.md, reference/sds-ref-database.md, affected domain docs (section 3)
Security / auth changes	sds-05-security-architecture.md
Cross-cutting concerns (logging, caching)	sds-06-cross-cutting.md
SRS domain requirements change	Corresponding domains/sds-domain-*.md (sections 1, 5, 8)
New components added to a domain	Corresponding domains/sds-domain-*.md (sections 2, 8)
Rule logic changes	Corresponding rules/sds-rules-*.md (sections 1.0, 5 truth tables, 8)
New rule added to a category	Corresponding rules/sds-rules-*.md + sds-rules-engine.md rule catalog
Rule precedence changes	rules/sds-rules-engine.md, affected rule doc section 1.0
New API endpoints	reference/sds-ref-api.md, affected domain doc section 4
Schema changes (tables/columns)	reference/sds-ref-database.md, affected domain doc section 3
New config options	reference/sds-ref-config.md, affected domain doc section 7
New terms introduced	reference/sds-ref-glossary.md

5.2 Adding New Content

New Section in an Existing Domain Document

1. Add section with an anchor: ### Section Title {#anchor-name}
2. Document the content (components, algorithms, data, etc.)
3. Reference the SRS requirements this section implements
4. Update section 8 (Implementation Mapping) with new code locations
5. Update sds-master-index.md if the section represents a major new topic

New Domain Document

1. Copy the header structure from an existing domain doc matching the character type
2. Declare domain character in the metadata blockquote
3. Fill all 11 sections -- discharge unused ones with standard phrasings
4. Include all REQ-* from the corresponding SRS in the Requirements Covered table
5. Map to code locations in section 8
6. Add the new document to sds-master-index.md in both the "By Concern" and "By Document Tier" sections
7. Update the Docusaurus sidebar configuration if needed

New Rule in an Existing Rule Document

1. Add a subsection under section 5 (Behavioral Design) with the algorithm and truth table
2. Add the rule to the Requirements Covered table in section 1.2
3. Update the Rule Summary Block in section 1.0 (precedence table)
4. Update the rule count in sds-rules-engine.md rule catalog (section 10)
5. Update section 8 (Implementation Mapping) with the new rule's code location

New Reference Entry

1. Add the entry in the appropriate reference document
2. Follow the existing format in that specific document (table structure, column headers)
3. Update related domain docs if they should cross-reference the new entry

5.3 Updating Diagrams

Mermaid diagrams (preferred): Edit directly in the markdown source. Standard diagram types:

Diagram Type	Use For
graph TB or graph LR	Component architecture, dependencies
flowchart TD	Decision logic, algorithms
sequenceDiagram	Interaction flows
erDiagram	Entity relationships
stateDiagram-v2	State machines

Mark illustrative diagrams explicitly with a blockquote beneath:

> This diagram illustrates the high-level flow. It does not specify implementation details.

Image-based diagrams: Update the source file, export as PNG, replace the file in docusaurus/static/media/, and verify rendering.

Validation: Run the Mermaid validation script to catch syntax errors before committing:

bash docusaurus/scripts/validate-mermaid.sh docusaurus/docs

tip

Mermaid syntax gotchas: pipe characters in labels conflict with edge syntax (use {"CT Diff > 2?"} not {|CT| > 2?}), forward slashes in labels need quotes (Node["/api/runs"]), and node IDs cannot match subgraph IDs.

5.4 Quality Checklist

For the full SDS quality checklist, see the Authoring Checklists Reference.