# naroh091/hermes-proactive-radar architecture

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

- Interactive diagram: https://gitdiagram.com/naroh091/hermes-proactive-radar
- Repository: https://github.com/naroh091/hermes-proactive-radar

## Overview

Hermes Radar is a proactive assistant that turns mail, calendar, repository, and conversation activity into tracked tasks, decides what merits attention, and either handles work or asks the owner. The README documents this principal workflow and additional capabilities including warmup, trust-governed jobs, reminders, feedback learning, and dashboard/desktop views. Source excerpts are partial, so unsampled subsystem links below rely on README statements rather than inspected implementation details.

Main entry points: [`radar/pipeline/process.py`](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/process.py) (Task processing), [`radar/jobs/service.py`](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/jobs/service.py) (Job service), [`radar/pipeline/triage.py`](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/triage.py) (Signal triage), [`radar/delivery/dispatch.py`](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/dispatch.py) (Notice dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_signals["Signals & setup"]
  node_gmail["Mail source<br/>[gmail.py]"]
  node_calendar["Calendar source<br/>[calendar.py]"]
  node_github["GitHub source<br/>[github.py]"]
  node_sessions["Chat signals<br/>[session.py]"]
  node_cron["Cron signals<br/>[cron_output.py]"]
  node_ingress["Push ingress"]
  node_providers["Connectors<br/>[registry.py]"]
  node_warmup["Profile warmup<br/>[warmup.py]"]
  node_scheduler["Runtime scheduler<br/>[scheduler.py]"]
end

subgraph group_reasoning["Task reasoning"]
  node_triage["Signal triage<br/>[triage.py]"]
  node_process["Task processing<br/>[process.py]"]
  node_checklists["Task checklists<br/>[checklists.py]"]
  node_schemas["Pipeline schemas<br/>[schemas.py]"]
  node_store[("Radar state<br/>[store.py]")]
end

subgraph group_action["Actions &amp; trust"]
  node_jobs["Job service<br/>[service.py]"]
  node_runner["Job runner<br/>[runner.py]"]
  node_firewall["Execution firewall<br/>[firewall.py]"]
  node_native["Native operations<br/>[native.py]"]
  node_trust["Trust policy<br/>[trust.py]"]
end

subgraph group_delivery["Delivery &amp; learning"]
  node_cadence["Notice cadence<br/>[cadence.py]"]
  node_dispatch["Notice dispatch<br/>[dispatch.py]"]
  node_notice["Notice content<br/>[notice.py]"]
  node_context["Mail context<br/>[context.py]"]
  node_learn["Feedback learning<br/>[learn.py]"]
  node_preferences["User preferences<br/>[preferences.py]"]
end

subgraph group_surfaces["User surfaces"]
  node_dashboard["Dashboard panel<br/>[plugin_api.py]"]
  node_desktop["Desktop panel<br/>[plugin.js]"]
end

node_owner(("Owner"))
node_telegram(("Messaging gateway"))

node_gmail -->|"emits signals"| node_triage
node_calendar -->|"emits signals"| node_triage
node_github -->|"emits signals"| node_triage
node_sessions -->|"emits signals"| node_triage
node_cron -->|"emits signals"| node_triage
node_ingress -.->|"receives push"| node_gmail
node_providers -.->|"connects source"| node_gmail
node_providers -.->|"connects source"| node_calendar
node_warmup -->|"learns habits"| node_gmail
node_warmup -->|"learns habits"| node_calendar
node_triage -->|"filters signals"| node_process
node_process -->|"updates tasks"| node_store
node_process -->|"builds checks"| node_checklists
node_process -.->|"uses schemas"| node_schemas
node_scheduler -.->|"runs pipeline"| node_process
node_process -.->|"proposes work"| node_jobs
node_jobs -->|"checks permission"| node_trust
node_jobs -->|"applies safeguards"| node_firewall
node_jobs -->|"starts delegated job"| node_runner
node_jobs -->|"routes native work"| node_native
node_scheduler -->|"starts approved work"| node_jobs
node_store -.->|"supplies task state"| node_dispatch
node_dispatch -.->|"schedules notices"| node_cadence
node_dispatch -.->|"prepares messages"| node_notice
node_notice -.->|"adds email context"| node_context
node_owner -->|"replies to notices"| node_telegram
node_dispatch -->|"sends notices"| node_telegram
node_telegram -->|"captures feedback"| node_learn
node_learn -.->|"updates preferences"| node_preferences
node_owner -->|"reviews tasks"| node_dashboard
node_dashboard -->|"reads and records decisions"| node_store
node_owner -->|"views task panel"| node_desktop
node_desktop -.->|"uses shared panel API"| node_dashboard

click node_gmail "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/gmail.py"
click node_calendar "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/calendar.py"
click node_github "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/github.py"
click node_sessions "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/session.py"
click node_cron "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/cron_output.py"
click node_ingress "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/ingress/gmail_push_receiver.py"
click node_providers "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/providers/registry.py"
click node_warmup "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/warmup.py"
click node_scheduler "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/scheduler.py"
click node_triage "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/triage.py"
click node_process "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/process.py"
click node_checklists "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/checklists.py"
click node_schemas "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/schemas.py"
click node_store "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/store.py"
click node_jobs "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/jobs/service.py"
click node_runner "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/jobs/runner.py"
click node_firewall "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/jobs/firewall.py"
click node_native "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/operations/native.py"
click node_trust "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/trust.py"
click node_cadence "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/cadence.py"
click node_dispatch "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/dispatch.py"
click node_notice "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/notice.py"
click node_context "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/context.py"
click node_learn "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/learn.py"
click node_preferences "https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/preferences.py"
click node_dashboard "https://github.com/naroh091/hermes-proactive-radar/blob/main/dashboard/plugin_api.py"
click node_desktop "https://github.com/naroh091/hermes-proactive-radar/blob/main/desktop/plugin.js"

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_gmail,node_calendar,node_github,node_sessions,node_cron,node_ingress,node_providers,node_warmup,node_scheduler toneBlue
class node_triage,node_process,node_checklists,node_schemas,node_store toneAmber
class node_jobs,node_runner,node_firewall,node_native,node_trust toneMint
class node_cadence,node_dispatch,node_notice,node_context,node_learn,node_preferences toneRose
class node_dashboard,node_desktop,node_owner,node_telegram toneIndigo
```

## Components

### Signals & setup

- [Mail source](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/gmail.py): `radar/sources/gmail.py`
- [Calendar source](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/calendar.py): `radar/sources/calendar.py`
- [GitHub source](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/github.py): `radar/sources/github.py`
- [Chat signals](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/session.py): `radar/sources/session.py`
- [Cron signals](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/sources/cron_output.py): `radar/sources/cron_output.py`
- [Push ingress](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/ingress/gmail_push_receiver.py): `radar/ingress/gmail_push_receiver.py`
- [Connectors](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/providers/registry.py): `radar/providers/registry.py`
- [Profile warmup](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/warmup.py): `radar/warmup.py`
- [Runtime scheduler](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/scheduler.py): `radar/scheduler.py`

### Task reasoning

- [Signal triage](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/triage.py): `radar/pipeline/triage.py`
- [Task processing](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/process.py): `radar/pipeline/process.py`
- [Task checklists](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/checklists.py): `radar/pipeline/checklists.py`
- [Pipeline schemas](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/pipeline/schemas.py): `radar/pipeline/schemas.py`
- [Radar state](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/store.py): `radar/store.py`

### Actions & trust

- [Job service](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/jobs/service.py): `radar/jobs/service.py`
- [Job runner](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/jobs/runner.py): `radar/jobs/runner.py`
- [Execution firewall](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/jobs/firewall.py): `radar/jobs/firewall.py`
- [Native operations](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/operations/native.py): `radar/operations/native.py`
- [Trust policy](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/trust.py): `radar/trust.py`

### Delivery & learning

- [Notice cadence](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/cadence.py): `radar/delivery/cadence.py`
- [Notice dispatch](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/dispatch.py): `radar/delivery/dispatch.py`
- [Notice content](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/notice.py): `radar/delivery/notice.py`
- [Mail context](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/context.py): `radar/delivery/context.py`
- [Feedback learning](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/delivery/learn.py): `radar/delivery/learn.py`
- [User preferences](https://github.com/naroh091/hermes-proactive-radar/blob/main/radar/preferences.py): `radar/preferences.py`

### User surfaces

- [Dashboard panel](https://github.com/naroh091/hermes-proactive-radar/blob/main/dashboard/plugin_api.py): `dashboard/plugin_api.py`
- [Desktop panel](https://github.com/naroh091/hermes-proactive-radar/blob/main/desktop/plugin.js): `desktop/plugin.js`

### Other components

- **Owner**
- **Messaging gateway**

## Connections

- Mail source → Signal triage: emits signals
- Calendar source → Signal triage: emits signals
- GitHub source → Signal triage: emits signals (evidence: `radar/sources/github.py`)
- Chat signals → Signal triage: emits signals
- Cron signals → Signal triage: emits signals
- Push ingress → Mail source: receives push
- Connectors → Mail source: connects source
- Connectors → Calendar source: connects source
- Profile warmup → Mail source: learns habits
- Profile warmup → Calendar source: learns habits
- Signal triage → Task processing: filters signals
- Task processing → Radar state: updates tasks
- Task processing → Task checklists: builds checks
- Task processing → Pipeline schemas: uses schemas
- Runtime scheduler → Task processing: runs pipeline
- Task processing → Job service: proposes work
- Job service → Trust policy: checks permission (evidence: `radar/jobs/service.py`)
- Job service → Execution firewall: applies safeguards (evidence: `radar/jobs/service.py`)
- Job service → Job runner: starts delegated job (evidence: `radar/jobs/service.py`)
- Job service → Native operations: routes native work (evidence: `radar/jobs/service.py`)
- Runtime scheduler → Job service: starts approved work
- Radar state → Notice dispatch: supplies task state
- Notice dispatch → Notice cadence: schedules notices
- Notice dispatch → Notice content: prepares messages
- Notice content → Mail context: adds email context
- Owner → Messaging gateway: replies to notices
- Notice dispatch → Messaging gateway: sends notices
- Messaging gateway → Feedback learning: captures feedback
- Feedback learning → User preferences: updates preferences
- Owner → Dashboard panel: reviews tasks
- Dashboard panel → Radar state: reads and records decisions (evidence: `dashboard/plugin_api.py`)
- Owner → Desktop panel: views task panel
- Desktop panel → Dashboard panel: uses shared panel API