Overview

The purpose of this plan is to review a number of previously completed Platform Architecture, Solution Architecture, and Solution Design documents and create new templates for Solution Design and Platform Architecture documents.

Guidance

The Problem

We have a problem at the moment whereby when we conduct projects, there are conversations we have with the business around “use case specific” requirements, and then there are conversations we have with IT around “infrastructure specific” requirements. IT stakeholders are always the same groups of individuals (e.g. Security, Risk, Compliance, Architecture, etc.) and the business stakeholders are usually separate depending on the use case. The challenge is, if we have a single document for every use case, and the infrastructure specific requirements are essentially the same, we are just duplicating that infrastructure specific information every time we create a new use case document.

The Solution

Our approach to solve this problem is to create a Platform Architecture Document (for IT Stakeholders with infrastructure specific requirements) that can act as a foundational reference document for all Solution Design Documents (for Business and IT stakeholders with use case specific requirements). Additionally, it should be considered that often there is a need to separate business use case “Solution Design” information and use case “Business Case” information, which is something that this plan will investigate further (i.e. should we have a separate Opportunity Assessment template).

How does this work?

The high level definitions for these documents include the following:

1. Platform Architecture Document: Reference Architecture document that describes the infrastructure that gets provisioned, the integrations between systems, and the core functionality of the platform. This acts as a central reference point for all use cases that get built on top of the Platform. Architectural Impact Assessments are required every time a new use case is planned for deployment on top of the platform. This document serves as a central point for review for all IT stakeholders that are concerned with cyber security, risk and compliance, information classifications handled by the platform, integrations, architectural patterns, etc. This document does not include any business logic, only platform specific logic and logic specific to what the platform is capable of doing when it is used to serve a particular solution use case.
2. Solution Design Document: Use case specific documents that describes the problem and how the solution solves it, business logic specific to the use case, and an Architectural Impact Assessment for the use case which outlines what components and capabilities the use case leverages as well as any changes needed to the Platform Architecture so that it can support the use case. This document serves as the central point of review for business stakeholders seeking to confirm business logic and solution features / requirements, and provide insight as well for any IT stakeholders that wish to get an understanding of the use case.
3. Opportunity Assessment: A separate template that captures the “business case” aspects (problem statement, value proposition, stakeholder impact, cost-benefit) independently of the technical “solution design” aspects. This allows business stakeholders to review and approve the opportunity independently of the solution design details. Decision: Adopted — see Task 3 Decision.

Template Numbering

The templates follow a numbered convention to indicate document hierarchy:

• 001 - Platform Architecture (foundational, one per platform)
• 002 - Opportunity Assessment (business case per use case)
• 003 - Solution Design (technical design per use case)

Tasks

• Task 1 - Convert reference sources to markdown: Review each Reference Source document listed below and create a like-for-like markdown conversion of each document within this plan directory (docs/plans/01 Platform & Solution Architecture Document Templates/). Each converted document should faithfully reproduce the structure, headings, and content of the original. Tables should be converted to markdown tables. Where diagrams or images exist in the source, insert a placeholder noting [Diagram: description of diagram] (i.e. make sure to actually review contents of the diagram and create a ‘description of diagram’). Name each converted file to match the original filename but with a .md extension.
• Task 2 - Define segregation strategy: Using the converted markdown reference sources from Task 1, analyse each document and annotate/map which sections constitute “Platform Architecture” content vs. “Solution Design” content vs. “Opportunity Assessment / Business Case” content. Update this plan document with a new ## Segregation Strategy section that documents the mapping and rationale.
• Task 3 - Determine Opportunity Assessment template: Document the rationale for whether a separate 002 - Opportunity Assessment - [USE CASE NAME] template should be adopted in addition to the Platform Architecture and Solution Design templates. The template file already exists at .templates/documents/002 - Opportunity Assessment - [USE CASE NAME].md (currently empty) so this task is about determining its purpose, scope, and whether it should be kept, merged into Solution Design, or maintained as a standalone deliverable. Decision: Adopted as a separate template. See Segregation Strategy section.
• Task 4 - Create template content: Using the segregation strategy from Task 2, populate the currently empty template files with full template structures including headings, guidance notes, and placeholder content. These are new templates being created from scratch (the current files are empty).
• Task 5 - MECE analysis and template refinement: Conduct a comprehensive MECE (Mutually Exclusive, Collectively Exhaustive) analysis across all three templates to identify overlaps, gaps, ambiguities, and structural inconsistencies. Apply all fixes to the templates. See MECE Analysis section below.
• Task 6 - Test document creation: Create three populated test documents using the UniSC “Mandatory Requirements for Student Placements” use case, one for each template (001, 002, 003). Content sourced from the P001 SDD and P000 PA reference documents. See Test Documents section below.
• Task 7 - Final conformance review: Verify all three test documents conform to the updated templates. Assess section presence, section ordering, template guidance removal, table structure, content quality, and cross-references. See Conformance Review section below.

Reference Sources

• Squad - UniSC/P001 - Mandatory Reqs Student Placmts/P001 - Mandatory reqs for student placements - SDD.docx: This is a current document that we are working on which has raised the need for splitting up Solution Design and Platform Architecture type information into two separate documents. The reason for this is that the “Mandatory Reqs for Student Placmts” is a use case that will leverage the same foundational Platform Architecture as another set of use cases, of which all would require their own Solution Design document.
• Squad - UniSC/P001 - Mandatory Reqs Student Placmts/P000 - GenAI Platform Architecture.docx: This is the Platform Architecture document that was created for the UniSC engagement. It serves as the foundational platform reference for all UniSC use cases and is a strong example of what the Platform Architecture template should capture.
• Squad - AGL/AGL Phase 3/CMPL - Solution Architecture Document - v2.doc: This was a completed example of a “Platform Architecture” document that also happened to include some “Solution Design” document type information. When we worked with this client we also created a set of “Solution Component View” documents which essentially acted as “Solution Design” documents (see below).
• Squad - AGL/AGL Phase 3/CMPL - Solution Component Views - v1.docx: This is the “Solution Component View” document that acts as an aggregated “Solution Design” document for 5 different features (separated in the document by title prefixed Solution Component - [Feature Name]).

Templates

All template files have been created, populated, and refined through MECE analysis (Tasks 4–5):

• .templates/documents/001 - Platform Architecture - AI Accelerator.md (448 lines)
• .templates/documents/002 - Opportunity Assessment - [USE CASE NAME].md (275 lines)
• .templates/documents/003 - Solution Design - [USE CASE NAME].md (383 lines)

Segregation Strategy

This section documents the analysis and mapping of content from the four reference source documents into the three template categories: Platform Architecture (PA), Opportunity Assessment (OA), and Solution Design (SD).

Key Observations

1. P000 was poorly derived from P001. The Platform Architecture document (P000) was copied wholesale from the Solution Design Document (P001), retaining version history, contributors, approvers, and even the introduction still referencing “SDD”. Sections 3.2–3.6 in P000 contain pure use-case content (solution features, user stories, process flows, exceptions) that should not appear in a Platform Architecture document. Sections 2.3–2.8 contain AGL-specific content (AGL policies, Confluence links, Synapse migration references) that was accidentally mixed in from the CMPL project.

2. AGL’s “Views” structure is the strongest template precedent. The CMPL-SAD organises content into distinct horizontal views: Business View, Integration View, Infrastructure View, Information View, Security View, and Support View. Each “view” maps to a specific IT stakeholder concern. This structure should be adopted for the 001 Platform Architecture template.

3. The Architectural Impact Assessment (AIA) concept has two direct precedents:

   • CMPL-SAD’s “Solution impacts” table categorises components as EXISTING / CHANGE / NEW / DECOMMISSIONED
   • CMPL-SCV’s “Impacts to other architecture views” table maps use-case impact to each horizontal view (Solution overview, Information view, Integration view, Infrastructure view, Security view, Support view)
   • The AIA in the 003 Solution Design template should combine both into the bridge between SD and PA documents.

4. Content requiring splitting between templates. Several section types contain elements belonging to multiple templates: Component Architecture, Integration Architecture/Interfaces, Scope, Business Applications, Information Classification, Solution Technologies, Non-Functional Requirements, and Assumptions.

5. Opportunity Assessment content exists across documents but is embedded within other sections: Background (P001 2.1), Objectives/Phases (CMPL-SAD), Current State (CMPL-SAD), high-level value stream metrics (P001 2.5), and workload/SLA quantification from the Functional Requirements Questionnaire (P001 2.4).

Recommended Template Structures

001 - Platform Architecture

Adopts the AGL “Views” structure as horizontal concerns, with a Business View providing platform context and an explicit Use Case Register for tracking all solutions built on the platform:

1. Document Control (version, contributors, approvers)
2. Introduction (platform purpose and document scope)
3. Business View (background, objectives, scope, dependencies, assumptions, risks, technical debt, references)
4. Platform Overview (platform description, platform capabilities, solution impacts table, architecture decisions, guardrails)
5. Use Case Register (table linking to all SD and OA documents built on this platform)
6. Integration View (integration patterns, standard interfaces, middleware)
7. Infrastructure View (deployment architecture, networking, environments, licensing, backup/recovery)
8. Information View (data classification, system of record, data governance)
9. Security View (information classification, authentication/authorisation, security controls, auditing)
10. Support View (service classification, support model, operational procedures)
11. Appendix

002 - Opportunity Assessment

Captures the business case independently of technical solution design:

1. Document Control
2. Executive Summary
3. Background and Context (business context, current state, problem statement)
4. Objectives (goals, success metrics, phased approach if applicable)
5. Stakeholder Analysis (stakeholder groups, impact assessment, RACI)
6. Value Proposition (quantified benefits, business process value stream, workload/SLA analysis)
7. Scope (in scope / out of scope from a business perspective)
8. Cost-Benefit Analysis (estimated costs, expected savings, ROI timeline)
9. Risks and Assumptions (business risks, assumptions with consequences if invalid)
10. Recommendation (go/no-go, recommended approach, next steps)
11. Appendix

003 - Solution Design

Covers use-case-specific technical design with an Architectural Impact Assessment that bridges back to the PA:

1. Document Control (version, contributors, approvers)
2. Introduction (solution purpose, relationship to PA document, document scope)
3. Business Process (background reference to OA, detailed process description, business applications used, process flows)
4. Solution Overview (solution description, solution features/epics, user stories, solution process flows, solution exceptions)
5. Solution Component Views (per-feature deep dives with business view, current state, solution overview, requirements)
6. Architectural Impact Assessment (component impact table [EXISTING/CHANGE/NEW/DECOMMISSIONED], impacts to PA horizontal views [Integration, Infrastructure, Information, Security, Support], use-case specific integration interfaces, use-case specific NFRs, use-case specific technology choices and ADRs)
7. Appendix (process details, screenshots, references, assumptions)

Task 3 Decision: Opportunity Assessment Template

Decision: Adopt the Opportunity Assessment as a separate template (002).

Rationale:

1. Clear content separation exists. The analysis above identifies 8 distinct content areas that are business-case oriented (background, objectives, current state, value stream metrics, workload quantification, stakeholder impact, cost considerations, high-level problem statement). These are currently scattered across the Solution Design and Platform Architecture documents with no consistent home.

2. Different audiences and approval workflows. Business stakeholders (process owners, executives) need to review and approve the opportunity independently of technical solution design. The OA serves as the “should we do this?” document, while the SD serves as the “how do we do this?” document. Combining them forces business stakeholders to wade through technical content they don’t need to approve.

3. Different lifecycle timing. The Opportunity Assessment is typically created before the Solution Design — it justifies starting the design work. Keeping them separate allows the OA to be approved as a gate before investing effort in the SD.

4. Precedent in reference documents. The CMPL-SAD’s phased objectives section (POV → Detailed Design → Production Deployment) and the P001 Functional Requirements Questionnaire both contain OA-type content that was awkwardly embedded in technical documents. A dedicated template prevents this.

5. Lightweight by design. The OA template should be concise — it captures just enough business context to justify the investment and scope the use case, without duplicating the detailed technical content that belongs in the SD.

If not needed for a particular engagement, the OA template can simply be omitted and its key content (background, objectives) can be briefly summarised in the SD’s Introduction section instead. The template numbering remains stable regardless.

Success Criteria

• All reference source documents have been converted to markdown and are available in this plan’s directory for analysis
• The segregation strategy clearly maps which types of content belong in each template, with rationale documented
• A decision has been made and documented on whether to adopt the Opportunity Assessment template
• Each template contains a complete structure with headings, guidance notes, and placeholder content that can be used immediately for a new client engagement
• The templates can be validated by taking an existing completed document (e.g. the UniSC SDD) and confirming that its content can be cleanly split across the Platform Architecture and Solution Design templates without duplication or gaps
• A MECE analysis has been conducted to ensure no overlaps, gaps, or ambiguities exist between the three templates
• Test documents populated with real UniSC content demonstrate the templates work end-to-end
• A final conformance review confirms all test documents pass against their respective templates

Validation: P001 Content Split Across Templates

This section validates that the content of the UniSC SDD (P001 — Mandatory Requirements for Student Placements) can be cleanly split across the three templates without duplication or gaps.

MECE Analysis

A comprehensive MECE (Mutually Exclusive, Collectively Exhaustive) analysis was conducted across all three templates after Task 4 (initial template creation). The analysis identified 30 issues across four categories: Overlaps, Gaps, Ambiguities, and Structural inconsistencies. All 30 issues were resolved and the fixes applied to the templates (Task 5).

Overlap Issues (9 — all resolved)

Gap Issues (9 — all resolved)

Ambiguity Issues (5 — all resolved)

Structural Issues (7 — all resolved)

Conclusion

All three templates and their corresponding test documents have been validated. The template system successfully separates infrastructure-specific content (001 PA) from business-case content (002 OA) and use-case-specific technical content (003 SD), with the Architectural Impact Assessment in 003 providing a clear bridge back to the Platform Architecture. The MECE analysis ensures no content overlaps or gaps exist between the three templates.