Appearance
D2.1 · Target state architecture document
| Work stream | WS 2 — Target State Architecture |
| SOW source | Schedule "A", WS 2 deliverables, first bullet |
| Status | ⚪ Not started |
| Indicative window | Weeks 2–4 |
The largest deliverable in the engagement, and the one the other two work streams hang off.
What the SOW asks for
Target state architecture document which includes: architecture vision and objectives · guiding principles · target state architecture overview · portal architecture · application and platform architecture · integration architecture · data architecture considerations · identity and security considerations · key architectural decisions and rationale · risks and considerations
WS 2 activity 3 enumerates the domains to be considered more finely than the deliverable list does: portal architecture, application and platform architecture, integration and API architecture, data architecture, identity and access management, architectural design patterns, security, infrastructure, content management, and analytics.
Structure and where each section lives
The document is assembled from docs/architecture/. One page per domain, so sections can be drafted, reviewed and revised independently.
| SOW section | Page | Status |
|---|---|---|
| Architecture vision and objectives | architecture/vision-and-objectives.md | ⚪ |
| Guiding principles | architecture/guiding-principles.md | ⚪ |
| Target state architecture overview | architecture/overview.md | ⚪ |
| Portal architecture | architecture/portal.md | ⚪ |
| Application and platform architecture | architecture/application-and-platform.md | ⚪ |
| Integration and API architecture | architecture/integration-and-api.md | ⚪ |
| Data architecture considerations | architecture/data.md | ⚪ |
| Identity and access management | architecture/identity-and-access.md | ⚪ |
| Security | architecture/security.md | ⚪ |
| Infrastructure | architecture/infrastructure.md | ⚪ |
| Content management | architecture/content-management.md | ⚪ |
| Analytics | architecture/analytics.md | ⚪ |
| Architectural design patterns | architecture/design-patterns.md | ⚪ |
| Key architectural decisions and rationale | Decision log | 🟡 |
| Risks and considerations | architecture/risks-and-considerations.md | ⚪ |
See the architecture overview for the current index of these pages.
Decisions deliberately live in the decision log rather than inline. The SOW makes decisions and rationale a named deliverable and requires the alternatives to be recorded; an ADR per decision keeps the trade-off intact, and the document references them rather than summarising them into uselessness.
Diagrams
Diagrams carry structure, prose carries rationale, and neither restates the other. Planned:
| Diagram | Type | Purpose |
|---|---|---|
| Target state architecture | architecture | The headline artifact — components, boundaries, ownership |
| Current state / as-is context | architecture | Where we are starting from |
| Integration and API topology | architecture or dataflow | Gateway estate, fan-out, orchestration |
| Identity and access | sequence | Login, token exchange, entitlement decision |
| Homepage composition | sequence | A single page load end to end |
| Data and consent flow | dataflow | What moves where, under whose authority |
None are authored yet. The only diagram in the repository is the starter sketch — a placeholder proving the toolchain, where every node is a guess. It is registered as not client-safe and must not be shown.
Each diagram gets a launcher page at /diagrams/<slug> and, once versions are cut, a timeline at /diagrams/history/<slug> showing what changed after which working session and why. That is directly useful for this deliverable: WS 2 activity 6 is a sequence of alignment sessions, and being able to show a stakeholder exactly what their feedback changed is worth a great deal in activity 7's executive readout.
The bar these diagrams have to clear
Domain K of the segment assessment assesses the ADS's architecture diagram as a controlled document and finds it wanting on nine counts: it does not name the actual hosting platform, does not draw the edge tier or WAF or any public/private boundary, omits components on a read path, does not classify components as new versus existing against its own legend, and defines no connector semantics — protocol, authentication, data classification. Our diagrams will be read by the same reviewers. That is a specification, and we should treat it as one when authoring in diagrams/src/.
What the target state has to answer
Beyond the SOW's own list, the client material sets a concrete agenda. These are the questions a target state document will be judged on:
- Where does the authorization decision live once display is aggregated away from the product portals? Customer-identity propagation versus service-principal fan-out with compensating controls is the single most consequential open technical question in the material.
- What is the composition pattern, and what triggers a change of pattern? Single BFF, per-LOB micro-BFFs, or federated GraphQL — the options deck frames the choice and asks for a written sunset date or migration trigger.
- What is the relationship between MVP and target state? The strategy document's Phase 2 is precisely what MVP1 excludes. Are the MVP's contracts forward-compatible with an ECID swap?
- How does the experience degrade? Thirteen hard dependencies on the critical path with no fallback route is the finding with the widest blast radius.
- Who owns the shared runtime? Four components with no natural business-unit home. We surface this as an architectural dependency; designing the operating model is out of scope.
- What is the classification of the aggregate? An aggregate of a customer's whole position is more sensitive than any single source record, and nothing in the material performs that re-classification.
Acceptance
Written acceptance from Manulife's project manager per SOW §5, following the final architecture review and executive readout (WS 2 activity 7).