# Civops Technical Architecture Brief

**Audience:** Engineering, IT/OT
**Read time:** ~8 minutes
**Companion to:** Civops Platform Overview, Security & Compliance Brief

---

## Deployment model

Civops runs as a **single-box appliance** at Purdue Level 3.5 inside the customer's own DMZ. The reference platform is a NUC-class x86 server for pilot tier; an ARM64 industrial appliance for production tier. One image SKU per tier — no third tier (preserves volume-pricing leverage with the manufacturer).

The appliance does **not** require outbound internet after cutover. Cloud Anthropic powers the pre-cutover phases (Marketing, Sales, Assessment, Setup); after the cutover state machine flips to **live**, every agent routes through onboard Ollama. The boundary is observable, audit-logged, and cannot regress without admin re-clearing readiness.

---

## Connectivity strategy — the replacement ladder

Civops never rips out an existing system on day one. Every Business System Connector walks a defined ladder:

| Stage | What Civops does | Customer impact |
|---|---|---|
| **passive_read** | Reads via API or DB replica · writes nothing back | Zero risk · sees everything · proves value |
| **shadow_write** | Writes shadow records · diff against source · alerts on drift | Side-by-side validation |
| **dual_write** | Writes both Civops and source · source remains primary | Operators learn the new interface · no data loss |
| **primary** | Civops is the system of record · source is read-only or retired | Customer's choice of timing |

This is what makes "no rip-and-replace" defensible. The customer decides when (or if) to promote each connector. Civops doesn't force a cutover.

---

## The data fabric

The platform is built on a **federated data fabric** — every plant owns its data; the enterprise tier reads via federation across plants. Disconnected plants are flagged in the matrix view, never silently dropped.

Key components:

- **Catalogs:** LLM models, system types, semantic tags
- **Agents:** 21 specialized agents (extraction, classification, anomaly, root-cause, etc.) — each declares preferredCloudModel + preferredLocalModel
- **Adapters:** Per-system connectors (QuickBooks Online, NetSuite, SAP, Ignition Historian, etc.) with the replacement ladder built in
- **Audit:** Single chokepoint writer for every config mutation, vault read, outbound HTTP call, connector write, and inference call. Append-only, hash-chained.
- **Inference seam:** `cloudInference` (Anthropic) and `localInference` (Ollama) are interchangeable behind one interface. The default export auto-selects via env.

---

## On-prem AI — Ollama

After go-live cutover, every agent's inference call routes to a local Ollama HTTP endpoint inside the appliance. Models are pre-pulled and warmed before cutover — first request is never a cold start.

Cutover is a state machine: `offline → preloading → warming → vetting → ready → live`. The "Go Live" button is disabled until every wired agent has a vetted local model candidate AND purpose-coverage is complete.

Vet TTL defaults to 14 days. After that, the vet drops and cutover regresses — drift can't hide behind a year-old pass.

---

## Network posture

| Requirement | How Civops handles it |
|---|---|
| **DMZ isolation** | Outbound-only connections from L3.5 to L4 corporate. No L4 → L3.5 inbound. |
| **OT VLAN respect** | Recursive 5-min review of OT VLAN configuration; never bridges eth0/eth1. |
| **ISA-95 hierarchy** | Enforced via `runIsaNamingScan`; bad names surface as warnings (pilot tier) → critical (audited tier). |
| **Plug-and-play hardware** | udev rules pre-loaded for every recommended scanner / printer / RFID. |

---

## Tech stack reference

- **App:** Next.js 15 App Router · TypeScript · Prisma · React 19
- **DB:** Postgres 16 + TimescaleDB (time-series) + pgvector (embeddings) · same image
- **AI (cloud):** Anthropic Claude (Sonnet for analysis, Haiku for extraction) — pre-cutover
- **AI (on-prem):** Ollama with vetted GGUF models — post-cutover
- **Auth:** NextAuth.js + MFA + lockout protection
- **Containerization:** docker-compose · standalone Next.js output · ~40-80 MB image instead of full node_modules
- **CI/CD:** Vercel for cloud demo · Packer for appliance image (gated behind `CIVOPS_PACKER_BUILD_ENABLED=1`)

---

## What engineers ask first, and what to say back

**"Does Civops require us to migrate our historian?"**
No. Passive-read mode lets Civops use your existing historian without writes. You promote connectors on your timeline.

**"What about DMZ compliance?"**
The compliance scan runs at boot and embeds in `runComplianceScan()`. Critical findings block go-live. We ship a DMZ Fit Assessment doc with the install guide.

**"Do we need to give Anthropic access to our plant data?"**
Pre-cutover, yes — for marketing/demo/assessment. Post-cutover, no. Ollama runs in the DMZ. There is no implicit cloud fallback after cutover; if a vet fails, the state regresses to vetting and admins re-clear before re-going-live.

**"What if your platform goes down?"**
The customer's source systems remain primary in passive_read mode. Civops being unavailable means dashboards are unavailable; production keeps running.

---

## Next step

The **Security & Compliance Brief** answers the audit/CISO questions in detail (SOC 2 readiness, GxP fit, audit chain). The **Customer Install Guide** walks the actual deploy.