Decision 01: Three-Document Separation (PAD, OAD, SDD)
Status
Accepted
Date
2026-02-18
Context
When documenting AI platform projects, a single monolithic architecture document becomes unwieldy as the number of use cases grows. IT stakeholder concerns (security, networking, infrastructure) are platform-wide and apply to every use case, but they were being duplicated across individual solution design documents. This led to inconsistency, maintenance burden, and difficulty for IT reviewers who had to read every use case document to understand platform-level concerns.
The original project (UniSC PA / P000) suffered from mixed content — platform-level and use-case-level concerns were interleaved in a single document, making it difficult to determine which sections applied broadly versus which were use-case-specific.
Decision
Separate architecture documentation into three document types with clear boundaries:
-
PAD (Platform Architecture Document) — One per platform. Contains all platform-level concerns: infrastructure, networking, security, integration patterns, environment strategy, monitoring, non-functional requirement baselines, and the Use Case Register.
-
OAD (Opportunity Assessment Document) — One per use case (optional). Contains the business case: value proposition, cost-benefit analysis, stakeholder analysis, and go/no-go recommendation. Intended for business stakeholders making investment decisions.
-
SDD (Solution Design Document) — One or more per use case. Contains use-case-specific content: business process detail, solution features, user stories, component views, and the Architectural Impact Assessment (AIA) that bridges back to the PAD.
Rationale
- Eliminates duplication: Platform-level concerns (networking, security, infrastructure) are documented once in the PAD and referenced by all SDDs, rather than duplicated in each.
- Right audience, right document: IT security reviewers read the PAD; business stakeholders read the OAD; solution teams read the SDD.
- Scalable: Adding a new use case requires creating an OAD and SDD, not modifying the core platform documentation (except for the Use Case Register and any component changes identified in the AIA).
- MECE structure: A comprehensive analysis (30 issues) was conducted to ensure no content gaps or overlaps between the three document types.
Consequences
- Authors must understand which content belongs in which document — the guidance text in each template helps with this.
- Cross-references between documents are necessary (addressed by Decision 03).
- The PAD must be maintained as a living document — updated whenever a new use case’s AIA identifies platform changes.
- The OAD is optional, which means the SDD must contain sufficient business context when no OAD exists.