Architecture and deployment

Five consumers (Web and API, Agent tool surface, Model dispatch, Background work and Logs and traces) each read their configuration from, and write their audit record to, one store.

Most of it is data, not code. Changing it is usually a write, though new capability still takes a release. The store holds:

• Workflow definitions: steps, edges, dependencies
• Decision rules and thresholds: matched by shape, bands per ontology
• Service and model routing: a healthy instance, by capability and cost
• Secrets: provider keys encrypted at rest
• A history table: beside every managed table; soft delete only, and every change keeps its author, its timestamp and its prior value

All three are handled by one platform, one implementation: events, workflows, the decision loop: deterministic first, probabilistic second, human last, recorded either way.

Out: model providers, or in-network, on by default · signed webhooks to URLs you own · push notifications (FCM) · cloud APIs, only if configured.

Alerts and logs are outputs of the platform, not inputs, so they are not counted as a way in.

1. 1 Deterministic first An event arrives. Known shape, matching rule? Shapes and rules are matched by hash. yes → apply the workflow, no model callno → step 2
2. 2 Probabilistic second Model reasoning, constrained by your policy, then a quality gate. approve → proceedreview → try againreject → step 3
3. 3 Human last The human queue: an operator decides.

Promote to a learned rule, approved by a second person. That is how the system learns, and what gives step one more to match on next time.

This is the order the code actually runs in, not a statement of philosophy. Rules are evaluated first; where a model runs, a rule decided to call it and a rule bounds it.

One traced request. A request arrives and a trace_id is minted; every log line and every error carries it from that point on. Along the way a step runs, a model is called where a rule dispatches one, a person decides only if the gate sends it there, and rows are written to managed tables.

What it leaves behind, all reachable from that one identifier:

• Log lines, by trace: trace_id plus span_id on every line, shipped into the database.
• Step snapshot: workflow_step_executions, with the output written to workflow state.
• Prompt and response: persisted per trace and span as artefacts, with the cost in llm_usage_stats.
• Decision event: decision_events, kind hitl_resolved, so the person's decision is recorded inside the trail, not beside it.
• History rows: a platform_history row per change, carrying the author, the timestamp and the prior value. Soft delete only.

So "what happened, and why" is a query against one identifier, not a reconstruction.

1. 1 A model call is made Chat, embedding or rerank, from any service, through brain-stem-llm.
2. 2 The registry resolves it service_models × service_instances: a healthy instance for the capability, chosen by cost.
3. 3 Self-hosted, first vLLM, in your network: no credential, and no prompt egress. healthy → response to the callernone healthy → step 4
4. 4 A cloud provider, only if none is healthy Active by flag, with the key resolved by name from secrets and decrypted at the point of use, so swapping a provider key is one row.

A failing instance is paused by setting available_after per capability. The window expires by itself and the instance returns to rotation, with no operator action.

• Every call is recorded: llm_usage_stats carries the provider, the model, the cost and the trace_id.
• Production without a GPU runs cloud-only, through this same path. Nothing about the route changes; only which step succeeds.
• The mix is a routing decision you own: which models are self-hosted and which providers are active are rows in the registry, and the spend is queryable per call.

Inside the customer's network. nginx terminates TLS and routes requests, in front of:

• Platform API: REST and events
• Agent tool surface: the MCP server
• Web and account API: REST
• Model gateway: routes every model call
• Background workers: no listening port
• Log shipper: logs into the database
• One database: control plane, data, logs and history in one instance; vector search required
• An optional in-network model host: which removes prompt egress entirely. A GPU is a choice, not a requirement.

On the host: document conversion, and a secrets master key supplied from the environment.

Reached by default: your chosen LLM provider (prompt content leaves, unless the in-network option is taken, and the destination is a registry row, so it is substitutable).

Off unless explicitly configured: other model providers (Groq, Together AI, DeepSeek, OpenRouter, Anthropic, OpenAI, Google) · Google Sheets, Drive, FCM push and Gemini · AWS S3 and Secrets Manager · data sources and brokers (OpenStreetMap, Crawl4AI, an MQTT broker, external MCP servers) · signed callbacks to webhook URLs you register (HMAC-SHA256).

No telemetry, analytics, crash reporting or phone-home of any kind. Nothing else crosses the line.

Services bind all interfaces, so inside your network they are reachable from the LAN unless you firewall them. Some outbound paths leave via spawned CLI subprocesses, not HTTP, so enforce the egress allow-list at the host or network layer, not in a proxy.