# ado11231/jevqa architecture

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

- Interactive diagram: https://gitdiagram.com/ado11231/jevqa
- Repository: https://github.com/ado11231/jevqa

## Overview

jevqa turns Markdown checklists into automated tests of web and mobile interfaces, using visible screen content rather than application source. The principal workflow is: the engineer supplies a test and configuration, the CLI starts a run, the runner executes steps through a device driver, rules or Jev determine outcomes, and events are saved and shown in the terminal or harness. The README documents native-device support as a capability, though the excerpts establish only the web driver’s implementation details; several package connections are supported by the README rather than sampled call sites.

Main entry points: [`packages/runner/src/step.ts`](https://github.com/ado11231/jevqa/blob/main/packages/runner/src/step.ts) (Step execution), [`packages/cli/src/commands/run.ts`](https://github.com/ado11231/jevqa/blob/main/packages/cli/src/commands/run.ts) (Run command), [`packages/runner/src/run.ts`](https://github.com/ado11231/jevqa/blob/main/packages/runner/src/run.ts) (Test runner), [`packages/drivers/src/web.ts`](https://github.com/ado11231/jevqa/blob/main/packages/drivers/src/web.ts) (Web driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Test setup"]
  node_markdown["Checklist file"]
  node_config["Run configuration<br/>[config.ts]"]
  node_testfile["Test parsing<br/>[testfile.ts]"]
end

subgraph group_execution["Run execution"]
  node_cli["Run command<br/>[run.ts]"]
  node_runner["Test runner<br/>[run.ts]"]
  node_step["Step execution<br/>[step.ts]"]
  node_rules["Step rules<br/>[step-rules.ts]"]
  node_driver["Device interface<br/>[driver.ts]"]
  node_webdriver["Web driver<br/>[web.ts]"]
  node_native["Native driver"]
end

subgraph group_judgment["Screen judgment"]
  node_screen["Screen reader<br/>[read-web-screen.ts]"]
  node_snapshot["Screen snapshot<br/>[snapshot.ts]"]
  node_judge["Jev judge<br/>[jev.ts]"]
  node_verdict["Verdict rules<br/>[verdict.ts]"]
end

subgraph group_reporting["Run reporting"]
  node_events["Run events<br/>[events.ts]"]
  node_log["Run log<br/>[log.ts]"]
  node_terminal["Terminal output<br/>[terminal-output.ts]"]
  node_harness["Harness server<br/>[server.ts]"]
  node_harnesspage["Harness UI<br/>[App.tsx]"]
  node_eventstream["Live event reader<br/>[useRunEvents.ts]"]
end

node_engineer(("Test author"))
node_app["Tested app"]
node_jevservice["Jev API"]

node_engineer -->|"writes steps"| node_markdown
node_engineer -->|"configures run"| node_config
node_markdown -->|"selects tests"| node_cli
node_config -->|"loads settings"| node_cli
node_cli -->|"parses tests"| node_testfile
node_cli -->|"starts run"| node_runner
node_runner -->|"runs steps"| node_step
node_step -->|"checks rules"| node_rules
node_step -->|"controls device"| node_driver
node_driver -->|"implemented by"| node_webdriver
node_webdriver -->|"controls browser"| node_app
node_webdriver -->|"reads screen"| node_screen
node_step -->|"builds snapshot"| node_snapshot
node_step -->|"asks questions"| node_judge
node_judge -.->|"sends questions"| node_jevservice
node_step -->|"assesses answers"| node_verdict
node_step -->|"emits events"| node_events
node_runner -->|"writes events"| node_log
node_cli -->|"renders events"| node_terminal
node_cli -->|"forwards events"| node_harness
node_harness -->|"streams events"| node_eventstream
node_eventstream -->|"updates view"| node_harnesspage
node_runner -.->|"supports devices"| node_native

click node_config "https://github.com/ado11231/jevqa/blob/main/packages/core/src/config.ts"
click node_testfile "https://github.com/ado11231/jevqa/blob/main/packages/core/src/testfile.ts"
click node_cli "https://github.com/ado11231/jevqa/blob/main/packages/cli/src/commands/run.ts"
click node_runner "https://github.com/ado11231/jevqa/blob/main/packages/runner/src/run.ts"
click node_step "https://github.com/ado11231/jevqa/blob/main/packages/runner/src/step.ts"
click node_rules "https://github.com/ado11231/jevqa/blob/main/packages/runner/src/step-rules.ts"
click node_driver "https://github.com/ado11231/jevqa/blob/main/packages/drivers/src/driver.ts"
click node_webdriver "https://github.com/ado11231/jevqa/blob/main/packages/drivers/src/web.ts"
click node_screen "https://github.com/ado11231/jevqa/blob/main/packages/drivers/src/read-web-screen.ts"
click node_snapshot "https://github.com/ado11231/jevqa/blob/main/packages/core/src/snapshot.ts"
click node_judge "https://github.com/ado11231/jevqa/blob/main/packages/judge/src/jev.ts"
click node_verdict "https://github.com/ado11231/jevqa/blob/main/packages/core/src/verdict.ts"
click node_events "https://github.com/ado11231/jevqa/blob/main/packages/core/src/events.ts"
click node_log "https://github.com/ado11231/jevqa/blob/main/packages/runner/src/log.ts"
click node_terminal "https://github.com/ado11231/jevqa/blob/main/packages/cli/src/terminal-output.ts"
click node_harness "https://github.com/ado11231/jevqa/blob/main/packages/server/src/server.ts"
click node_harnesspage "https://github.com/ado11231/jevqa/blob/main/packages/ui/src/App.tsx"
click node_eventstream "https://github.com/ado11231/jevqa/blob/main/packages/ui/src/useRunEvents.ts"
click node_native "https://github.com/ado11231/jevqa/tree/main/packages/drivers/src"

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_markdown,node_config,node_testfile toneBlue
class node_cli,node_runner,node_step,node_rules,node_driver,node_webdriver,node_native toneAmber
class node_screen,node_snapshot,node_judge,node_verdict,node_jevservice toneMint
class node_events,node_log,node_terminal,node_harness,node_harnesspage,node_eventstream toneRose
class node_engineer,node_app toneIndigo
```

## Components

### Test setup

- **Checklist file**
- [Run configuration](https://github.com/ado11231/jevqa/blob/main/packages/core/src/config.ts): `packages/core/src/config.ts`
- [Test parsing](https://github.com/ado11231/jevqa/blob/main/packages/core/src/testfile.ts): `packages/core/src/testfile.ts`

### Run execution

- [Run command](https://github.com/ado11231/jevqa/blob/main/packages/cli/src/commands/run.ts): `packages/cli/src/commands/run.ts`
- [Test runner](https://github.com/ado11231/jevqa/blob/main/packages/runner/src/run.ts): `packages/runner/src/run.ts`
- [Step execution](https://github.com/ado11231/jevqa/blob/main/packages/runner/src/step.ts): `packages/runner/src/step.ts`
- [Step rules](https://github.com/ado11231/jevqa/blob/main/packages/runner/src/step-rules.ts): `packages/runner/src/step-rules.ts`
- [Device interface](https://github.com/ado11231/jevqa/blob/main/packages/drivers/src/driver.ts): `packages/drivers/src/driver.ts`
- [Web driver](https://github.com/ado11231/jevqa/blob/main/packages/drivers/src/web.ts): `packages/drivers/src/web.ts`
- [Native driver](https://github.com/ado11231/jevqa/tree/main/packages/drivers/src): `packages/drivers/src`

### Screen judgment

- [Screen reader](https://github.com/ado11231/jevqa/blob/main/packages/drivers/src/read-web-screen.ts): `packages/drivers/src/read-web-screen.ts`
- [Screen snapshot](https://github.com/ado11231/jevqa/blob/main/packages/core/src/snapshot.ts): `packages/core/src/snapshot.ts`
- [Jev judge](https://github.com/ado11231/jevqa/blob/main/packages/judge/src/jev.ts): `packages/judge/src/jev.ts`
- [Verdict rules](https://github.com/ado11231/jevqa/blob/main/packages/core/src/verdict.ts): `packages/core/src/verdict.ts`

### Run reporting

- [Run events](https://github.com/ado11231/jevqa/blob/main/packages/core/src/events.ts): `packages/core/src/events.ts`
- [Run log](https://github.com/ado11231/jevqa/blob/main/packages/runner/src/log.ts): `packages/runner/src/log.ts`
- [Terminal output](https://github.com/ado11231/jevqa/blob/main/packages/cli/src/terminal-output.ts): `packages/cli/src/terminal-output.ts`
- [Harness server](https://github.com/ado11231/jevqa/blob/main/packages/server/src/server.ts): `packages/server/src/server.ts`
- [Harness UI](https://github.com/ado11231/jevqa/blob/main/packages/ui/src/App.tsx): `packages/ui/src/App.tsx`
- [Live event reader](https://github.com/ado11231/jevqa/blob/main/packages/ui/src/useRunEvents.ts): `packages/ui/src/useRunEvents.ts`

### Other components

- **Test author**
- **Tested app**
- **Jev API**

## Connections

- Test author → Checklist file: writes steps
- Test author → Run configuration: configures run
- Checklist file → Run command: selects tests
- Run configuration → Run command: loads settings
- Run command → Test parsing: parses tests
- Run command → Test runner: starts run
- Test runner → Step execution: runs steps
- Step execution → Step rules: checks rules
- Step execution → Device interface: controls device
- Device interface → Web driver: implemented by
- Web driver → Tested app: controls browser
- Web driver → Screen reader: reads screen
- Step execution → Screen snapshot: builds snapshot
- Step execution → Jev judge: asks questions
- Jev judge → Jev API: sends questions
- Step execution → Verdict rules: assesses answers
- Step execution → Run events: emits events
- Test runner → Run log: writes events
- Run command → Terminal output: renders events
- Run command → Harness server: forwards events
- Harness server → Live event reader: streams events
- Live event reader → Harness UI: updates view
- Test runner → Native driver: supports devices