Recommended Reading Order

This is the path we recommend for your first pass of the audit. It is ordered to move from engagement context, through the architectural spine, into the engineering practices that govern how the system is built - and total read-time is just under 2 hours. Once you have completed these pages, the rest of the corpus is reference material: navigate by sidebar from any of them, and use the dimension-driven index below to drop into specific areas as findings emerge.

The Path

1. Welcome to the EY Review (5 min)

Link: /ey-review/What this answers: Why this build exists, what is in scope, and who at Olly owns the conversation. Why now: Anchors the engagement before you touch any architecture content. Maps to: Documentation maturity.

2. Review Framework (10 min)

Link: /ey-review/frameworkWhat this answers: The seven dimensions you are assessing, the severity rubric, and the finding-register format expected as deliverable. Why now: Every subsequent page should be read with these seven dimensions in mind. Maps to: Documentation maturity, Regulatory posture.

3. Scope, NDA, Watermarking (5 min)

Link: /ey-review/scopeWhat this answers: What is in and out of scope for the review, the NDA position, and how per-page watermark hashes work for traceability. Why now: Closes the engagement-framing trio before you enter the architecture. Maps to: Documentation maturity, Regulatory posture.

4. C4 L1 Business Landscape (8 min)

Link: /architecture/system-contextWhat this answers: The actors, regulators, and external systems Olly sits between - the business landscape view. Why now: You need the outside-in picture before you read containers or processes. Maps to: Layering, Integration completeness, Regulatory posture.

5. C4 L2 Container Views (10 min)

Link: /architecture/containersWhat this answers: The deployable containers (services, apps, datastores, gateways) and the trust boundaries between them. Why now: Translates the L1 landscape into the runtime topology you will be testing for layering and integration completeness. Maps to: Layering, Engineering patterns, Integration completeness.

6. Business Process Catalogue (8 min)

Link: /architecture/business-processesWhat this answers: The enumerated business processes Olly claims to support, in the language of the business. Why now: Pairs with the next page to convert "what we say we do" into "what we have actually built." Maps to: Use-case completeness, Documentation maturity.

7. Domain Model Overview (7 min)

Link: /domain/What this answers: The domain concepts (policy, claim, member, party, eligibility, care, consent) and how they relate. Why now: Grounds the process catalogue in the data model you will see referenced from every later page. Maps to: Layering, Use-case completeness, Documentation maturity.

8. Kafka Event Catalog (7 min)

Link: /data/eventsWhat this answers: Every domain event Olly emits - topic, producer, consumers, payload contract, evolution policy. Why now: The asynchronous half of the integration surface. For an architecture audit this is the most concrete contract artefact in the corpus - every cross-service boundary either lives here or in the REST gateway. Maps to: API design, Integration completeness, Use-case completeness.

9. InFORM Process Coverage Map (10 min)

Link: /architecture/process-coverageWhat this answers: Honest status of every InFORM business process: done, partial, pending, or out of scope. Why now: This is the highest-leverage page in the build - it tells you where to invest the rest of your reading and where the gaps already are. Maps to: Use-case completeness, Documentation maturity, Regulatory posture.

10. Design Principles (8 min)

Link: /architecture/practices/design-principlesWhat this answers: The seven invariants every service is expected to honour. Why now: Sets the rubric for the practice pages that follow; tells you what "good" looks like in this codebase. Maps to: Engineering patterns, Layering, API design.

11. Database Strategy (7 min)

Link: /architecture/practices/databaseWhat this answers: How Olly handles persistence, schema ownership, migrations, and the database-per-service position. Why now: Engineering-pattern depth on the most consequential layer. Maps to: Engineering patterns, Layering, Integration completeness.

12. Change Control & Deployment (7 min)

Link: /architecture/practices/change-controlWhat this answers: How code reaches production: review, CI, environment promotion, rollback. Why now: Regulators (FCA SYSC, DSPT) will probe this; you should see it before you file regulatory findings. Maps to: Engineering patterns, Regulatory posture, Documentation maturity.

13. Observability & Telemetry (6 min)

Link: /architecture/practices/observabilityWhat this answers: What is traced, logged, and measured, and how that evidence is retained. Why now: Observability underpins Consumer Duty evidence and incident response - it is a regulatory artefact as much as an engineering one. Maps to: Engineering patterns, Regulatory posture, Integration completeness.

14. Data Protection (6 min)

Link: /architecture/data-protectionWhat this answers: How PHI is handled - encryption at rest, consent capture, Article 17 erasure, audit retention. Why now: The regulatory-posture page. Article 9 / NHS DSPT / GDPR concerns all crystallise here; read it before forming a regulatory-posture verdict. Maps to: Regulatory posture, Layering, Documentation maturity.

15. AI Strategy (7 min)

Link: /architecture/practices/aiWhat this answers: Where AI is used (triage being the principal example), how it is governed, and how it interacts with the regulated path. Why now: AI sits at the intersection of clinical (Article 9), conduct (Consumer Duty), and engineering pattern concerns - it deserves a dedicated read. Maps to: Engineering patterns, Regulatory posture, Use-case completeness.

16. Coding Guidelines (6 min)

Link: /arch/coding-guidelines.htmlWhat this answers: The repo-level coding conventions that the practice pages assume. Why now: Closes the engineering-pattern loop with the on-the-ground rules engineers actually follow. Maps to: Engineering patterns, API design, Documentation maturity.

17. Exit - File Findings Against the Framework (3 min)

Link: /ey-review/frameworkWhat this answers: The deliverable specification (finding register columns, severity rubric, executive summary structure). Why now: Re-anchors you in the deliverable format before you start writing findings. Maps to: Documentation maturity.

By Dimension

1. API design

• C4 L2 Container Views - shows the inter-service surface where API contracts meet.
• Design Principles - the invariants APIs are expected to honour.
• Kafka Event Catalog - the event-driven half of the API surface, with payload schemas.
• Coding Guidelines - naming, versioning, and error-envelope conventions.

2. Engineering patterns

• Design Principles - the seven invariants.
• Database Strategy - persistence patterns and schema ownership.
• Change Control & Deployment - how code flows to production.
• 2PC / Outbox - the canonical transactional-messaging pattern.

3. Layering

• C4 L1 Business Landscape - the outside boundary.
• C4 L2 Container Views - runtime layering.
• Service Map - service-level decomposition.
• Domain Model Overview - domain layer separate from transport and storage.

4. Integration completeness

• Event Flow - the asynchronous integration spine.
• Kafka Event Catalog - versioned event contracts.
• Data Protection - PHI handling, consent, erasure, audit.
• Build vs Buy - which integrations are bought (Stripe, Novu, Mirth) and the rationale.

5. Use-case completeness

• Business Process Catalogue - what the business says it does.
• InFORM Process Coverage Map - what is actually built.
• Claims Lifecycle - a worked end-to-end capability.
• AI Triage - the clinical-to-care end-to-end flow.

6. Documentation maturity

• Welcome to the EY Review - engagement framing.
• Review Framework - deliverable contract.
• Designs overview - decision records.
• Ontology & Catalog overview - glossary discipline.

7. Regulatory posture

• Consent & GDPR - Article 9 lawful basis and consent capture.
• Data Protection - PHI custody, encryption, retention, audit trails.
• AI Strategy - AI governance against Consumer Duty and clinical safety.
• Observability & Telemetry - evidence retention for regulator inspection.

How to file findings

Findings are filed against the seven dimensions in the Review Framework. Use the row format defined there: one row per finding with dimension, severity, page_url, finding, suggested_action, and references. Every page in this build is watermarked with a per-page hash visible in the footer - quote it alongside the page URL in the page_url column so we can trace which build the finding originated from. Aim for evidence-grounded findings: one issue, one severity, one page of origin.