# bobbyflow/ron-inbox-intelligence architecture

> Architecture diagram of the GitHub repository bobbyflow/ron-inbox-intelligence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bobbyflow/ron-inbox-intelligence
- Repository: https://github.com/bobbyflow/ron-inbox-intelligence

## Overview

1. **Project shape**
   This is a **single Python CLI application** centered on `gmail_intel.py`, not a service or web app. The rest of the repo is supporting material: safety documentation, example output, tests, and CI.

2. **Primary runtime**
   The tool runs locally on **Python 3.11+** and is intended to be executed from the command line in either **demo**, **dry-run calibration**, or **live monitor** mode. The command-line entry point is the main orchestration layer for the whole pipeline.

3. **External integrations**
   The system depends on Google Workspace APIs for **Gmail** and optionally **Calendar**. The README notes a required local adapter, `google_api.build_service`, which supplies authenticated service clients. That adapter is an important boundary: the repo assumes Gmail/Calendar connectivity but does not vendor the auth stack.

4. **Message ingestion boundary**
   The first subsystem is Gmail retrieval. It supports:
   - targeted candidate queries,
   - broader calibration sweeps,
   - custom Gmail search strings.
   
   This is the source of all message data flowing into the decision pipeline.

5. **Normalization layer**
   Retrieved messages are normalized into a consistent internal representation containing:
   - headers,
   - body text,
   - snippets,
   - attachments,
   - ICS payloads.
   
   This layer is important because later classification is driven by evidence aggregation across all of these fields, not just the subject line.

6. **Decision engine**
   The core logic is a **deterministic rule engine** that classifies each message into one of four actions:
   - `ignore`
   - `notify_user`
   - `needs_review`
   - `auto_create_calendar`
   
   The README emphasizes conservative behavior: only strong evidence allows automatic calendar writes. This makes the decision engine the main architectural boundary between “parsing” and “action.”

7. **Parser and safety subsystems**
   The repo uses **provider-aware parsers** for recurring event sources plus a conservative generic parser. Safety checks include:
   - confirmation/approval language,
   - parseable future date/time,
   - blocking waitlists/cancellations/tentative items,
   - inspecting ICS attachments,
   - preventing action on urgent-but-non-calendar categories such as financial or medical notices.
   
   These checks are not cosmetic; they directly gate whether a message becomes actionable.

8. **Calendar action path**
   Only high-confidence events can reach the live Google Calendar write path. Before creation, the system performs:
   - **idempotency key** checks,
   - **duplicate event scans** in the surrounding time window.
   
   For parseable-but-not-approved events, it can create clearly labeled placeholders such as `[PENDING APPROVAL]`, marked tentative/free. This is a distinct branch from full auto-creation.

9. **Persistence and audit trail**
   The application writes a **local SQLite audit trail** for messages, decisions, runs, and calendar actions. This is the main durability layer and supports traceability, reproducibility, and post-run review. The repo also emits **compact JSON reports** for downstream automation or dashboards.

10. **Demo and test harness**
   The repo includes a **zero-credential synthetic demo** (`--demo`) and an example output file under `examples/`. Tests focus on demo classification behavior, which suggests the public test surface is centered on the deterministic rule engine rather than external API calls.

11. **Documentation and safety model**
   `docs/safety-model.md` is a key design document: it defines the conservative decision rules and the kinds of messages that must never auto-act. `reports/README.md` likely documents report artifacts and usage, reinforcing that outputs are meant to be inspected and archived.

12. **CI and packaging posture**
   The `.github/workflows/ci.yml` workflow and `pyproject.toml`/`requirements.txt` indicate standard Python package hygiene: lint/test/compile checks rather than deployment orchestration. The repo is organized as an automation prototype with a strong emphasis on safety, auditability, and local-first operation.

Main entry points: [`gmail_intel.py`](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py) (gmail_intel.py), [`docs/safety-model.md`](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/docs/safety-model.md) (Safety gates), [`pyproject.toml`](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/pyproject.toml) (Packaging), [`tests/test_demo_classification.py`](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/tests/test_demo_classification.py) (tests/test_demo_classification.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Runtime"]
  node_n1["gmail_intel.py<br/>cli orchestrator<br/>[gmail_intel.py]"]
  node_n2(("Demo mode<br/>synthetic run<br/>[gmail_intel.py]"))
  node_n3["Query ingest<br/>gmail retrieval<br/>[gmail_intel.py]"]
  node_n4["Normalize mail<br/>message model<br/>[gmail_intel.py]"]
  node_n5{{"Rule engine<br/>deterministic classify<br/>[gmail_intel.py]"}}
end

subgraph group_g2["Integrations"]
  node_n9["Approval branch<br/>pending placeholder<br/>[gmail_intel.py]"]
  node_n10[("Calendar write<br/>google calendar<br/>[gmail_intel.py]")]
  node_n11["Dedupe checks<br/>idempotency<br/>[gmail_intel.py]"]
  node_n12["Service adapter<br/>google api boundary<br/>[gmail_intel.py]"]
end

subgraph group_g3["Safety"]
  node_n6{{"Safety gates<br/>approval filters<br/>[safety-model.md]"}}
  node_n7["Parser stack<br/>provider parsers<br/>[gmail_intel.py]"]
  node_n8["ICS inspect<br/>attachment evidence<br/>[gmail_intel.py]"]
  node_n13[("Audit SQLite<br/>local persistence<br/>[gmail_intel.py]")]
  node_n14["JSON reports<br/>compact output<br/>[gmail_intel.py]"]
  node_n15["docs/safety-model.md<br/>safety spec<br/>[safety-model.md]"]
end

subgraph group_g4["Project"]
  node_n16["examples/demo_output.json<br/>sample report<br/>[demo_output.json]"]
  node_n17["tests/test_demo_classification.py<br/>demo tests"]
  node_n18["CI workflow<br/>python ci<br/>[ci.yml]"]
  node_n19["Packaging<br/>project config<br/>[pyproject.toml]"]
  node_n20["Deps<br/>requirements<br/>[requirements.txt]"]
end

node_n1 -->|"demo"| node_n2
node_n1 -->|"ingest"| node_n3
node_n3 -->|"auth client"| node_n12
node_n3 -->|"messages"| node_n4
node_n4 -->|"parse"| node_n7
node_n4 -->|"attachments"| node_n8
node_n7 -->|"candidate event"| node_n6
node_n8 -->|"calendar evidence"| node_n6
node_n6 -->|"allow/deny"| node_n5
node_n5 -->|"pending"| node_n9
node_n5 -->|"auto create"| node_n10
node_n10 -->|"before write"| node_n11
node_n11 -->|"calendar client"| node_n12
node_n5 -->|"audit"| node_n13
node_n10 -->|"action log"| node_n13
node_n1 -->|"report"| node_n14
node_n14 -->|"example"| node_n16
node_n1 -->|"policy"| node_n15
node_n1 -->|"verified by"| node_n17
node_n18 -->|"runs"| node_n17
node_n19 -->|"packages"| node_n1
node_n19 -->|"depends on"| node_n20

click node_n1 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n2 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n3 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n4 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n5 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n6 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/docs/safety-model.md"
click node_n7 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n8 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n9 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n10 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n11 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n12 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n13 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n14 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py"
click node_n15 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/docs/safety-model.md"
click node_n16 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/examples/demo_output.json"
click node_n17 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/tests/test_demo_classification.py"
click node_n18 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/.github/workflows/ci.yml"
click node_n19 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/pyproject.toml"
click node_n20 "https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/requirements.txt"

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_n1,node_n2,node_n3,node_n4,node_n5 toneBlue
class node_n9,node_n10,node_n11,node_n12 toneAmber
class node_n6,node_n7,node_n8,node_n13,node_n14,node_n15 toneMint
class node_n16,node_n17,node_n18,node_n19,node_n20 toneRose
```

## Components

### Runtime

Local CLI execution and core processing pipeline

- [gmail_intel.py](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): cli orchestrator · Main command-line entry point and pipeline coordinator · `gmail_intel.py`
- [Demo mode](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): synthetic run · Zero-credential demo path used for local simulation · `gmail_intel.py`
- [Query ingest](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): gmail retrieval · Candidate queries, calibration sweeps, and custom Gmail search strings · `gmail_intel.py`
- [Normalize mail](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): message model · Normalizes headers, body, snippets, attachments, and ICS payloads · `gmail_intel.py`
- [Rule engine](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): deterministic classify · Maps each message to ignore, notify_user, needs_review, or auto_create_calendar · `gmail_intel.py`

### Integrations

External Google Workspace boundaries and write path

- [Approval branch](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): pending placeholder · Creates labeled tentative placeholders when an event is parseable but not approved · `gmail_intel.py`
- [Calendar write](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): google calendar · Live Google Calendar creation path for high-confidence events · `gmail_intel.py`
- [Dedupe checks](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): idempotency · Uses idempotency keys and duplicate scans in the surrounding time window · `gmail_intel.py`
- [Service adapter](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): google api boundary · Local authenticated build_service boundary for Gmail and optional Calendar clients · `gmail_intel.py`

### Safety

Conservative decision rules, audits, and documentation

- [Safety gates](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/docs/safety-model.md): approval filters · Confirmation language, future date checks, waitlist/cancellation blocking, and non-calendar category rejection · `docs/safety-model.md`
- [Parser stack](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): provider parsers · Provider-aware recurring-event parsing plus conservative generic parsing · `gmail_intel.py`
- [ICS inspect](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): attachment evidence · Examines calendar payloads embedded in message attachments · `gmail_intel.py`
- [Audit SQLite](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): local persistence · Stores messages, decisions, runs, and calendar actions · `gmail_intel.py`
- [JSON reports](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/gmail_intel.py): compact output · Emits machine-readable reports for downstream automation or review · `gmail_intel.py`
- [docs/safety-model.md](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/docs/safety-model.md): safety spec · Defines conservative action rules and never-auto-act categories · `docs/safety-model.md`

### Project

Packaging, tests, and supporting repo files

- [examples/demo_output.json](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/examples/demo_output.json): sample report · Example output artifact for the demo and report format · `examples/demo_output.json`
- [tests/test_demo_classification.py](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/tests/test_demo_classification.py): demo tests · Validates deterministic demo classification behavior · `tests/test_demo_classification.py`
- [CI workflow](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/.github/workflows/ci.yml): python ci · Automated lint, test, and compile checks · `.github/workflows/ci.yml`
- [Packaging](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/pyproject.toml): project config · Project metadata and dependency configuration · `pyproject.toml`
- [Deps](https://github.com/bobbyflow/ron-inbox-intelligence/blob/main/requirements.txt): requirements · Pinned runtime dependency list · `requirements.txt`

## Connections

- gmail_intel.py → Demo mode: demo · Runs synthetic local simulation mode
- gmail_intel.py → Query ingest: ingest · Fetches Gmail messages for analysis
- Query ingest → Service adapter: auth client · Uses service adapter to obtain Gmail/Calendar clients
- Query ingest → Normalize mail: messages · Passes retrieved messages into normalization
- Normalize mail → Parser stack: parse · Feeds structured text and metadata to parsers
- Normalize mail → ICS inspect: attachments · Surfaces ICS evidence for inspection
- Parser stack → Safety gates: candidate event · Parser output is checked by safety gates
- ICS inspect → Safety gates: calendar evidence · ICS payloads are evaluated conservatively
- Safety gates → Rule engine: allow/deny · Gates whether a message can become actionable
- Rule engine → Approval branch: pending · Routes parseable but unapproved items to placeholders
- Rule engine → Calendar write: auto create · Sends only high-confidence events to Calendar writes
- Calendar write → Dedupe checks: before write · Runs idempotency and duplicate detection first
- Dedupe checks → Service adapter: calendar client · Uses authenticated Calendar service for writes
- Rule engine → Audit SQLite: audit · Stores classifications and run metadata
- Calendar write → Audit SQLite: action log · Persists calendar actions for traceability
- gmail_intel.py → JSON reports: report · Emits compact JSON summaries
- JSON reports → examples/demo_output.json: example · Example output demonstrates report shape
- gmail_intel.py → docs/safety-model.md: policy · Implements the documented safety model
- gmail_intel.py → tests/test_demo_classification.py: verified by · Demo classification behavior is tested directly
- CI workflow → tests/test_demo_classification.py: runs · CI executes the test suite
- Packaging → gmail_intel.py: packages · Defines the Python application build and metadata
- Packaging → Deps: depends on · Declares runtime dependencies
