# parambhatia2004/jack-ryan architecture

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

- Interactive diagram: https://gitdiagram.com/parambhatia2004/jack-ryan
- Repository: https://github.com/parambhatia2004/jack-ryan

## Overview

Jack Ryan is a background engineering-risk monitor. On each polling cycle, its agent fetches GitHub pull requests and Jira sprint, completed, and incident tickets; it runs five detectors, compares findings with persisted active signals, and posts new or resolved alerts to Slack. Incident-linked PRs also seed file-risk scores. The README documents these capabilities; the graph’s implementation links are limited to the excerpts and source-index references provided.

Main entry points: [`agent.py`](https://github.com/parambhatia2004/jack-ryan/blob/main/agent.py) (Polling agent), [`config.py`](https://github.com/parambhatia2004/jack-ryan/blob/main/config.py) (Configuration), [`monitors/jira.py`](https://github.com/parambhatia2004/jack-ryan/blob/main/monitors/jira.py) (Jira monitor), [`monitors/github.py`](https://github.com/parambhatia2004/jack-ryan/blob/main/monitors/github.py) (GitHub monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Polling orchestration"]
  node_agent["Polling agent<br/>[agent.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_collection["Activity collection"]
  node_github_monitor["GitHub monitor<br/>[github.py]"]
  node_jira_monitor["Jira monitor<br/>[jira.py]"]
end

subgraph group_detection["Risk detection"]
  node_incident_files["Incident-linked files<br/>[incident_files.py]"]
  node_large_change["Large untracked change"]
  node_simultaneous_edits["Simultaneous edits"]
  node_done_no_pr["Done without PR<br/>[done_no_pr.py]"]
  node_sprint_coordination["Sprint coordination"]
end

subgraph group_state_delivery["State and delivery"]
  node_db[("SQLite state<br/>[db.py]")]
  node_slack_module["Slack delivery<br/>[slack.py]"]
end

node_operator(("Operator"))
node_github["GitHub"]
node_jira["Jira"]
node_slack["Slack"]

node_operator -.->|"starts"| node_agent
node_agent -->|"fetches PRs"| node_github_monitor
node_agent -->|"fetches tickets"| node_jira_monitor
node_github_monitor -->|"queries"| node_github
node_jira_monitor -->|"queries"| node_jira
node_agent -->|"runs check"| node_incident_files
node_agent -->|"runs check"| node_large_change
node_agent -->|"runs check"| node_simultaneous_edits
node_agent -->|"runs check"| node_done_no_pr
node_agent -->|"runs check"| node_sprint_coordination
node_incident_files -->|"reads risk scores"| node_db
node_agent -->|"tracks signals"| node_db
node_agent -->|"seeds risk scores"| node_db
node_agent -->|"fetches PR links"| node_jira_monitor
node_agent -->|"posts alerts"| node_slack_module
node_slack_module -->|"sends messages"| node_slack
node_agent -->|"reads settings"| node_config
node_github_monitor -->|"reads credentials"| node_config
node_jira_monitor -->|"reads credentials"| node_config
node_slack_module -->|"reads credentials"| node_config
node_done_no_pr -->|"reads grace period"| node_config
node_sprint_coordination -->|"reads thresholds"| node_config

click node_agent "https://github.com/parambhatia2004/jack-ryan/blob/main/agent.py"
click node_config "https://github.com/parambhatia2004/jack-ryan/blob/main/config.py"
click node_github_monitor "https://github.com/parambhatia2004/jack-ryan/blob/main/monitors/github.py"
click node_jira_monitor "https://github.com/parambhatia2004/jack-ryan/blob/main/monitors/jira.py"
click node_incident_files "https://github.com/parambhatia2004/jack-ryan/blob/main/signals/incident_files.py"
click node_large_change "https://github.com/parambhatia2004/jack-ryan/blob/main/signals/large_untracked_change.py"
click node_simultaneous_edits "https://github.com/parambhatia2004/jack-ryan/blob/main/signals/simultaneous_edits.py"
click node_done_no_pr "https://github.com/parambhatia2004/jack-ryan/blob/main/signals/done_no_pr.py"
click node_sprint_coordination "https://github.com/parambhatia2004/jack-ryan/blob/main/signals/sprint_coordination.py"
click node_db "https://github.com/parambhatia2004/jack-ryan/blob/main/db.py"
click node_slack_module "https://github.com/parambhatia2004/jack-ryan/blob/main/slack.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_agent,node_config toneBlue
class node_github_monitor,node_jira_monitor toneAmber
class node_incident_files,node_large_change,node_simultaneous_edits,node_done_no_pr,node_sprint_coordination toneMint
class node_db,node_slack_module toneRose
class node_operator,node_github,node_jira,node_slack toneIndigo
```

## Components

### Polling orchestration

- [Polling agent](https://github.com/parambhatia2004/jack-ryan/blob/main/agent.py): `agent.py`
- [Configuration](https://github.com/parambhatia2004/jack-ryan/blob/main/config.py): `config.py`

### Activity collection

- [GitHub monitor](https://github.com/parambhatia2004/jack-ryan/blob/main/monitors/github.py): `monitors/github.py`
- [Jira monitor](https://github.com/parambhatia2004/jack-ryan/blob/main/monitors/jira.py): `monitors/jira.py`

### Risk detection

- [Incident-linked files](https://github.com/parambhatia2004/jack-ryan/blob/main/signals/incident_files.py): `signals/incident_files.py`
- [Large untracked change](https://github.com/parambhatia2004/jack-ryan/blob/main/signals/large_untracked_change.py): `signals/large_untracked_change.py`
- [Simultaneous edits](https://github.com/parambhatia2004/jack-ryan/blob/main/signals/simultaneous_edits.py): `signals/simultaneous_edits.py`
- [Done without PR](https://github.com/parambhatia2004/jack-ryan/blob/main/signals/done_no_pr.py): `signals/done_no_pr.py`
- [Sprint coordination](https://github.com/parambhatia2004/jack-ryan/blob/main/signals/sprint_coordination.py): `signals/sprint_coordination.py`

### State and delivery

- [SQLite state](https://github.com/parambhatia2004/jack-ryan/blob/main/db.py): `db.py`
- [Slack delivery](https://github.com/parambhatia2004/jack-ryan/blob/main/slack.py): `slack.py`

### Other components

- **Operator**
- **GitHub**
- **Jira**
- **Slack**

## Connections

- Operator → Polling agent: starts (evidence: `README.md`)
- Polling agent → GitHub monitor: fetches PRs (evidence: `agent.py`)
- Polling agent → Jira monitor: fetches tickets (evidence: `agent.py`)
- GitHub monitor → GitHub: queries (evidence: `monitors/github.py`)
- Jira monitor → Jira: queries (evidence: `monitors/jira.py`)
- Polling agent → Incident-linked files: runs check (evidence: `agent.py`)
- Polling agent → Large untracked change: runs check (evidence: `agent.py`)
- Polling agent → Simultaneous edits: runs check (evidence: `agent.py`)
- Polling agent → Done without PR: runs check (evidence: `agent.py`)
- Polling agent → Sprint coordination: runs check (evidence: `agent.py`)
- Incident-linked files → SQLite state: reads risk scores (evidence: `signals/incident_files.py`)
- Polling agent → SQLite state: tracks signals (evidence: `agent.py`)
- Polling agent → SQLite state: seeds risk scores (evidence: `agent.py`)
- Polling agent → Jira monitor: fetches PR links (evidence: `agent.py`)
- Polling agent → Slack delivery: posts alerts (evidence: `agent.py`)
- Slack delivery → Slack: sends messages (evidence: `slack.py`)
- Polling agent → Configuration: reads settings (evidence: `agent.py`)
- GitHub monitor → Configuration: reads credentials (evidence: `monitors/github.py`)
- Jira monitor → Configuration: reads credentials (evidence: `monitors/jira.py`)
- Slack delivery → Configuration: reads credentials (evidence: `slack.py`)
- Done without PR → Configuration: reads grace period (evidence: `signals/done_no_pr.py`)
- Sprint coordination → Configuration: reads thresholds (evidence: `signals/sprint_coordination.py`)