Appearance
WS 2 — Target State Architecture
| Duration | 3 weeks |
| Objective | Synthesize the client's existing architectural direction, technology decisions and business requirements into a cohesive target state architecture for the future Unified Portal |
| Deliverables | D2.1 · D2.2 · D2.3 · D2.4 |
Tasks
| ID | Activity (SOW Schedule "A") | Output | Status |
|---|---|---|---|
| WS2-A1 | Establish and document guiding principles and design considerations — scalability, security, integration, reuse, maintainability, extensibility | architecture/guiding-principles.md | ⚪ |
| WS2-A2 | Review existing target state artifacts, technology decisions and supporting documentation | Carried from WS 1 | 🟡 |
| WS2-A3 | Define and document the target state architecture across all named domains | architecture/ + diagrams | ⚪ |
| WS2-A4 | Identify architectural decisions, trade-offs, dependencies, constraints and areas requiring client decision or validation | Decision log · open questions | 🟡 |
| WS2-A5 | Create the executive-level target state architecture presentation | D2.2 | ⚪ |
| WS2-A6 | Conduct working sessions and alignment discussions with lines of business IT and leadership | Session notes · D2.3 · diagram versions | ⚪ |
| WS2-A7 | Conduct the final architecture review and executive readout | Readout record · confirmed decisions | ⚪ |
WS2-A3 domain sub-tasks
One per SOW-named domain. Each produces a page in docs/architecture/ and, where structure is better carried visually, a diagram.
| ID | Domain | Page | Diagram | Status |
|---|---|---|---|---|
| WS2-A3a | Vision and objectives | vision-and-objectives.md | — | ⚪ |
| WS2-A3b | Target state overview | overview.md | Target state architecture | ⚪ |
| WS2-A3c | Portal architecture | portal.md | Homepage composition (sequence) | ⚪ |
| WS2-A3d | Application and platform | application-and-platform.md | — | ⚪ |
| WS2-A3e | Integration and API | integration-and-api.md | Integration topology | ⚪ |
| WS2-A3f | Data architecture | data.md | Data and consent flow | ⚪ |
| WS2-A3g | Identity and access management | identity-and-access.md | Identity and entitlement (sequence) | ⚪ |
| WS2-A3h | Security | security.md | — | ⚪ |
| WS2-A3i | Infrastructure | infrastructure.md | — | ⚪ |
| WS2-A3j | Content management | content-management.md | — | ⚪ |
| WS2-A3k | Analytics | analytics.md | — | ⚪ |
| WS2-A3l | Architectural design patterns | design-patterns.md | — | ⚪ |
| WS2-A3m | Risks and considerations | risks-and-considerations.md | — | ⚪ |
Working notes
Where to start
Not at the top of the list. Three domains carry disproportionate weight, and the rest are easier to write once they are settled:
Identity and access (A3g) — because the authorization question is the most consequential unresolved item in the entire client material. Does customer identity propagate to the BU Data APIs, or does service-principal fan-out stand with compensating controls? Everything about the integration layer, the cache design and the data classification follows from that answer.
Integration and API (A3e) — because the composition pattern decision lives here, and because the API landscape gives us an unusually solid evidence base to reason from.
Portal architecture (A3c) — because it is where the MVP and the target state have to be reconciled, and because the experience map has already done the zone-level work.
Decisions that will need an ADR
Provisional. Each needs alternatives recorded and the reason the alternatives lost — on this engagement the trade-off is the deliverable, and a decision without its alternatives cannot be defended in an executive readout.
Where a Recommendation is named, the position is already argued in recommendations/ and the ADR follows if the client accepts it.
| Likely ADR | The choice | Recommendation |
|---|---|---|
| Composition pattern | Single BFF · per-LOB micro-BFFs · federated GraphQL — and the trigger that changes it | R3 constrains it |
| Authorization model | Customer-identity propagation (token exchange / on-behalf-of) vs service-principal fan-out with compensating controls | R1 |
| Entitlement source | Manual BU Mapping Service vs resolved enterprise relationship (ECID) | — |
| Aggregation boundary | Where cross-BU aggregation happens — UI, BFF, integration layer, or a projection | R3 |
| Cache design and classification | What is cached, keyed how, classified as what, for how long | — |
| Degradation contract | What the customer sees when a tile, a BU or the BFF fails | R2 |
| Fallback route | Whether the legacy Product Selection page survives as a bypass, and for how long | R2 |
| MVP forward-compatibility | Whether MVP contracts must be ECID-swap-safe, and what that costs | — |
The stakeholder sessions
A6 is where the work gets validated or does not. Two mechanical notes that are easy to skip and expensive to skip:
- Cut a diagram version at each session, labelled with something a reader recognises ("WS2 identity session") and carrying the feedback that drove the revision. The timeline at
/diagrams/history/<slug>then shows what changed and whether it was structural or cosmetic. Reconstructing this afterwards is not possible — snapshots are immutable, and invented history makes the deltas lie. - Record disagreement as disagreement. D2.3 is more credible for containing unresolved items than for reporting universal alignment, and the material already contains a live dispute between two client functions.
The bar for our diagrams
Domain K of the segment assessment assesses the ADS's architecture diagram as a controlled document and finds nine defects: wrong hosting platform, no edge tier or WAF drawn, no public/private boundaries marked, components missing from a read path, components not classified new versus existing against the legend, connectors with no protocol, authentication or data classification, business units unnamed, and no depiction of the dark-launch routing mechanism.
Read as a specification, that is a good one. The same reviewers will read ours.