Target State Architecture: Household Consumables Demand Orchestration Platform

v0.7 DRAFT · Status: For ARB review · Owner: Principal Enterprise Architect, Office of the CTO · Contributors: TBC (delivery)

Executive summary

The stakeholder asked for "a shared shopping list for me and my partner". It is regrettable that the requirement was worded as though it were small. What the household needs is Demand-Signal-as-a-Platform: capturing, reconciling and fulfilling household intent across two concurrent, unsynchronised writers who have each, independently, bought oat milk.

Non-functional requirements

Guiding principles

1. Cloud-agnostic by default.
2. Event-first. Milk is an event, not a row.
3. No tactical solutions.
4. Humans are read-only.
5. Every item has an owner, and the owner is never the person who finished it.

Logical architecture

• Intent Capture Service: accepts a claim that something is needed. It does not believe the claim.
• Item Normalisation Service: resolves "milk", "Milk", "the milk" and "MILK!!" to one SKU.
• Duplicate Intent Arbitration Service: decides who added the eggs first. Consistency is eventual. The argument is immediate.
• List Projection Service: the CQRS read model, which is to say the list. It is not authoritative.
• Fulfilment Saga Orchestrator: runs InBasket → Bought, with the compensating step ReturnedToShelf.
• Notification Service: calls the Partner Presence Service.
• Partner Presence Service: calls the Notification Service.

Diagram

flowchart LR
  H["Legacy (do not touch): Stakeholder + Partner"]
  subgraph EU["eu-west-1 (primary, active)"]
    BFF1["Mobile BFF: Stakeholder"]
    BFF2["Mobile BFF: Partner"]
    GW["Kong API Gateway"]
    KC["Keycloak realm: household"]
    IC["Intent Capture Service"]
    NORM["Item Normalisation Service"]
    K["Kafka: household.intent.v1 (64 partitions)"]
    FL["Flink: dedup window (event-time)"]
    ARB["Duplicate Intent Arbitration Service"]
    PROJ["List Projection Service (CQRS read)"]
    PG["PostgreSQL (outbox)"]
    RD["Redis: list cache"]
    ES["Elasticsearch: do-we-have-any search"]
    T["Temporal: Fulfilment Saga"]
    NS["Notification Service"]
    PP["Partner Presence Service"]
    V["Vault"]
    OBS["Prometheus + Grafana + Jaeger"]
  end
  subgraph US["us-east-1 (active-active)"]
    KUS["Kafka replica"]
  end
  AI["Future: AI Layer (predicts milk)"]
  BC["Future: Blockchain (paused)"]

  H -->|"mTLS"| BFF1
  H -->|"mTLS"| BFF2
  BFF1 --> GW
  BFF2 --> GW
  GW -->|"OIDC"| KC
  GW -->|"gRPC"| IC
  IC -->|"gRPC"| NORM
  NORM -->|"async (eventually)"| K
  K --> FL
  FL --> ARB
  ARB -->|"async (eventually)"| K
  K --> PROJ
  PROJ --> PG
  PG -->|"outbox relay"| K
  PROJ --> RD
  PROJ --> ES
  K --> T
  T --> NS
  NS -->|"gRPC"| PP
  PP -->|"gRPC"| NS
  NS -->|"push"| H
  K -->|"MirrorMaker 2"| KUS
  KUS -->|"MirrorMaker 2"| K
  V -.-> GW
  OBS -.-> K
  K -.->|"replay"| AI
  AI -.-> BC

Legend: blue is strategic, amber is tactical (deprecated), grey is owned by delivery, and red is the stakeholder.

Technology choices

Rejected alternatives

• A shared note in a phone notes app. The stakeholder proposed this. It is a very natural first instinct, as most instincts are. It has no audit trail, no SLO, no RBAC and no future. It is also already in production in the household, which is exactly the concern.
• Paper on the fridge. Single-region and unreplicated, one magnet away from total data loss.
• Shouting "we need milk" across the flat. Event-first, admittedly, but with no durability and no consumer offsets.

Risks

Indicative cost

$23,870/month across two regions, excluding egress and groceries. This is lean.

Roadmap

• Phase 1, Foundations (18 months): landing zone, Terraform modules, Kafka, the Keycloak realm.
• Phase 2, Platform: Normalisation, Arbitration, the Saga.
• Phase 3, Re-platform: migration off Phase 2.
• Phase 4: the list, in month 31.

I have booked the ARB slot. It is in March.

Next steps

1. Raise ADR-0001: "Milk is an event, not a row."
2. Socialise with stakeholders, including the partner.
3. Book an ARB slot. Until then the stakeholder may keep using the fridge, which has been logged as tactical.

Target State Architecture: Enterprise Media Asset Identity Lifecycle Platform

v0.7 DRAFT · Status: For ARB review · Owner: Principal Enterprise Architect, Office of the CTO · Contributors: TBC (delivery)

Executive summary

This proposal establishes Naming-as-a-Platform: a governed, event-sourced capability for assigning, mutating and auditing the identity of media assets across the estate. The originating requirement was phrased as "I need to rename 40 photos on my laptop". That wording is regrettable, but it has been preserved in the event log, where it will stay forever.

Non-functional requirements

Guiding principles

1. Cloud-agnostic by default.
2. Event-first. A rename is something that happened, not something that is done.
3. No tactical solutions.
4. Filenames are a bounded context, not a string.
5. Humans never touch the filesystem directly. Humans caused the current filenames.

Logical architecture

• Asset Ingestion Service: discovers photos on the edge region.
• EXIF Extraction Service: reads capture metadata and publishes it to the Naming Policy Engine, which ignores it.
• Naming Policy Engine: decides what a photo is allowed to be called.
• Ordinal Allocation Service: issues the numbers 1 to 40, idempotently.
• Ordinal Allocation Proxy: calls the Ordinal Allocation Service.
• Collision Detection Service: makes sure no two photos become IMG_0001.
• Rename Saga Orchestrator: coordinates the rename, with a compensating rename back if it fails.
• Filename History Read Model: the CQRS projection of what each photo used to be called.

Diagram

flowchart LR
  H["Legacy (do not touch): the stakeholder"] -->|"drag-and-drop (untrusted)"| BFF["Photo BFF"]
  BFF -->|mTLS| GW["Kong API Gateway"]
  GW --> KC["Keycloak: may this human rename?"]
  GW --> ING["Asset Ingestion Service"]
  subgraph EU["Region: eu-west"]
    ING -->|"async (eventually)"| K1[("Kafka: photo.rename.requested, 64 partitions")]
    K1 --> EXIF["EXIF Extraction Service"]
    EXIF --> NPE["Naming Policy Engine"]
    NPE --> OAP["Ordinal Allocation Proxy"]
    OAP -->|gRPC| OAS["Ordinal Allocation Service"]
    OAS --> COL["Collision Detection Service"]
    COL --> SAGA["Temporal: Rename Saga"]
    SAGA -->|"async (eventually)"| K2[("Kafka: photo.renamed")]
    K2 --> FL["Flink: rename reconciliation"]
    FL -->|replay| COL
  end
  subgraph US["Region: us-east (active-active)"]
    CAS[("Cassandra: filename history")]
    ES[("Elasticsearch: former names")]
  end
  K2 --> CAS
  CAS --> ES
  SAGA -->|mTLS| EDGE["Edge Region: the laptop"]
  EDGE -->|"async (eventually)"| ING
  ES --> GRAF["Grafana: single pane of glass"]
  NPE -.-> AI["Future: AI Layer (names photos by vibe)"]
  CAS -.-> BC["Future: Blockchain (paused)"]

Legend: blue is strategic, amber is tactical (deprecated), grey is owned by delivery.

Technology choices

Rejected alternatives

The stakeholder proposed Finder's built-in batch rename: select all 40, right-click, Rename. Nearby, someone also proposed a shell for-loop. Both were rejected as tactical, as not scaling past 40, and as having no clear ownership model. Finder writes no events and has no SLO, and it does not let anyone replay a rename. It is a very natural first instinct. Most instincts are.

Risks

Indicative cost

$37,480/month excluding egress of 40 JPEGs, which is lean. Licensing TBC with Procurement, who have been informed and are thrilled.

Roadmap

I have booked the ARB slot. It is in March.

Next steps

1. Raise ADR-0001: "Photos are events."
2. Socialise with stakeholders.
3. Book a follow-up ARB slot to review the March slot.
4. Ask the delivery teams to keep the photos as they are until Phase 4.