Software Design Specification: Introduction

Document Type: System-Level (Tier 1) Status: Draft Last Updated: 2026-01-25

---

1. Purpose

This Software Design Specification (SDS) describes how the PCR Analysis System implements the requirements defined in the Software Requirements Specification (SRS).

The SDS answers:

• What components exist and how they interact
• What data structures and algorithms are used
• Where requirements are implemented in code
• Why specific design decisions were made

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

---

2. Scope

2.1 What This SDS Covers

• System architecture and component decomposition
• Domain-specific design for each functional area
• Rules engine design and decision logic
• Data models and state management
• API contracts and integration points
• Implementation traceability (REQ → Design → Code)

2.2 What This SDS Does Not Cover

• Requirements themselves (see SRS)
• Test procedures (see STD/STR)
• Operational procedures (see deployment documentation)
• User documentation

---

3. Document Organization

3.1 Document Tiers

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

Constraint: Tier 1 documents do not satisfy individual requirements directly. They provide synthesis and constraints shared across domains. No REQ-* identifier should trace primarily to a Tier 1 document.

3.2 Document Map

sds/
├── Tier 1: System-Level
│   ├── sds-01-introduction.md          # This document
│   ├── 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
│
├── Tier 2: Domain Design
│   ├── domains/                        # Functional domains
│   │   ├── sds-domain-kitcfg.md
│   │   ├── sds-domain-notif.md
│   │   └── ...
│   └── rules/                          # Rules engine
│       ├── sds-rules-engine.md         # Framework overview
│       ├── sds-rules-combine-outcomes.md
│       └── ...
│
├── Tier 3: Reference
│   ├── reference/
│   │   ├── sds-ref-api.md
│   │   ├── sds-ref-database.md
│   │   ├── sds-ref-config.md
│   │   └── sds-ref-glossary.md
│
└── Tier 4: Reference
    └── sds-master-index.md             # Document index

---

4. How to Use This SDS

4.1 For Understanding a Domain

1. Start with the relevant domain document in domains/ or rules/
2. Read the Overview for purpose and requirements covered
3. Read the Component Architecture for structure
4. Read the Behavioral Design for algorithms and logic
5. Use Implementation Mapping to find code

4.2 For Tracing a Requirement

1. Find the REQ-* in the domain document's Requirements Covered table
2. Check the Implementation Mapping section for design sections and code paths
3. For full traceability, consult the Traceability Matrix

4.3 For Modifying the System

1. Read the relevant domain document completely
2. Understand the Design Decisions rationale
3. Check Dependencies for downstream impact
4. Update the domain document when making design changes

---

5. Domain Document Template

5.1 Template as Contract

The domain document template defines what sections must exist, not how much content each requires.

Sections are obligations to address a concern, not mandates for equal weight.

For simpler domains, the correct content may be:

• "Not applicable"
• "No owned entities"
• "Delegates to X"

Explicit absence is valuable design information.

Hard Rule: Sections exist to be discharged, not necessarily filled. Brevity is correct when it accurately constrains behavior. Reviewers should push back on unnecessary verbosity.

5.1.1 Domain Boundary Rule

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

5.2 Domain Character

Each domain document must declare its character in the header. This primes reader expectations and justifies section weight.

Character	Description	Typical Section Weight
Thin orchestration	Coordinates other domains, little owned logic	Light behavioral, heavy dependencies
Algorithmic	Complex decision logic, rules	Heavy behavioral, truth tables mandatory
Configuration-heavy	CRUD operations, validation, import/export	Heavy data design, entity ownership
Stateful	Manages persistent state transitions	State machines mandatory
Integration	External system communication	Heavy interface design, error handling

Header format:

> **Domain Character:** Thin orchestration

5.3 Section Obligations

Section	Obligation	Substantive When...
1. Overview	Mandatory	Always
2. Component Architecture	Mandatory	Always
3. Data Design	Conditional	Domain owns or significantly transforms data
4. Interface Design	Conditional	Domain exposes APIs or consumes external services
5. Behavioral Design	Conditional	Non-trivial logic exists
6. Error Handling	Conditional	Failure modes beyond "delegate to caller"
7. Configuration	Conditional	Configurable behavior exists
8. Implementation Mapping	Mandatory	Always
9. Design Decisions	Mandatory	Always (even if brief)
10. Related Documents	Mandatory	Always

Additional sections for rule domains:

Section	Obligation	Notes
Rule Summary Block	Mandatory	At top of §1, before detailed content
Decision Logic (Truth Tables)	Mandatory	Any rule with 2+ boolean/categorical conditions
Precedence	Mandatory	Rule execution order
Performance Considerations	Conditional	Non-obvious scaling concerns

5.3.1 Rule Summary Block (Mandatory for Rule Docs)

Every rule document must include a summary block at the top of §1 Overview. This allows reviewers to orient before diving into tables.

### 1.0 Rule Summary

| Property | Value |
|----------|-------|
| **Intent** | {1 paragraph: what this rule accomplishes} |
| **Inputs** | {list of decision inputs} |
| **Outputs** | {list of decision outputs} |
| **Precedence** | {where in execution order, e.g., "After WDCLS, before RQUAL"} |

This is mandatory because rule documents tend toward density. The summary provides a reviewer entry point.

5.4 Discharged Sections

When a section is not applicable or minimal, use these standard phrasings. This keeps brevity intentional and avoids stylistic drift.

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

---

6. Conventions

6.1 Pseudocode Structure

All algorithms use this structure:

Algorithm: {Name}

Inputs:
- {input_1}: {type/description}
- {input_2}: {type/description}

Outputs:
- {output}: {type/description}

Assumptions:
- {assumption_1}
- {assumption_2}

Steps:
1. {step}
2. {step}
   a. {sub-step}
   b. {sub-step}
3. {step}

Notes:
- {edge case handling}
- {non-obvious behavior}

Rationale:

• Expresses ordering and precedence (prose fails at this)
• Avoids implementation leakage (no PHP/TS syntax)
• Auditable and LLM-readable

6.2 Truth Tables

Any rule combining 2+ boolean or categorical conditions must include a truth table:

### Decision Logic

| Condition A | Condition B | Condition C | Result |
|-------------|-------------|-------------|--------|
| true | true | * | OUTCOME_1 |
| true | false | true | OUTCOME_2 |
| true | false | false | OUTCOME_3 |
| false | * | * | OUTCOME_4 |

**Precedence:** Rows evaluated top-to-bottom; first match wins.
**Default:** If no row matches, {default behavior}.
**Unreachable:** Row X is unreachable due to {constraint}.

Required annotations:

• Precedence rules (evaluation order)
• Default case (when nothing matches)
• Unreachable combinations (if any, with justification)

6.3 Diagrams

Use Mermaid for all diagrams. Standard diagram types:

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

Mark illustrative diagrams explicitly:

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

6.4 Cross-References

To SRS:

[SRS: domain.md](../../domain.md)

To other SDS documents:

[SDS: Architecture](../sds-03-architecture-overview.md)
[SDS: Related Domain](./sds-domain-other.md)

To reference material:

See [Database Reference](../reference/sds-ref-database.md#table-name) for full schema.
See [Configuration Reference](../reference/sds-ref-config.md#setting-name) for details.

6.5 Traceability Notation

In Requirements Covered tables:

| REQ ID | Title | Priority |
|--------|-------|----------|
| REQ-DOMAIN-001 | Requirement title | Must |

In Implementation Mapping sections:

| REQ ID | Design Section | Code Location |
|--------|----------------|---------------|
| REQ-DOMAIN-001 | §5.1 Algorithm Name | `path/to/file.php:function` |

---

7. Maintenance

7.1 When to Update

Update domain documents when:

• Requirements change (SRS update triggers SDS review)
• Implementation changes significantly
• Design decisions are revised
• New components are added

7.2 Change Process

1. Update the relevant domain document
2. Regenerate the traceability matrix: python3 docusaurus/scripts/generate-unified-traceability.py --render-md
3. Update related documents if dependencies change

7.3 Version History

Each document maintains its own Last Updated date in the header.

Major revisions are tracked in git commit history.

---

8. Terminology

Term	Definition
SDS	Software Design Specification (this document set)
SRS	Software Requirements Specification
Domain	A functional area of the system (e.g., NOTIF, KITCFG)
Tier 1	System-level documents (architecture, cross-cutting)
Tier 2	Domain design documents
Tier 3	Reference material
Tier 4	Traceability artifacts

See Glossary for complete terminology.

---

9. References

Document	Location	Purpose
SRS	output/srs/	Requirements source
SDD (Legacy)	output/sdd/	Predecessor documentation
IEEE 1016-1998	External	SDS standard reference