# cobusgreyling/jev architecture

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

- Interactive diagram: https://gitdiagram.com/cobusgreyling/jev
- Repository: https://github.com/cobusgreyling/jev

## Overview

Jev Showcase is an operator-facing interactive lab and smart-home demo, alongside a TypeScript CLI that applies Jev decisions to agent tasks. The main user workflows are exploring documented concepts and examples in the lab, issuing a home request that is judged and converted into a code-owned device plan, or invoking a CLI decision command for routing, retrieval, guardrails, or trace classification. Source excerpts support the Python API/client and parts of the TypeScript harness; unsampled CLI subsystems are included from the documented capabilities and tree, with uncertain internal wiring omitted.

Main entry points: [`app.py`](https://github.com/cobusgreyling/jev/blob/main/app.py) (Lab API), [`packages/js/src/cli.ts`](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/cli.ts) (Jev CLI), [`packages/js/src/client.ts`](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/client.ts) (TypeScript client), [`packages/js/src/route.ts`](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/route.ts) (Model routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lab["Operator lab"]
  node_browser["Browser UI<br/>[app.js]"]
  node_lab_api["Lab API<br/>[app.py]"]
  node_cost["Cost analysis<br/>[cost.py]"]
  node_policy["Ticket policy<br/>[policy.py]"]
end

subgraph group_home["Smart-home demo"]
  node_home_ui["Home UI<br/>[home.js]"]
  node_home_api["Home API<br/>[app.py]"]
  node_home_logic["House planning<br/>[home.py]"]
  node_home_state[("House state<br/>[home.py]")]
end

subgraph group_harness["Agent harness"]
  node_jev_cli["Jev CLI<br/>[cli.ts]"]
  node_routing["Model routing<br/>[route.ts]"]
  node_retrieval["Context retrieval<br/>[retrieve.ts]"]
  node_guardrails["Text guardrails<br/>[guard.ts]"]
  node_trace_classify["Trace classification<br/>[classify.ts]"]
  node_questions["Question builders<br/>[questions.ts]"]
end

subgraph group_service["Jev service"]
  node_js_client["TypeScript client<br/>[client.ts]"]
  node_py_client["Python client<br/>[client.py]"]
end

subgraph group_knowledge["Knowledge assets"]
  node_lab_data["Lab content"]
  node_home_examples["Home fixtures"]
end

node_operator(("Operator"))
node_cli_user(("CLI user"))
node_typesafe{{"TypeSafe System One"}}

node_operator -->|"uses"| node_browser
node_browser -->|"requests"| node_lab_api
node_lab_api -->|"calculates costs"| node_cost
node_lab_api -->|"applies policy"| node_policy
node_lab_api -->|"judges request"| node_py_client
node_lab_api -->|"loads content"| node_lab_data
node_home_ui -->|"submits commands"| node_home_api
node_home_api -->|"builds and applies plans"| node_home_logic
node_home_api -->|"judges home state"| node_py_client
node_home_api -->|"uses fixtures"| node_home_examples
node_home_logic -->|"updates device state"| node_home_state
node_home_ui -->|"applies confirmed plan"| node_home_api
node_cli_user -->|"invokes"| node_jev_cli
node_jev_cli -->|"routes task"| node_routing
node_jev_cli -->|"retrieves context"| node_retrieval
node_jev_cli -->|"screens text"| node_guardrails
node_jev_cli -->|"classifies trace"| node_trace_classify
node_routing -->|"builds questions"| node_questions
node_retrieval -->|"builds questions"| node_questions
node_routing -->|"calls service"| node_js_client
node_retrieval -->|"calls service"| node_js_client
node_guardrails -->|"calls service"| node_js_client
node_trace_classify -->|"calls service"| node_js_client
node_js_client -->|"sends decisions request"| node_typesafe
node_py_client -->|"sends decisions request"| node_typesafe

click node_browser "https://github.com/cobusgreyling/jev/blob/main/static/app.js"
click node_lab_api "https://github.com/cobusgreyling/jev/blob/main/app.py"
click node_cost "https://github.com/cobusgreyling/jev/blob/main/jev_lab/cost.py"
click node_policy "https://github.com/cobusgreyling/jev/blob/main/jev_lab/policy.py"
click node_home_ui "https://github.com/cobusgreyling/jev/blob/main/static/home.js"
click node_home_api "https://github.com/cobusgreyling/jev/blob/main/app.py"
click node_home_logic "https://github.com/cobusgreyling/jev/blob/main/jev_lab/home.py"
click node_home_state "https://github.com/cobusgreyling/jev/blob/main/jev_lab/home.py"
click node_jev_cli "https://github.com/cobusgreyling/jev/blob/main/packages/js/src/cli.ts"
click node_routing "https://github.com/cobusgreyling/jev/blob/main/packages/js/src/route.ts"
click node_retrieval "https://github.com/cobusgreyling/jev/blob/main/packages/js/src/retrieve.ts"
click node_guardrails "https://github.com/cobusgreyling/jev/blob/main/packages/js/src/guard.ts"
click node_trace_classify "https://github.com/cobusgreyling/jev/blob/main/packages/js/src/classify.ts"
click node_questions "https://github.com/cobusgreyling/jev/blob/main/packages/js/src/questions.ts"
click node_js_client "https://github.com/cobusgreyling/jev/blob/main/packages/js/src/client.ts"
click node_py_client "https://github.com/cobusgreyling/jev/blob/main/jev_lab/client.py"
click node_lab_data "https://github.com/cobusgreyling/jev/tree/main/data"
click node_home_examples "https://github.com/cobusgreyling/jev/tree/main/data/fixtures"

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_browser,node_lab_api,node_cost,node_policy,node_cli_user toneBlue
class node_home_ui,node_home_api,node_home_logic,node_home_state toneAmber
class node_jev_cli,node_routing,node_retrieval,node_guardrails,node_trace_classify,node_questions toneMint
class node_js_client,node_py_client toneRose
class node_lab_data,node_home_examples,node_operator,node_typesafe toneIndigo
```

## Components

### Operator lab

- [Browser UI](https://github.com/cobusgreyling/jev/blob/main/static/app.js): `static/app.js`
- [Lab API](https://github.com/cobusgreyling/jev/blob/main/app.py): `app.py`
- [Cost analysis](https://github.com/cobusgreyling/jev/blob/main/jev_lab/cost.py): `jev_lab/cost.py`
- [Ticket policy](https://github.com/cobusgreyling/jev/blob/main/jev_lab/policy.py): `jev_lab/policy.py`

### Smart-home demo

- [Home UI](https://github.com/cobusgreyling/jev/blob/main/static/home.js): `static/home.js`
- [Home API](https://github.com/cobusgreyling/jev/blob/main/app.py): `app.py`
- [House planning](https://github.com/cobusgreyling/jev/blob/main/jev_lab/home.py): `jev_lab/home.py`
- [House state](https://github.com/cobusgreyling/jev/blob/main/jev_lab/home.py): `jev_lab/home.py`

### Agent harness

- [Jev CLI](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/cli.ts): `packages/js/src/cli.ts`
- [Model routing](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/route.ts): `packages/js/src/route.ts`
- [Context retrieval](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/retrieve.ts): `packages/js/src/retrieve.ts`
- [Text guardrails](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/guard.ts): `packages/js/src/guard.ts`
- [Trace classification](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/classify.ts): `packages/js/src/classify.ts`
- [Question builders](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/questions.ts): `packages/js/src/questions.ts`

### Jev service

- [TypeScript client](https://github.com/cobusgreyling/jev/blob/main/packages/js/src/client.ts): `packages/js/src/client.ts`
- [Python client](https://github.com/cobusgreyling/jev/blob/main/jev_lab/client.py): `jev_lab/client.py`

### Knowledge assets

- [Lab content](https://github.com/cobusgreyling/jev/tree/main/data): `data`
- [Home fixtures](https://github.com/cobusgreyling/jev/tree/main/data/fixtures): `data/fixtures`

### Other components

- **Operator**
- **CLI user**
- **TypeSafe System One**

## Connections

- Operator → Browser UI: uses
- Browser UI → Lab API: requests
- Lab API → Cost analysis: calculates costs
- Lab API → Ticket policy: applies policy
- Lab API → Python client: judges request
- Lab API → Lab content: loads content
- Home UI → Home API: submits commands
- Home API → House planning: builds and applies plans
- Home API → Python client: judges home state
- Home API → Home fixtures: uses fixtures
- House planning → House state: updates device state
- Home UI → Home API: applies confirmed plan
- CLI user → Jev CLI: invokes
- Jev CLI → Model routing: routes task
- Jev CLI → Context retrieval: retrieves context
- Jev CLI → Text guardrails: screens text
- Jev CLI → Trace classification: classifies trace
- Model routing → Question builders: builds questions
- Context retrieval → Question builders: builds questions
- Model routing → TypeScript client: calls service
- Context retrieval → TypeScript client: calls service
- Text guardrails → TypeScript client: calls service
- Trace classification → TypeScript client: calls service
- TypeScript client → TypeSafe System One: sends decisions request
- Python client → TypeSafe System One: sends decisions request