# iamkk369/project-risk-agent architecture

> Architecture diagram of the GitHub repository iamkk369/project-risk-agent, 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/iamkk369/project-risk-agent
- Repository: https://github.com/iamkk369/project-risk-agent

## Overview

Project Risk Agent turns authorized GitHub issue data into deterministic, explainable delivery-risk findings and manager-oriented reports, with optional Gemini executive reasoning. The main workflow fetches and parses issues, scores dependency risk, compares bounded history, enriches decisions, then formats a report; portfolio analysis repeats this per repository. Webhooks can trigger a fresh run, while AgentCore, S3, Secrets Manager, and structured logging support optional runtime integrations. The workflow stages are documented in the README; unsampled implementation details and deployment status are not independently verified here.

Main entry points: [`src/risk_agent/main.py`](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/main.py) (CLI Pipeline), [`src/risk_agent/github_tool.py`](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/github_tool.py) (Issue Fetch and Parse), [`src/risk_agent/webhook.py`](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/webhook.py) (Webhook Listener), [`src/risk_agent/risk_engine.py`](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/risk_engine.py) (Risk Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["Risk Analysis"]
  node_github_tool["Issue Fetch and Parse<br/>[github_tool.py]"]
  node_risk["Risk Engine<br/>[risk_engine.py]"]
  node_history[("Risk History<br/>[history.py]")]
  node_decision["Decision Support"]
end

subgraph group_reporting["Reports and Portfolio"]
  node_report["Markdown Report<br/>[report.py]"]
  node_portfolio["Portfolio Analysis<br/>[portfolio.py]"]
end

subgraph group_runtime["Runtime Integrations"]
  node_main["CLI Pipeline<br/>[main.py]"]
  node_agentcore_app["AgentCore Entrypoint<br/>[agentcore_app.py]"]
  node_webhook["Webhook Listener<br/>[webhook.py]"]
  node_event_handler["Event Validation<br/>[event_handler.py]"]
  node_s3_store[("Encrypted S3 Reports<br/>[storage.py]")]
end

subgraph group_operations["Security and Observability"]
  node_security["Credential Resolution<br/>[security.py]"]
  node_observability["Structured Logging<br/>[observability.py]"]
end

node_manager(("Engineering Team"))
node_github{{"GitHub Issues"}}
node_gemini{{"Google Gemini"}}
node_s3[("Amazon S3")]
node_secrets[("Secrets Manager")]

node_manager -->|"starts analysis"| node_main
node_github_tool -->|"fetches issues"| node_github
node_github -->|"returns issue data"| node_github_tool
node_main -->|"runs pipeline"| node_github_tool
node_github_tool -->|"parsed issues"| node_risk
node_main -->|"runs pipeline"| node_risk
node_risk -->|"current risk snapshot"| node_history
node_main -->|"loads and saves"| node_history
node_history -->|"trajectory"| node_decision
node_main -->|"enriches findings"| node_decision
node_decision -->|"decision signals"| node_report
node_main -->|"generates report"| node_report
node_report -->|"presents findings"| node_manager
node_main -->|"runs portfolio mode"| node_portfolio
node_manager -->|"requests portfolio"| node_portfolio
node_main -->|"requests explanation"| node_gemini
node_gemini -->|"explains findings"| node_manager
node_manager -->|"starts listener"| node_webhook
node_webhook -->|"validates event"| node_event_handler
node_webhook -->|"triggers analysis"| node_main
node_manager -.->|"invokes runtime"| node_agentcore_app
node_agentcore_app -->|"uses workflow"| node_main
node_main -->|"persists report"| node_s3_store
node_s3_store -->|"writes encrypted object"| node_s3
node_main -->|"resolves credentials"| node_security
node_security -->|"reads configured secret"| node_secrets
node_main -->|"emits events"| node_observability

click node_main "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/main.py"
click node_github_tool "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/github_tool.py"
click node_risk "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/risk_engine.py"
click node_history "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/history.py"
click node_decision "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/decision_support.py"
click node_report "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/report.py"
click node_portfolio "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/portfolio.py"
click node_agentcore_app "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/agentcore_app.py"
click node_webhook "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/webhook.py"
click node_event_handler "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/event_handler.py"
click node_s3_store "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/storage.py"
click node_security "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/security.py"
click node_observability "https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/observability.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_github_tool,node_risk,node_history,node_decision toneBlue
class node_report,node_portfolio,node_s3,node_secrets toneAmber
class node_main,node_agentcore_app,node_webhook,node_event_handler,node_s3_store toneMint
class node_security,node_observability toneRose
class node_manager,node_github,node_gemini toneIndigo
```

## Components

### Risk Analysis

- [Issue Fetch and Parse](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/github_tool.py): `src/risk_agent/github_tool.py`
- [Risk Engine](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/risk_engine.py): `src/risk_agent/risk_engine.py`
- [Risk History](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/history.py): `src/risk_agent/history.py`
- [Decision Support](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/decision_support.py): `src/risk_agent/decision_support.py`

### Reports and Portfolio

- [Markdown Report](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/report.py): `src/risk_agent/report.py`
- [Portfolio Analysis](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/portfolio.py): `src/risk_agent/portfolio.py`

### Runtime Integrations

- [CLI Pipeline](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/main.py): `src/risk_agent/main.py`
- [AgentCore Entrypoint](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/agentcore_app.py): `src/risk_agent/agentcore_app.py`
- [Webhook Listener](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/webhook.py): `src/risk_agent/webhook.py`
- [Event Validation](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/event_handler.py): `src/risk_agent/event_handler.py`
- [Encrypted S3 Reports](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/storage.py): `src/risk_agent/storage.py`

### Security and Observability

- [Credential Resolution](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/security.py): `src/risk_agent/security.py`
- [Structured Logging](https://github.com/iamkk369/project-risk-agent/blob/main/src/risk_agent/observability.py): `src/risk_agent/observability.py`

### Other components

- **Engineering Team**
- **GitHub Issues**
- **Google Gemini**
- **Amazon S3**
- **Secrets Manager**

## Connections

- Engineering Team → CLI Pipeline: starts analysis (evidence: `README.md`)
- Issue Fetch and Parse → GitHub Issues: fetches issues (evidence: `README.md`)
- GitHub Issues → Issue Fetch and Parse: returns issue data (evidence: `README.md`)
- CLI Pipeline → Issue Fetch and Parse: runs pipeline (evidence: `src/risk_agent/main.py`)
- Issue Fetch and Parse → Risk Engine: parsed issues (evidence: `README.md`)
- CLI Pipeline → Risk Engine: runs pipeline (evidence: `src/risk_agent/main.py`)
- Risk Engine → Risk History: current risk snapshot (evidence: `README.md`)
- CLI Pipeline → Risk History: loads and saves (evidence: `src/risk_agent/main.py`)
- Risk History → Decision Support: trajectory (evidence: `README.md`)
- CLI Pipeline → Decision Support: enriches findings (evidence: `src/risk_agent/main.py`)
- Decision Support → Markdown Report: decision signals (evidence: `README.md`)
- CLI Pipeline → Markdown Report: generates report (evidence: `src/risk_agent/main.py`)
- Markdown Report → Engineering Team: presents findings (evidence: `README.md`)
- CLI Pipeline → Portfolio Analysis: runs portfolio mode (evidence: `src/risk_agent/main.py`)
- Engineering Team → Portfolio Analysis: requests portfolio (evidence: `README.md`)
- CLI Pipeline → Google Gemini: requests explanation (evidence: `README.md`)
- Google Gemini → Engineering Team: explains findings (evidence: `README.md`)
- Engineering Team → Webhook Listener: starts listener (evidence: `README.md`)
- Webhook Listener → Event Validation: validates event (evidence: `src/risk_agent/webhook.py`)
- Webhook Listener → CLI Pipeline: triggers analysis (evidence: `src/risk_agent/webhook.py`)
- Engineering Team → AgentCore Entrypoint: invokes runtime (evidence: `README.md`)
- AgentCore Entrypoint → CLI Pipeline: uses workflow (evidence: `src/risk_agent/agentcore_app.py`)
- CLI Pipeline → Encrypted S3 Reports: persists report (evidence: `src/risk_agent/main.py`)
- Encrypted S3 Reports → Amazon S3: writes encrypted object (evidence: `src/risk_agent/storage.py`)
- CLI Pipeline → Credential Resolution: resolves credentials (evidence: `src/risk_agent/main.py`)
- Credential Resolution → Secrets Manager: reads configured secret (evidence: `src/risk_agent/security.py`)
- CLI Pipeline → Structured Logging: emits events (evidence: `src/risk_agent/main.py`)