# AI Executive Office — CXO Assistant Platform (On-Premises)

**Solution Architecture v1.1 · fully on-premise, open source, multi-tenant, sovereign-capable · Data & AI Global Practice · 2026-09 · 30 views · 34 architecture decision records**

A multi-tenant AI Executive Office that runs **entirely inside the customer's own data centre** — no cloud
plane, no vendor API call, no weight or prompt that leaves the building — architected as a **decision
intelligence platform rather than a chatbot with company data**: a governed conversational layer over
enterprise systems, specialist agents, decision intelligence and controlled execution, built for a sovereign
public-sector scenario and for the commercial tenants that come after it.

Every component is open source, or an enterprise product licensed to run on hardware the customer owns.
This is the on-premise twin of [`../cxo-assistant-platform/`](../cxo-assistant-platform/), which is the same
architecture on Azure: identical layers, identical actors and journeys, identical decision loop, and every
capability answered by a package the customer installs rather than a service they subscribe to.

Eight decisions carry the design:

- The **decision record** — situation, evidence, options, approval, action, outcome — is the system of record.
  The conversation is a rendering of it.
- The model **never touches data**. Every read goes through a typed **Model Context Protocol** tool plane
  carrying the caller's exchanged token, so the orchestrator holds no credential for any store.
- **Deterministic before generative.** KPIs come from measures in one governed semantic layer, forecasts from
  registered models on served endpoints. The model classifies, plans and narrates; it never produces a figure.
- **Abstention is a first-class outcome.** Claims are bound to evidence identifiers and checked mechanically;
  unsupported claims are removed and the gap is stated.
- **Isolation is a purchased tier.** Pooled and siloed deploy from one codebase, with sovereign tenants
  siloed by default — their own cluster, their own accelerators, their own database hosts.
- **Execution is a proposal, never a write.** One execution plane holds every write credential in the estate,
  one connector identity per target system, after a human approval.
- **Sovereignty is physical, then enforced** — the hardware is in a room the customer controls; admission
  control denies any workload without a residency label, the firewall denies unlisted egress, package feeds
  are mirrored rather than fetched, and the customer holds the key in its own HSM.
- **Only first-party MCP servers** run inside the boundary, and a tool description is treated as untrusted
  input rather than as instruction.

Thirty-four decision records carry the reasoning for every component and technology choice on these views.
Each gives the forcing question, the concrete on-premise mechanism, the alternatives that lost (including those
that are right for a different organisation), what the choice costs, when to choose differently, and the
transferable lesson. They are rendered on the landing page of the diagram set, directly below the index and
below the architecture one-pager, and again as two markdown documents the site renders in its own
reading layout: [docs/architecture-one-pager.md](docs/architecture-one-pager.md) (~11 min) and
[docs/decision-record.md](docs/decision-record.md) (~100 min).

---

## What is here

| Path | Contents |
|---|---|
| `diagrams/index.html` | The landing page: 30 views in seven acts, every format linked, then the **architecture one-pager** and the **full decision record** below the index |
| `diagrams/architecture-one-pager.docx` | The one-pager as a **Word document** — the same content plus the technology table, the risk register and the index of decisions, in a format a reviewer can mark up. Linked from the landing page |
| `diagrams/*.html` | One self-contained page per view: the inlined diagram plus the reasoning it leaves out, with copy / PNG / PDF export |
| `diagrams/svg/*.svg` | The same 30 views as SVG with the diagram XML embedded; they re-open in diagrams.net fully editable |
| `diagrams/drawio/*.drawio` | draw.io native source |
| `docs/architecture-one-pager.md` | The one-pager as markdown — the short executive read, and the first document the site links |
| `docs/decision-record.md` | The 34 decision records as markdown |
| `specs/part-a..d.json` | Diagram specifications, the source of truth for every view |
| `specs/manifest-a..b.json` | Acts, page titles, subtitles and the decision / assumption / risk cards |
| `specs/adr.json` | The one-pager, the 34 decision records, the capability-to-technology table and the package glossary |
| `scripts/build.sh` | Rebuilds every deliverable from the specs |
| `scripts/pin-icons.mjs` | Pins one mark per component, and stops the resolver putting a cloud provider's logo on a diagram whose argument is that no cloud is involved |
| `scripts/render-adr.mjs` | Validates `adr.json` and renders it into `diagrams/index.html` and the two `docs/*.md` |
| `scripts/make-docx.py` | Renders the one-pager into `diagrams/architecture-one-pager.docx` |
| `scripts/make-guide.mjs` | Builds the print-only 32-page A4 landscape guide into `build/` (not committed) |
| `ask.md` | The original requirement |

**`diagrams/` is standalone.** Copy that one folder anywhere, open `index.html` by double click, and
everything resolves offline — every page, every SVG, every draw.io file, the Word document, and every icon,
which is embedded as a data URI rather than fetched. `check-links.mjs` proves it on every build. The only
thing that touches the network is the export toolbar's `⋯` menu, and only when a reader presses it.

To rebuild after editing a spec:

```bash
bash scripts/build.sh          # requires Node 20+; python-docx only for the Word step
```

Edit `specs/part-*.json` and `specs/manifest-*.json`, never the assembled `views.json` / `manifest.json`.

---

## The technology, in one screen

| Layer | What runs it |
|---|---|
| Experience | Self-hosted chat client (Mattermost) for brief and approval, React web app for depth |
| Edge and contract | HAProxy with VRRP and a Coraza WAF; Kong Gateway, cluster-internal, for tenant quota and contract |
| Orchestration | LangGraph on Kubernetes, Temporal for durable investigations, Camunda 8 for approval workflow |
| Tool plane | First-party MCP servers, one per domain, tools resolved per role at start-up |
| AI | vLLM serving an open-weight 70B-class reasoning model and a 7B-class router on H100-class nodes; BGE-M3 and a cross-encoder on TEI; Llama Guard 3 and an NLI verifier for guardrails |
| Retrieval | OpenSearch — BM25 and k-NN fused, security filter in query context |
| Data | Apache Iceberg on MinIO, Trino for query, Spark for batch, Airflow and dbt for the build, Cube for the semantic layer, Superset for BI, Neo4j for the graph |
| Records | PostgreSQL under Patroni for the decision store, MinIO object lock for evidence, Redis for turn state |
| Integration | Kafka with Debezium for change data, Apache Camel for execution connectors |
| Identity and secrets | Keycloak federated to Active Directory with RFC 8693 token exchange; HashiCorp Vault fronting the customer's HSM |
| Platform | Istio, Calico, OPA Gatekeeper, Harbor, GitLab, Argo CD, Terraform, Helm, Ansible |
| Observability | Prometheus, Grafana, Loki, Tempo, OpenTelemetry, Langfuse; a second OpenSearch cluster as the SIEM |

The full table, with the credible alternative and the reason for each, is on the landing page and in
[docs/decision-record.md](docs/decision-record.md).

---

## The seven acts

| Act | What it lands | Views |
|---|---|---|
| 1 · Context and scope | The boundary, who touches it, and the shape of the platform in one picture | 01–02 |
| 2 · People and journeys | The executive office, the people who run it and the machines that act unasked, plus the three journeys whose worst moments the rest of the set answers | 03–06 |
| 3 · Structure | The layering rule, the deployable units in one tenant, every interface, and how one codebase serves many organisations | 07–10 |
| 4 · Data | Zones by rebuildability, source-to-answer flow, the canonical model, and how a document becomes a citation | 11–14 |
| 5 · Runtime | One question end to end, agent orchestration, who computes what, proactive detection, the closed loop, and governed execution | 15–20 |
| 6 · Operations | Sites and failure domains, delivery, observability, the evaluation loop, and the degradation contract | 21–25 |
| 7 · Assurance | Trust zones, the identity chain, sovereignty, AI guardrails, and reconstructing a decision months later | 26–30 |

---

## Verification

Every deliverable is machine-checked before hand-over:

| Gate | Result |
|---|---|
| `validate.mjs --strict` (geometry, labels, page bounds) | 30 files, **0 errors, 0 warnings** |
| `route-check.mjs` (arrows over boxes, labels on boxes) | 238 edges, **0 errors**, 10 clutter warnings |
| `icons.mjs check` | 619 nodes, **0 unresolved, 0 weak matches**, and **no cloud provider's logo anywhere** |
| `check-links.mjs` | 31 pages, 239 relative links, **all resolve** |
| `render-adr.mjs` | Every ADR cross-reference to a view, area and record validated before writing |

The ten remaining route-check warnings are label density on two views — the system context (01), where four
populated sides converge on one centre, and the integration catalogue (09), where fourteen interfaces are
listed deliberately. Both are the clutter class the skill prints and does not fail on; the alternative is
removing interfaces the view exists to enumerate.

Eleven boxes had to be pinned away from an Azure logo the resolver reached for on a word match — `Airflow`
found Azure Pipelines, `HAProxy + WAF` found Azure Active Directory, `Monitor` found Azure Monitor. Each is
recorded with its reason in `scripts/pin-icons.mjs`. The container marks were changed from the cloud glyph to
an on-premise one for the same reason: on this set a cloud badge on a data centre is an argument against the
architecture.

---

## Honest limits

- **This is a design, not a post-mortem.** No figure in it is a measured production number. Targets are
  engineering commitments to be tested; volumes are assumptions drawn from the requirement.
- **GPU supply, and the power and cooling available in the target hall, are the binding external
  constraints.** Accelerator lead times run to months, and a dense GPU rack materially changes a facility's
  power draw. ADR-29 carries both as a named risk with three pre-agreed fallbacks, to be confirmed with the
  customer's procurement and facilities functions before contract rather than assumed from these diagrams.
- **Somebody has to operate roughly twenty pieces of infrastructure software.** That is the real price of
  choosing on-premise over a managed cloud, it is larger than the hardware bill, and it belongs in the
  commercial model rather than in year two. The estate is deliberately narrowed for this reason (ADR-11).
- **There is no anycast scrubbing tier.** Volumetric denial of service is the enterprise perimeter's problem;
  the platform can state that honestly but cannot solve it (ADR-06).
- **Entity resolution across ERP, procurement and projects is the hardest item in the programme** and the one
  most often underestimated. ADR-16 treats it as a workstream with a human review queue, not a pipeline step.
- **Ten-year audit retention is assumed** from public-sector norms and must be confirmed per contract; it is
  the dominant driver of long-term storage sizing.
- **The customer is anonymous by design.** No organisation, country or jurisdiction is named anywhere in this
  package; sites are "primary" and "secondary", and the control framework is referred to generically. Sizing,
  the directory topology and the existing lake's table format are all stated as facts to confirm rather than
  assumed.