# anthropicbots/hiero-bot-py architecture

> Architecture diagram of the GitHub repository anthropicbots/hiero-bot-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anthropicbots/hiero-bot-py
- Repository: https://github.com/anthropicbots/hiero-bot-py

## Overview

hydra-maintainer is a self-hosted GitHub App for maintainer operations. GitHub webhook deliveries are verified and dispatched through repository configuration into workflows for onboarding, PR quality and health, reviewer handling, contributor progression, and issue management; those workflows act through the GitHub client and persist results for audit and API queries. Optional AI review uses a provider backend layer. The graph also includes scheduled stale-issue work and authenticated REST access. Some workflow links rely on the SOURCE INDEX or README rather than complete source excerpts; uncertain implementation details are omitted.

Main entry points: [`app/github/webhooks.py`](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/github/webhooks.py) (Webhook router), [`app/github/client.py`](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/github/client.py) (GitHub client), [`app/utils/audit.py`](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/utils/audit.py) (Audit trail), [`app/workflows/pullrequest.py`](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/pullrequest.py) (PR gates and review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["App ingress"]
  node_app["FastAPI app<br/>[main.py]"]
  node_webhooks["Webhook router<br/>[webhooks.py]"]
  node_scheduler["Scheduled jobs<br/>[jobs.py]"]
end

subgraph group_maintainer["Maintainer workflows"]
  node_onboarding["Contributor onboarding<br/>[onboarding.py]"]
  node_pullrequest["PR gates and review<br/>[pullrequest.py]"]
  node_prhealth["PR health scoring<br/>[prhealth.py]"]
  node_review_assignment["Reviewer assignment"]
  node_progression["Contributor progression<br/>[progression.py]"]
  node_issues["Issue management<br/>[issuemanagement.py]"]
end

subgraph group_platform["Shared platform"]
  node_config["Repo configuration<br/>[loader.py]"]
  node_github_client["GitHub client<br/>[client.py]"]
  node_database["Database sessions<br/>[database.py]"]
  node_records[("Persistent records<br/>[models.py]")]
  node_audit["Audit trail<br/>[audit.py]"]
end

subgraph group_ai["AI review"]
  node_reviewer["AI review orchestration<br/>[reviewer.py]"]
  node_registry["Backend registry<br/>[registry.py]"]
  node_backend_contract["Backend contract<br/>[base.py]"]
  node_provider_backends["AI providers"]
end

subgraph group_access["API and identity"]
  node_api["REST API<br/>[routes.py]"]
  node_auth["OAuth and sessions<br/>[oauth.py]"]
  node_auth_dependencies["Route authentication<br/>[dependencies.py]"]
end

node_github(("GitHub"))

node_github -->|"sends events"| node_webhooks
node_app -->|"registers router"| node_webhooks
node_app -->|"registers routes"| node_api
node_app -->|"starts jobs"| node_scheduler
node_webhooks -->|"loads repo config"| node_config
node_config -->|"fetches config"| node_github_client
node_webhooks -->|"dispatches events"| node_onboarding
node_webhooks -->|"dispatches events"| node_pullrequest
node_webhooks -->|"dispatches events"| node_prhealth
node_webhooks -->|"dispatches events"| node_progression
node_webhooks -->|"dispatches events"| node_issues
node_webhooks -->|"dispatches events"| node_review_assignment
node_scheduler -->|"runs stale scans"| node_issues
node_onboarding -->|"acts on GitHub"| node_github_client
node_pullrequest -->|"acts on GitHub"| node_github_client
node_prhealth -->|"posts scorecards"| node_github_client
node_review_assignment -->|"requests reviewers"| node_github_client
node_progression -->|"acts on GitHub"| node_github_client
node_issues -->|"acts on GitHub"| node_github_client
node_github_client -->|"calls API"| node_github
node_pullrequest -->|"requests AI review"| node_reviewer
node_reviewer -->|"selects backend"| node_registry
node_registry -->|"creates providers"| node_provider_backends
node_provider_backends -->|"implements contract"| node_backend_contract
node_api -->|"requires identity"| node_auth_dependencies
node_auth_dependencies -->|"gets database session"| node_database
node_api -->|"queries records"| node_database
node_database -->|"persists models"| node_records
node_auth -->|"stores user sessions"| node_records
node_onboarding -->|"records actions"| node_audit
node_pullrequest -->|"records actions"| node_audit
node_prhealth -->|"records actions"| node_audit
node_review_assignment -->|"records actions"| node_audit
node_progression -->|"records actions"| node_audit
node_issues -->|"records actions"| node_audit
node_audit -->|"writes audit entries"| node_records

click node_app "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/main.py"
click node_webhooks "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/github/webhooks.py"
click node_scheduler "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/scheduler/jobs.py"
click node_config "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/config/loader.py"
click node_github_client "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/github/client.py"
click node_onboarding "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/onboarding.py"
click node_pullrequest "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/pullrequest.py"
click node_prhealth "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/prhealth.py"
click node_review_assignment "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/reviewerassignment.py"
click node_progression "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/progression.py"
click node_issues "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/issuemanagement.py"
click node_reviewer "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/ai/reviewer.py"
click node_registry "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/ai/backends/registry.py"
click node_backend_contract "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/ai/backends/base.py"
click node_provider_backends "https://github.com/anthropicbots/hiero-bot-py/tree/main/app/ai/backends"
click node_database "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/db/database.py"
click node_records "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/db/models.py"
click node_audit "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/utils/audit.py"
click node_api "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/api/routes.py"
click node_auth "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/auth/oauth.py"
click node_auth_dependencies "https://github.com/anthropicbots/hiero-bot-py/blob/main/app/auth/dependencies.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_app,node_webhooks,node_scheduler toneBlue
class node_onboarding,node_pullrequest,node_prhealth,node_review_assignment,node_progression,node_issues toneAmber
class node_config,node_github_client,node_database,node_records,node_audit toneMint
class node_reviewer,node_registry,node_backend_contract,node_provider_backends toneRose
class node_api,node_auth,node_auth_dependencies,node_github toneIndigo
```

## Components

### App ingress

- [FastAPI app](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/main.py): `app/main.py`
- [Webhook router](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/github/webhooks.py): `app/github/webhooks.py`
- [Scheduled jobs](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/scheduler/jobs.py): `app/scheduler/jobs.py`

### Maintainer workflows

- [Contributor onboarding](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/onboarding.py): `app/workflows/onboarding.py`
- [PR gates and review](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/pullrequest.py): `app/workflows/pullrequest.py`
- [PR health scoring](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/prhealth.py): `app/workflows/prhealth.py`
- [Reviewer assignment](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/reviewerassignment.py): `app/workflows/reviewerassignment.py`
- [Contributor progression](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/progression.py): `app/workflows/progression.py`
- [Issue management](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/workflows/issuemanagement.py): `app/workflows/issuemanagement.py`

### Shared platform

- [Repo configuration](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/config/loader.py): `app/config/loader.py`
- [GitHub client](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/github/client.py): `app/github/client.py`
- [Database sessions](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/db/database.py): `app/db/database.py`
- [Persistent records](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/db/models.py): `app/db/models.py`
- [Audit trail](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/utils/audit.py): `app/utils/audit.py`

### AI review

- [AI review orchestration](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/ai/reviewer.py): `app/ai/reviewer.py`
- [Backend registry](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/ai/backends/registry.py): `app/ai/backends/registry.py`
- [Backend contract](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/ai/backends/base.py): `app/ai/backends/base.py`
- [AI providers](https://github.com/anthropicbots/hiero-bot-py/tree/main/app/ai/backends): `app/ai/backends`

### API and identity

- [REST API](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/api/routes.py): `app/api/routes.py`
- [OAuth and sessions](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/auth/oauth.py): `app/auth/oauth.py`
- [Route authentication](https://github.com/anthropicbots/hiero-bot-py/blob/main/app/auth/dependencies.py): `app/auth/dependencies.py`

### Other components

- **GitHub**

## Connections

- GitHub → Webhook router: sends events
- FastAPI app → Webhook router: registers router (evidence: `app/main.py`)
- FastAPI app → REST API: registers routes (evidence: `app/main.py`)
- FastAPI app → Scheduled jobs: starts jobs (evidence: `app/main.py`)
- Webhook router → Repo configuration: loads repo config (evidence: `app/github/webhooks.py`)
- Repo configuration → GitHub client: fetches config (evidence: `app/config/loader.py`)
- Webhook router → Contributor onboarding: dispatches events (evidence: `app/github/webhooks.py`)
- Webhook router → PR gates and review: dispatches events (evidence: `app/github/webhooks.py`)
- Webhook router → PR health scoring: dispatches events (evidence: `app/github/webhooks.py`)
- Webhook router → Contributor progression: dispatches events (evidence: `app/github/webhooks.py`)
- Webhook router → Issue management: dispatches events (evidence: `app/github/webhooks.py`)
- Webhook router → Reviewer assignment: dispatches events (evidence: `app/github/webhooks.py`)
- Scheduled jobs → Issue management: runs stale scans (evidence: `app/scheduler/jobs.py`)
- Contributor onboarding → GitHub client: acts on GitHub (evidence: `app/workflows/onboarding.py`)
- PR gates and review → GitHub client: acts on GitHub (evidence: `app/workflows/pullrequest.py`)
- PR health scoring → GitHub client: posts scorecards (evidence: `app/workflows/prhealth.py`)
- Reviewer assignment → GitHub client: requests reviewers (evidence: `app/workflows/reviewerassignment.py`)
- Contributor progression → GitHub client: acts on GitHub (evidence: `app/workflows/progression.py`)
- Issue management → GitHub client: acts on GitHub (evidence: `app/workflows/issuemanagement.py`)
- GitHub client → GitHub: calls API (evidence: `app/github/client.py`)
- PR gates and review → AI review orchestration: requests AI review (evidence: `app/workflows/pullrequest.py`)
- AI review orchestration → Backend registry: selects backend (evidence: `app/ai/reviewer.py`)
- Backend registry → AI providers: creates providers (evidence: `app/ai/backends/registry.py`)
- AI providers → Backend contract: implements contract (evidence: `app/ai/backends/base.py`)
- REST API → Route authentication: requires identity (evidence: `app/api/routes.py`)
- Route authentication → Database sessions: gets database session (evidence: `app/auth/dependencies.py`)
- REST API → Database sessions: queries records (evidence: `app/api/routes.py`)
- Database sessions → Persistent records: persists models (evidence: `app/db/database.py`)
- OAuth and sessions → Persistent records: stores user sessions (evidence: `app/auth/oauth.py`)
- Contributor onboarding → Audit trail: records actions (evidence: `app/workflows/onboarding.py`)
- PR gates and review → Audit trail: records actions (evidence: `app/workflows/pullrequest.py`)
- PR health scoring → Audit trail: records actions (evidence: `app/workflows/prhealth.py`)
- Reviewer assignment → Audit trail: records actions (evidence: `app/workflows/reviewerassignment.py`)
- Contributor progression → Audit trail: records actions (evidence: `app/workflows/progression.py`)
- Issue management → Audit trail: records actions (evidence: `app/workflows/issuemanagement.py`)
- Audit trail → Persistent records: writes audit entries (evidence: `app/utils/audit.py`)
