# jev-chat/jev-chat-jarvis-mac architecture

> Architecture diagram of the GitHub repository jev-chat/jev-chat-jarvis-mac, 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/jev-chat/jev-chat-jarvis-mac
- Repository: https://github.com/jev-chat/jev-chat-jarvis-mac

## Overview

jev-chat-jarvis is a macOS read-only chat assistant: it observes the foreground chat, analyzes new messages for intent and risk, presents ranked reply suggestions, and only inserts text after the user requests it. The main runtime coordinator is the floating HUD, which dispatches to accessibility or screen-capture adapters and coordinates analysis, generation, and display. The README also documents manual region calibration, optional detection boxes, and locally stored conversation context. Some implementation files were not sampled, so subsystem links below follow documented behavior where noted; uncertain internal wiring is omitted.

Main entry points: [`src/hud.py`](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/hud.py) (Floating HUD), [`src/generate.py`](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/generate.py) (Reply generation), [`src/apps/registry.py`](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/registry.py) (App registry), [`src/apps/ax_app.py`](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/ax_app.py) (Accessibility adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Chat capture"]
  node_registry["App registry<br/>[registry.py]"]
  node_ax_app["Accessibility adapter<br/>[ax_app.py]"]
  node_capture_app["Capture adapter<br/>[capture_app.py]"]
  node_perception["OCR perception<br/>[perception.py]"]
  node_calibration["Region calibration<br/>[calibration.py]"]
  node_visual_fill["Detection boxes<br/>[visual_fill.py]"]
  node_input_region["Input regions<br/>[input_region.py]"]
end

subgraph group_reasoning["Analysis and replies"]
  node_judge["Local judgment<br/>[judge.py]"]
  node_cloud_judge["Cloud judgment<br/>[judge_jev.py]"]
  node_generate["Reply generation<br/>[generate.py]"]
  node_tones["Reply tones<br/>[builtin.py]"]
end

subgraph group_interface["HUD and interaction"]
  node_hud["Floating HUD<br/>[hud.py]"]
  node_calibration_ui["Calibration UI<br/>[calibration_ui.py]"]
  node_fill["Safe text fill<br/>[fill.py]"]
end

subgraph group_configuration["Settings and context"]
  node_chat_context["Context handling<br/>[chat_context.py]"]
  node_settings["Settings window<br/>[settings.py]"]
  node_settings_config["Settings controller<br/>[settings_config.py]"]
  node_userconfig["User configuration<br/>[userconfig.py]"]
end

node_user(("User"))
node_chat["Chat app"]
node_model_services["Model services"]

node_user -->|"receives messages"| node_chat
node_user -->|"views and acts"| node_hud
node_hud -->|"selects adapter"| node_registry
node_registry -->|"dispatches"| node_ax_app
node_registry -->|"dispatches"| node_capture_app
node_ax_app -->|"reads text"| node_chat
node_capture_app -->|"captures window"| node_chat
node_capture_app -->|"provides image"| node_perception
node_perception -->|"returns messages"| node_hud
node_ax_app -->|"returns messages"| node_hud
node_hud -->|"requests analysis"| node_judge
node_hud -.->|"requests analysis"| node_cloud_judge
node_judge -->|"returns intent and risk"| node_hud
node_cloud_judge -.->|"sends judgment request"| node_model_services
node_cloud_judge -.->|"returns judgment"| node_hud
node_hud -->|"starts generation"| node_generate
node_generate -->|"uses tone definitions"| node_tones
node_generate -.->|"requests candidates"| node_model_services
node_generate -->|"returns candidates"| node_hud
node_hud -->|"requests insertion"| node_fill
node_fill -->|"checks and inserts text"| node_chat
node_hud -->|"records and reads context"| node_chat_context
node_chat_context -->|"stores locally"| node_user
node_user -->|"edits regions"| node_calibration_ui
node_calibration_ui -->|"previews and saves"| node_calibration
node_calibration -->|"supplies regions"| node_perception
node_hud -.->|"updates optional boxes"| node_visual_fill
node_visual_fill -.->|"overlays detections"| node_chat
node_user -->|"configures app"| node_settings
node_settings -->|"edits settings"| node_settings_config
node_settings_config -->|"reads and writes env"| node_userconfig
node_settings_config -->|"updates context settings"| node_chat_context

click node_hud "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/hud.py"
click node_registry "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/registry.py"
click node_ax_app "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/ax_app.py"
click node_capture_app "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/capture_app.py"
click node_perception "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/perception.py"
click node_calibration "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/calibration.py"
click node_calibration_ui "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/calibration_ui.py"
click node_visual_fill "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/visual_fill.py"
click node_judge "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/judge.py"
click node_cloud_judge "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/judge_jev.py"
click node_generate "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/generate.py"
click node_tones "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/builtin.py"
click node_fill "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/fill.py"
click node_chat_context "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/chat_context.py"
click node_settings "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/settings.py"
click node_settings_config "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/settings_config.py"
click node_userconfig "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/userconfig.py"
click node_input_region "https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/input_region.py"

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_registry,node_ax_app,node_capture_app,node_perception,node_calibration,node_visual_fill,node_input_region,node_user toneBlue
class node_judge,node_cloud_judge,node_generate,node_tones toneAmber
class node_hud,node_calibration_ui,node_fill toneMint
class node_chat_context,node_settings,node_settings_config,node_userconfig toneRose
class node_chat,node_model_services toneIndigo
```

## Components

### Chat capture

- [App registry](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/registry.py): `src/apps/registry.py`
- [Accessibility adapter](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/ax_app.py): `src/apps/ax_app.py`
- [Capture adapter](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/apps/capture_app.py): `src/apps/capture_app.py`
- [OCR perception](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/perception.py): `src/perception.py`
- [Region calibration](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/calibration.py): `src/calibration.py`
- [Detection boxes](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/visual_fill.py): `src/visual_fill.py`
- [Input regions](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/input_region.py): `src/input_region.py`

### Analysis and replies

- [Local judgment](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/judge.py): `src/judge.py`
- [Cloud judgment](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/judge_jev.py): `src/judge_jev.py`
- [Reply generation](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/generate.py): `src/generate.py`
- [Reply tones](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/builtin.py): `src/builtin.py`

### HUD and interaction

- [Floating HUD](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/hud.py): `src/hud.py`
- [Calibration UI](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/calibration_ui.py): `src/calibration_ui.py`
- [Safe text fill](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/fill.py): `src/fill.py`

### Settings and context

- [Context handling](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/chat_context.py): `src/chat_context.py`
- [Settings window](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/settings.py): `src/settings.py`
- [Settings controller](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/settings_config.py): `src/settings_config.py`
- [User configuration](https://github.com/jev-chat/jev-chat-jarvis-mac/blob/master/src/userconfig.py): `src/userconfig.py`

### Other components

- **User**
- **Chat app**
- **Model services**

## Connections

- User → Chat app: receives messages
- User → Floating HUD: views and acts
- Floating HUD → App registry: selects adapter
- App registry → Accessibility adapter: dispatches
- App registry → Capture adapter: dispatches
- Accessibility adapter → Chat app: reads text
- Capture adapter → Chat app: captures window
- Capture adapter → OCR perception: provides image
- OCR perception → Floating HUD: returns messages
- Accessibility adapter → Floating HUD: returns messages
- Floating HUD → Local judgment: requests analysis
- Floating HUD → Cloud judgment: requests analysis
- Local judgment → Floating HUD: returns intent and risk
- Cloud judgment → Model services: sends judgment request
- Cloud judgment → Floating HUD: returns judgment
- Floating HUD → Reply generation: starts generation
- Reply generation → Reply tones: uses tone definitions
- Reply generation → Model services: requests candidates
- Reply generation → Floating HUD: returns candidates
- Floating HUD → Safe text fill: requests insertion
- Safe text fill → Chat app: checks and inserts text
- Floating HUD → Context handling: records and reads context
- Context handling → User: stores locally
- User → Calibration UI: edits regions
- Calibration UI → Region calibration: previews and saves
- Region calibration → OCR perception: supplies regions
- Floating HUD → Detection boxes: updates optional boxes
- Detection boxes → Chat app: overlays detections
- User → Settings window: configures app
- Settings window → Settings controller: edits settings
- Settings controller → User configuration: reads and writes env
- Settings controller → Context handling: updates context settings