Document Template System — User Guide

This directory contains the templates for the three-document architecture documentation system: PAD, OAD, and SDD. This README explains how the system works, when to use each document type, and the conventions that keep the document set consistent.

Document Types

Document Hierarchy

PAD (Platform — foundation)
 ├── OAD (Use Case A — business case)
 │    └── SDD (Use Case A — technical design)
 ├── OAD (Use Case B — business case)
 │    ├── SDD (Use Case B — technical design — Solution 1)
 │    └── SDD (Use Case B — technical design — Solution 2)
 └── SDD (Use Case C — technical design, no OAD)

The PAD is the foundation. Every use case has at least one SDD. The OAD is optional — skip it for use cases with pre-approved funding or low business complexity, and note “N/A” in the PAD’s Use Case Register.

Naming Convention

Files follow a consistent naming convention using em dash (–) separators between the project code, descriptive code, and document type suffix:

Key Principles

• PROJECT CODE is the initiative or project identifier (e.g. CMPL, USC)
• AI PLATFORM CODE describes the platform (e.g. GenAI Platform)
• USE CASE CODE describes the use case (e.g. Customer Complaints, Billing Accuracy)
• The document type suffix (PAD, OAD, SDD) appears at the end, after a dash separator
• Related documents for the same use case group together naturally because they share the same project and use case code prefix

Example: Project Filenames

CMPL – GenAI Platform – PAD.md
CMPL – Customer Complaints – OAD.md
CMPL – Customer Complaints – SDD.md
CMPL – Customer Complaints – SDD – Fact Summary.md    (if multiple SDDs needed)
CMPL – Billing Accuracy – OAD.md                       (second use case)
CMPL – Billing Accuracy – SDD.md

Notice how all “Customer Complaints” documents group together in a file explorer, and the PAD is easily identifiable by its platform-level name.

Cross-Reference Convention

Cross-references use Obsidian link syntax for navigable, resilient links:

In-Document References

Use [[#heading-text|Heading Text]] to link to a section within the same document:

See [[#62-network-architecture|6.2 Network Architecture]] for the full network topology.
Refer to [[#35-guardrails-and-compliance|3.5 Guardrails and Compliance]] for compliance details.
As registered in the [[#4-use-case-register|4 Use Case Register]].

Cross-Document References

Use [[Document Name#section|Section]] to link to a section in another document. For templates, use the generic filename pattern as a placeholder:

Each SDD includes an Architectural Impact Assessment ([[PROJECT CODE – USE CASE CODE – SDD#5-architectural-impact-assessment|5 Architectural Impact Assessment]]).
Use case role mappings are documented in the respective [[PROJECT CODE – USE CASE CODE – SDD|SDDs]].
Use-case-specific cost analysis belongs in the [[PROJECT CODE – USE CASE CODE – OAD|OAD]].

For project-specific documents (e.g. the ACU PAD), use the actual project code:

Refer to [[ACU – USE CASE CODE – SDD#5-architectural-impact-assessment|5 Architectural Impact Assessment]].

Display Text (Pipe Syntax)

Use the pipe | to provide display text that differs from the link target:

[[PROJECT CODE – USE CASE CODE – SDD|SDDs]]   → renders as "SDDs"
[[PROJECT CODE – USE CASE CODE – OAD|OAD]]     → renders as "OAD"

Rules:

• Use heading text rather than section numbers alone for resilience against renumbering
• In-document links: [[#heading-text|Heading Text]]
• Cross-document links: [[Document Name#section-heading|Section Heading]]
• Use pipe syntax [[target|display text]] when the link target differs from desired display text
• For templates, use PROJECT CODE as a generic placeholder in cross-document links
• For client documents, use the actual project code (e.g. ACU)

How to Use the Templates

Starting a New Project

1. Copy the PAD template and rename it: PROJECT CODE – AI PLATFORM CODE – PAD.md
2. Populate the PAD with platform-level content (infrastructure, networking, security, integration patterns, NFR baselines)
3. For each use case:
   • If a business case is needed: copy the OAD template → PROJECT CODE – USE CASE CODE – OAD.md
   • Copy the SDD template → PROJECT CODE – USE CASE CODE – SDD.md
   • If the use case requires multiple SDDs, append a solution code: – SOLUTION CODE
4. Register the use case in the PAD’s Use Case Register (§4)

Populating a Template

Each template includes:

• A “How to Use This Template” preamble at the top with instructions
• Guidance text in blockquote format (>) — replace or remove once the section is populated
• [Bracketed placeholders] — replace with project-specific content
• [Diagram: ...] placeholders — replace with actual diagrams (recommended tools: draw.io, Mermaid, Lucidchart, Visio)
• Example tables showing the expected column structure — add rows as needed

The Architectural Impact Assessment (AIA)

The AIA (SDD §5) is the critical bridge between an SDD and the PAD. When an SDD is approved:

1. Update the PAD’s Solution Technologies table (PAD §3.3.2) with any CHANGE or NEW items
2. Update the PAD’s Use Case Register (PAD §4) with the new use case
3. Update any other PAD sections identified as impacted in the AIA’s “Impacts to Platform Architecture Views” table

Template Directory Structure

docs/templates/documents/
├── PROJECT CODE – AI PLATFORM CODE – PAD.md      (PAD template)
├── PROJECT CODE – USE CASE CODE – OAD.md          (OAD template)
├── PROJECT CODE – USE CASE CODE – SDD.md          (SDD template)
└── README.md                                      (this file)

Key Design Decisions

The design decisions behind this template system are formally documented as decisions in the Technology Guild Decisions directory: