# dannote/jev architecture

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

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

## Overview

Jev is an OTP client for TypeSafe and compatible decision models. Its main workflow accepts questions and state through a Jev.Server callback, dispatches each request asynchronously to a backend, converts the model response into a typed reply map, and routes that reply (or an error) to the user’s handle_answer callback. It also supports direct HTTP calls, custom backends, and request telemetry. The graph follows documented and sampled wiring; unsampled optional backends are shown only as an extension point.

Main entry points: [`lib/jev/http.ex`](https://github.com/dannote/jev/blob/master/lib/jev/http.ex) (HTTP Backend), [`lib/jev/server.ex`](https://github.com/dannote/jev/blob/master/lib/jev/server.ex) (Jev Server), [`lib/jev.ex`](https://github.com/dannote/jev/blob/master/lib/jev.ex) (Question Normalizer), [`lib/jev/backend.ex`](https://github.com/dannote/jev/blob/master/lib/jev/backend.ex) (Backend Contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_questions["Question API"]
  node_questions_api["Question Normalizer<br/>[jev.ex]"]
  node_noul["Yes/No Question<br/>[noul.ex]"]
  node_choice["Choice Question<br/>[choice.ex]"]
  node_score["Score Question<br/>[score.ex]"]
  node_reply_builder["Reply Builder<br/>[jev.ex]"]
end

subgraph group_otp["OTP Workflow"]
  node_jev_server["Jev Server<br/>[server.ex]"]
end

subgraph group_transport["Backend Transport"]
  node_backend["Backend Contract<br/>[backend.ex]"]
  node_http["HTTP Backend<br/>[http.ex]"]
  node_wire["Wire Codecs<br/>[wire.ex]"]
  node_error["HTTP Error<br/>[error.ex]"]
end

subgraph group_runtime["Runtime Services"]
  node_task_supervisor["Task Supervisor<br/>[application.ex]"]
  node_telemetry["Request Telemetry<br/>[telemetry.ex]"]
  node_application["OTP Application<br/>[application.ex]"]
end

node_caller(("OTP Caller"))
node_model_service(("Decision Model"))
node_direct_user(("Direct API User"))

node_caller -->|"calls"| node_jev_server
node_jev_server -->|"normalizes"| node_questions_api
node_questions_api -->|"builds"| node_noul
node_questions_api -->|"builds"| node_choice
node_questions_api -->|"builds"| node_score
node_jev_server -->|"starts task"| node_task_supervisor
node_jev_server -->|"dispatches"| node_backend
node_http -->|"implements"| node_backend
node_http -->|"spans request"| node_telemetry
node_http -->|"posts request"| node_model_service
node_model_service -->|"returns JSON"| node_http
node_http -->|"decodes"| node_wire
node_http -->|"builds reply"| node_reply_builder
node_reply_builder -->|"returns result"| node_jev_server
node_http -->|"returns failures"| node_error
node_jev_server -->|"delivers answer"| node_caller
node_application -->|"supervises"| node_task_supervisor
node_direct_user -.->|"posts directly"| node_http

click node_questions_api "https://github.com/dannote/jev/blob/master/lib/jev.ex"
click node_noul "https://github.com/dannote/jev/blob/master/lib/jev/noul.ex"
click node_choice "https://github.com/dannote/jev/blob/master/lib/jev/choice.ex"
click node_score "https://github.com/dannote/jev/blob/master/lib/jev/score.ex"
click node_jev_server "https://github.com/dannote/jev/blob/master/lib/jev/server.ex"
click node_task_supervisor "https://github.com/dannote/jev/blob/master/lib/jev/application.ex"
click node_backend "https://github.com/dannote/jev/blob/master/lib/jev/backend.ex"
click node_http "https://github.com/dannote/jev/blob/master/lib/jev/http.ex"
click node_wire "https://github.com/dannote/jev/blob/master/lib/jev/wire.ex"
click node_reply_builder "https://github.com/dannote/jev/blob/master/lib/jev.ex"
click node_error "https://github.com/dannote/jev/blob/master/lib/jev/error.ex"
click node_telemetry "https://github.com/dannote/jev/blob/master/lib/jev/telemetry.ex"
click node_application "https://github.com/dannote/jev/blob/master/lib/jev/application.ex"

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_questions_api,node_noul,node_choice,node_score,node_reply_builder,node_direct_user toneBlue
class node_jev_server toneAmber
class node_backend,node_http,node_wire,node_error toneMint
class node_task_supervisor,node_telemetry,node_application toneRose
class node_caller,node_model_service toneIndigo
```

## Components

### Question API

- [Question Normalizer](https://github.com/dannote/jev/blob/master/lib/jev.ex): `lib/jev.ex`
- [Yes/No Question](https://github.com/dannote/jev/blob/master/lib/jev/noul.ex): `lib/jev/noul.ex`
- [Choice Question](https://github.com/dannote/jev/blob/master/lib/jev/choice.ex): `lib/jev/choice.ex`
- [Score Question](https://github.com/dannote/jev/blob/master/lib/jev/score.ex): `lib/jev/score.ex`
- [Reply Builder](https://github.com/dannote/jev/blob/master/lib/jev.ex): `lib/jev.ex`

### OTP Workflow

- [Jev Server](https://github.com/dannote/jev/blob/master/lib/jev/server.ex): `lib/jev/server.ex`

### Backend Transport

- [Backend Contract](https://github.com/dannote/jev/blob/master/lib/jev/backend.ex): `lib/jev/backend.ex`
- [HTTP Backend](https://github.com/dannote/jev/blob/master/lib/jev/http.ex): `lib/jev/http.ex`
- [Wire Codecs](https://github.com/dannote/jev/blob/master/lib/jev/wire.ex): `lib/jev/wire.ex`
- [HTTP Error](https://github.com/dannote/jev/blob/master/lib/jev/error.ex): `lib/jev/error.ex`

### Runtime Services

- [Task Supervisor](https://github.com/dannote/jev/blob/master/lib/jev/application.ex): `lib/jev/application.ex`
- [Request Telemetry](https://github.com/dannote/jev/blob/master/lib/jev/telemetry.ex): `lib/jev/telemetry.ex`
- [OTP Application](https://github.com/dannote/jev/blob/master/lib/jev/application.ex): `lib/jev/application.ex`

### Other components

- **OTP Caller**
- **Decision Model**
- **Direct API User**

## Connections

- OTP Caller → Jev Server: calls
- Jev Server → Question Normalizer: normalizes
- Question Normalizer → Yes/No Question: builds
- Question Normalizer → Choice Question: builds
- Question Normalizer → Score Question: builds
- Jev Server → Task Supervisor: starts task
- Jev Server → Backend Contract: dispatches
- HTTP Backend → Backend Contract: implements
- HTTP Backend → Request Telemetry: spans request
- HTTP Backend → Decision Model: posts request
- Decision Model → HTTP Backend: returns JSON
- HTTP Backend → Wire Codecs: decodes
- HTTP Backend → Reply Builder: builds reply
- Reply Builder → Jev Server: returns result
- HTTP Backend → HTTP Error: returns failures
- Jev Server → OTP Caller: delivers answer
- OTP Application → Task Supervisor: supervises
- Direct API User → HTTP Backend: posts directly