# googlecloudplatform/dgem architecture

> Architecture diagram of the GitHub repository googlecloudplatform/dgem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlecloudplatform/dgem
- Repository: https://github.com/googlecloudplatform/dgem

## Overview

dgem is a zero-shot decision engine: users supply typed decision templates and input, and the model returns constrained choices with probabilities and uncertainty. Its main workflow runs through the CLI or HTTP gateway into template-based decision execution against an inference backend; hesitant decisions can be escalated to Gemini. The repository also exposes MCP and an embedded Decision Studio, plus evaluation, permutation, and batch tooling. Several links below are dashed because the relevant implementation was not sampled; documented capabilities are retained without implying unobserved call chains.

Main entry points: [`pkg/client/client.go`](https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/client/client.go) (Inference client), [`cmd/serve.go`](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/serve.go) (HTTP gateway), [`studio/src/dgem-studio.ts`](https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/dgem-studio.ts) (Studio application), [`cmd/decide.go`](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/decide.go) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[decide.go]"]
  node_gateway["HTTP gateway<br/>[serve.go]"]
  node_mcp["MCP server<br/>[mcp.go]"]
end

subgraph group_decision["Decision runtime"]
  node_systemone["SystemOne API<br/>[engine.go]"]
  node_templates["Template engine<br/>[engine.go]"]
  node_client["Inference client<br/>[client.go]"]
  node_calibration["Calibration<br/>[temperature_fit.go]"]
  node_taxonomy["Taxonomy expansion<br/>[expand_taxonomy.go]"]
end

subgraph group_integrations["Model integrations"]
  node_cascade["Gemini cascade<br/>[cascade_gemini.go]"]
  node_vertex{{"Vertex AI"}}
  node_cloudrun["Cloud Run inference"]
end

subgraph group_evaluation["Evaluation and batch"]
  node_batch["Batch worker<br/>[batch_worker.py]"]
  node_bench["Benchmark commands"]
  node_matrix["Regression matrix<br/>[bench_matrix.py]"]
  node_permutation["Order-bias analysis<br/>[permutation.go]"]
  node_decisionindex["Decision index<br/>[engine.go]"]
end

subgraph group_studio["Decision Studio"]
  node_studioapp["Studio application<br/>[dgem-studio.ts]"]
  node_batchui["Studio batch runner"]
  node_concepts["Concept visualizer"]
  node_hesitation["Hesitation display<br/>[hesitation.ts]"]
  node_studioembed["Embedded assets<br/>[embed.go]"]
end

node_user(("Decision user"))

node_user -.->|"submits decision"| node_cli
node_user -->|"sends request"| node_gateway
node_user -->|"uses tools"| node_mcp
node_user -->|"uses Studio"| node_studioapp
node_cli -.->|"uses policy"| node_templates
node_cli -.->|"requests inference"| node_client
node_gateway -.->|"runs decisions"| node_templates
node_gateway -->|"routes requests"| node_systemone
node_gateway -->|"selects backend"| node_client
node_systemone -->|"scores questions"| node_client
node_mcp -.->|"lists policies"| node_templates
node_mcp -.->|"requests inference"| node_client
node_client -.->|"calls endpoint"| node_vertex
node_client -.->|"calls endpoint"| node_cloudrun
node_gateway -.->|"escalates answers"| node_cascade
node_cascade -.->|"calls Gemini"| node_vertex
node_cli -.->|"fits temperature"| node_calibration
node_bench -->|"evaluates deployment"| node_client
node_bench -->|"measures order bias"| node_permutation
node_matrix -.->|"tests targets"| node_client
node_decisionindex -->|"scores decisions"| node_client
node_batch -->|"starts server"| node_cloudrun
node_studioapp -.->|"loads embedded app"| node_studioembed
node_studioapp -->|"renders batch tool"| node_batchui
node_studioapp -->|"renders concepts"| node_concepts
node_studioapp -->|"calls API"| node_gateway
node_studioapp -->|"displays uncertainty"| node_hesitation
node_concepts -->|"computes bands"| node_hesitation
node_batchui -.->|"submits decisions"| node_gateway

click node_cli "https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/decide.go"
click node_gateway "https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/serve.go"
click node_mcp "https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/mcp.go"
click node_systemone "https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/decisionindex/engine.go"
click node_templates "https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/template/engine.go"
click node_client "https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/client/client.go"
click node_calibration "https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/temperature_fit.go"
click node_taxonomy "https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/expand_taxonomy.go"
click node_cascade "https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/cascade_gemini.go"
click node_cloudrun "https://github.com/GoogleCloudPlatform/dgem/blob/main/deploy/cloudrun/server/structured_server.py"
click node_batch "https://github.com/GoogleCloudPlatform/dgem/blob/main/deploy/batch/batch_worker.py"
click node_bench "https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/bench_calibration.go"
click node_matrix "https://github.com/GoogleCloudPlatform/dgem/blob/main/scripts/bench_matrix.py"
click node_permutation "https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/permutation/permutation.go"
click node_decisionindex "https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/decisionindex/engine.go"
click node_studioapp "https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/dgem-studio.ts"
click node_batchui "https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/components/dgem-batch-runner.ts"
click node_concepts "https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/components/dgem-concept-visualizer.ts"
click node_hesitation "https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/hesitation.ts"
click node_studioembed "https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/embed.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_gateway,node_mcp,node_user toneBlue
class node_systemone,node_templates,node_client,node_calibration,node_taxonomy toneAmber
class node_cascade,node_vertex,node_cloudrun toneMint
class node_batch,node_bench,node_matrix,node_permutation,node_decisionindex toneRose
class node_studioapp,node_batchui,node_concepts,node_hesitation,node_studioembed toneIndigo
```

## Components

### User interfaces

- [CLI commands](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/decide.go): `cmd/decide.go`
- [HTTP gateway](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/serve.go): `cmd/serve.go`
- [MCP server](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/mcp.go): `cmd/mcp.go`

### Decision runtime

- [SystemOne API](https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/decisionindex/engine.go): `pkg/decisionindex/engine.go`
- [Template engine](https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/template/engine.go): `pkg/template/engine.go`
- [Inference client](https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/client/client.go): `pkg/client/client.go`
- [Calibration](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/temperature_fit.go): `cmd/temperature_fit.go`
- [Taxonomy expansion](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/expand_taxonomy.go): `cmd/expand_taxonomy.go`

### Model integrations

- [Gemini cascade](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/cascade_gemini.go): `cmd/cascade_gemini.go`
- **Vertex AI**
- [Cloud Run inference](https://github.com/GoogleCloudPlatform/dgem/blob/main/deploy/cloudrun/server/structured_server.py): `deploy/cloudrun/server/structured_server.py`

### Evaluation and batch

- [Batch worker](https://github.com/GoogleCloudPlatform/dgem/blob/main/deploy/batch/batch_worker.py): `deploy/batch/batch_worker.py`
- [Benchmark commands](https://github.com/GoogleCloudPlatform/dgem/blob/main/cmd/bench_calibration.go): `cmd/bench_calibration.go`
- [Regression matrix](https://github.com/GoogleCloudPlatform/dgem/blob/main/scripts/bench_matrix.py): `scripts/bench_matrix.py`
- [Order-bias analysis](https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/permutation/permutation.go): `pkg/permutation/permutation.go`
- [Decision index](https://github.com/GoogleCloudPlatform/dgem/blob/main/pkg/decisionindex/engine.go): `pkg/decisionindex/engine.go`

### Decision Studio

- [Studio application](https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/dgem-studio.ts): `studio/src/dgem-studio.ts`
- [Studio batch runner](https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/components/dgem-batch-runner.ts): `studio/src/components/dgem-batch-runner.ts`
- [Concept visualizer](https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/components/dgem-concept-visualizer.ts): `studio/src/components/dgem-concept-visualizer.ts`
- [Hesitation display](https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/src/hesitation.ts): `studio/src/hesitation.ts`
- [Embedded assets](https://github.com/GoogleCloudPlatform/dgem/blob/main/studio/embed.go): `studio/embed.go`

### Other components

- **Decision user**

## Connections

- Decision user → CLI commands: submits decision
- Decision user → HTTP gateway: sends request
- Decision user → MCP server: uses tools
- Decision user → Studio application: uses Studio
- CLI commands → Template engine: uses policy
- CLI commands → Inference client: requests inference
- HTTP gateway → Template engine: runs decisions
- HTTP gateway → SystemOne API: routes requests (evidence: `cmd/serve.go`)
- HTTP gateway → Inference client: selects backend (evidence: `cmd/serve.go`)
- SystemOne API → Inference client: scores questions (evidence: `pkg/decisionindex/engine.go`)
- MCP server → Template engine: lists policies
- MCP server → Inference client: requests inference
- Inference client → Vertex AI: calls endpoint
- Inference client → Cloud Run inference: calls endpoint
- HTTP gateway → Gemini cascade: escalates answers
- Gemini cascade → Vertex AI: calls Gemini
- CLI commands → Calibration: fits temperature
- Benchmark commands → Inference client: evaluates deployment (evidence: `cmd/bench_calibration.go`)
- Benchmark commands → Order-bias analysis: measures order bias (evidence: `cmd/bench_calibration.go`)
- Regression matrix → Inference client: tests targets (evidence: `scripts/bench_matrix.py`)
- Decision index → Inference client: scores decisions (evidence: `pkg/decisionindex/engine.go`)
- Batch worker → Cloud Run inference: starts server (evidence: `deploy/batch/batch_worker.py`)
- Studio application → Embedded assets: loads embedded app (evidence: `studio/embed.go`)
- Studio application → Studio batch runner: renders batch tool (evidence: `studio/src/dgem-studio.ts`)
- Studio application → Concept visualizer: renders concepts (evidence: `studio/src/dgem-studio.ts`)
- Studio application → HTTP gateway: calls API
- Studio application → Hesitation display: displays uncertainty (evidence: `studio/src/dgem-studio.ts`)
- Concept visualizer → Hesitation display: computes bands (evidence: `studio/src/components/dgem-concept-visualizer.ts`)
- Studio batch runner → HTTP gateway: submits decisions