# heysagnik/aethos architecture

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

- Interactive diagram: https://gitdiagram.com/heysagnik/aethos
- Repository: https://github.com/heysagnik/aethos

## Overview

Aethos is a GitHub pull-request review service: users install its GitHub App, mention @aethos-agent, and receive a code-computed merge-readiness verdict with inline findings. The main path triages a PR, assembles an inspectable context pack using the code index, requests structured model findings, computes the verdict, and posts a GitHub review. The dashboard exposes repositories, review history, settings, and pack details. Edges reflect excerpted calls or README workflow statements; indexing and frontend-to-API wiring are documented or apparent from API paths, but their implementation details were not sampled.

Main entry points: [`backend/apps/reviews/pipeline.py`](https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/pipeline.py) (Review orchestration), [`backend/apps/dashboard/api.py`](https://github.com/heysagnik/aethos/blob/main/backend/apps/dashboard/api.py) (Dashboard API), [`backend/apps/github/handlers.py`](https://github.com/heysagnik/aethos/blob/main/backend/apps/github/handlers.py) (GitHub event handlers), [`backend/apps/repos/services.py`](https://github.com/heysagnik/aethos/blob/main/backend/apps/repos/services.py) (Repository lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Identity &amp; Repositories"]
  node_accounts["OAuth &amp; membership<br/>[services.py]"]
  node_repos["Repository lifecycle<br/>[services.py]"]
  node_repo_store[("Repository records<br/>[models.py]")]
end

subgraph group_indexing["Code Index"]
  node_index_build["Index construction<br/>[indexer.py]"]
  node_code_parse["Code parsing &amp; graph<br/>[parse.py]"]
  node_index_services["Index lookup &amp; jobs<br/>[services.py]"]
  node_index_store[("Symbols &amp; embeddings<br/>[models.py]")]
end

subgraph group_review["Review Pipeline"]
  node_webhooks["GitHub event handlers<br/>[handlers.py]"]
  node_triage["PR triage<br/>[triage.py]"]
  node_packing["Context pack<br/>[pack.py]"]
  node_context["Context selection<br/>[context.py]"]
  node_review_pipeline["Review orchestration<br/>[pipeline.py]"]
  node_review_queue["Review step queue<br/>[queue.py]"]
  node_llm["Structured review call<br/>[llm.py]"]
  node_verdict["Verdict &amp; reasons<br/>[verdict.py]"]
  node_review_store[("Reviews &amp; findings<br/>[models.py]")]
end

subgraph group_integrations["External Services"]
  node_github(("GitHub"))
  node_qstash["QStash"]
  node_nim(("NVIDIA NIM"))
  node_gh_client["GitHub gateway<br/>[client.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_api["Dashboard API<br/>[api.py]"]
  node_dashboard_data["Dashboard selectors<br/>[selectors.py]"]
  node_web_app["Dashboard pages"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
  node_api_routes["API routing<br/>[urls.py]"]
  node_django_entry["Django API entry<br/>[index.py]"]
end

node_developer(("GitHub user"))

node_developer -->|"signs in"| node_accounts
node_accounts -->|"links installations"| node_repos
node_repos -->|"syncs repositories"| node_gh_client
node_webhooks -->|"updates lifecycle"| node_repos
node_webhooks -->|"enqueues review"| node_review_queue
node_webhooks -->|"receives events"| node_github
node_review_queue -->|"dispatches steps"| node_review_pipeline
node_review_pipeline -->|"fetches PR data"| node_gh_client
node_review_pipeline -->|"triages diff"| node_triage
node_review_pipeline -->|"builds context"| node_context
node_context -.->|"looks up index"| node_index_services
node_index_build -.->|"parses source"| node_code_parse
node_index_build -->|"stores chunks"| node_index_store
node_review_pipeline -->|"packs context"| node_packing
node_packing -->|"returns pack"| node_review_pipeline
node_review_pipeline -->|"requests findings"| node_llm
node_llm -.->|"calls model"| node_nim
node_review_pipeline -->|"computes verdict"| node_verdict
node_review_pipeline -->|"saves review"| node_review_store
node_review_pipeline -->|"posts review"| node_gh_client
node_developer -->|"inspects reviews"| node_web_app
node_web_app -->|"requests review"| node_frontend_api
node_frontend_api -->|"calls endpoints"| node_api_routes
node_django_entry -->|"serves routes"| node_api_routes
node_api_routes -->|"routes dashboard"| node_dashboard_api
node_dashboard_api -.->|"reads dashboard data"| node_dashboard_data
node_dashboard_api -.->|"serves reviews"| node_review_store
node_dashboard_api -.->|"serves repositories"| node_repo_store

click node_accounts "https://github.com/heysagnik/aethos/blob/main/backend/apps/accounts/services.py"
click node_repos "https://github.com/heysagnik/aethos/blob/main/backend/apps/repos/services.py"
click node_repo_store "https://github.com/heysagnik/aethos/blob/main/backend/apps/repos/models.py"
click node_webhooks "https://github.com/heysagnik/aethos/blob/main/backend/apps/github/handlers.py"
click node_gh_client "https://github.com/heysagnik/aethos/blob/main/backend/apps/github/client.py"
click node_index_build "https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/indexer.py"
click node_code_parse "https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/code/parse.py"
click node_index_services "https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/services.py"
click node_index_store "https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/models.py"
click node_triage "https://github.com/heysagnik/aethos/blob/main/backend/core/triage.py"
click node_packing "https://github.com/heysagnik/aethos/blob/main/backend/core/pack.py"
click node_context "https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/context.py"
click node_review_pipeline "https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/pipeline.py"
click node_review_queue "https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/queue.py"
click node_llm "https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/llm.py"
click node_verdict "https://github.com/heysagnik/aethos/blob/main/backend/core/verdict.py"
click node_review_store "https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/models.py"
click node_dashboard_api "https://github.com/heysagnik/aethos/blob/main/backend/apps/dashboard/api.py"
click node_dashboard_data "https://github.com/heysagnik/aethos/blob/main/backend/apps/dashboard/selectors.py"
click node_web_app "https://github.com/heysagnik/aethos/blob/main/frontend/src/pages/ReviewDetailPage.tsx"
click node_frontend_api "https://github.com/heysagnik/aethos/blob/main/frontend/src/lib/api.ts"
click node_api_routes "https://github.com/heysagnik/aethos/blob/main/backend/aethos/urls.py"
click node_django_entry "https://github.com/heysagnik/aethos/blob/main/api/index.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_accounts,node_repos,node_repo_store,node_developer toneBlue
class node_index_build,node_code_parse,node_index_services,node_index_store toneAmber
class node_webhooks,node_triage,node_packing,node_context,node_review_pipeline,node_review_queue,node_llm,node_verdict,node_review_store toneMint
class node_github,node_qstash,node_nim,node_gh_client toneRose
class node_dashboard_api,node_dashboard_data,node_web_app,node_frontend_api,node_api_routes,node_django_entry toneIndigo
```

## Components

### Identity & Repositories

- [OAuth & membership](https://github.com/heysagnik/aethos/blob/main/backend/apps/accounts/services.py): `backend/apps/accounts/services.py`
- [Repository lifecycle](https://github.com/heysagnik/aethos/blob/main/backend/apps/repos/services.py): `backend/apps/repos/services.py`
- [Repository records](https://github.com/heysagnik/aethos/blob/main/backend/apps/repos/models.py): `backend/apps/repos/models.py`

### Code Index

- [Index construction](https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/indexer.py): `backend/apps/indexing/indexer.py`
- [Code parsing & graph](https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/code/parse.py): `backend/apps/indexing/code/parse.py`
- [Index lookup & jobs](https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/services.py): `backend/apps/indexing/services.py`
- [Symbols & embeddings](https://github.com/heysagnik/aethos/blob/main/backend/apps/indexing/models.py): `backend/apps/indexing/models.py`

### Review Pipeline

- [GitHub event handlers](https://github.com/heysagnik/aethos/blob/main/backend/apps/github/handlers.py): `backend/apps/github/handlers.py`
- [PR triage](https://github.com/heysagnik/aethos/blob/main/backend/core/triage.py): `backend/core/triage.py`
- [Context pack](https://github.com/heysagnik/aethos/blob/main/backend/core/pack.py): `backend/core/pack.py`
- [Context selection](https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/context.py): `backend/apps/reviews/context.py`
- [Review orchestration](https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/pipeline.py): `backend/apps/reviews/pipeline.py`
- [Review step queue](https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/queue.py): `backend/apps/reviews/queue.py`
- [Structured review call](https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/llm.py): `backend/apps/reviews/llm.py`
- [Verdict & reasons](https://github.com/heysagnik/aethos/blob/main/backend/core/verdict.py): `backend/core/verdict.py`
- [Reviews & findings](https://github.com/heysagnik/aethos/blob/main/backend/apps/reviews/models.py): `backend/apps/reviews/models.py`

### External Services

- **GitHub**
- **QStash**
- **NVIDIA NIM**
- [GitHub gateway](https://github.com/heysagnik/aethos/blob/main/backend/apps/github/client.py): `backend/apps/github/client.py`

### Dashboard

- [Dashboard API](https://github.com/heysagnik/aethos/blob/main/backend/apps/dashboard/api.py): `backend/apps/dashboard/api.py`
- [Dashboard selectors](https://github.com/heysagnik/aethos/blob/main/backend/apps/dashboard/selectors.py): `backend/apps/dashboard/selectors.py`
- [Dashboard pages](https://github.com/heysagnik/aethos/blob/main/frontend/src/pages/ReviewDetailPage.tsx): `frontend/src/pages/ReviewDetailPage.tsx`
- [Frontend API client](https://github.com/heysagnik/aethos/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [API routing](https://github.com/heysagnik/aethos/blob/main/backend/aethos/urls.py): `backend/aethos/urls.py`
- [Django API entry](https://github.com/heysagnik/aethos/blob/main/api/index.py): `api/index.py`

### Other components

- **GitHub user**

## Connections

- GitHub user → OAuth & membership: signs in (evidence: `backend/apps/accounts/services.py`)
- OAuth & membership → Repository lifecycle: links installations (evidence: `backend/apps/accounts/services.py`)
- Repository lifecycle → GitHub gateway: syncs repositories (evidence: `backend/apps/repos/services.py`)
- GitHub event handlers → Repository lifecycle: updates lifecycle (evidence: `backend/apps/github/handlers.py`)
- GitHub event handlers → Review step queue: enqueues review (evidence: `backend/apps/github/handlers.py`)
- GitHub event handlers → GitHub: receives events (evidence: `README.md`)
- Review step queue → Review orchestration: dispatches steps (evidence: `backend/apps/reviews/queue.py`)
- Review orchestration → GitHub gateway: fetches PR data (evidence: `backend/apps/reviews/pipeline.py`)
- Review orchestration → PR triage: triages diff (evidence: `backend/apps/reviews/pipeline.py`)
- Review orchestration → Context selection: builds context (evidence: `backend/apps/reviews/pipeline.py`)
- Context selection → Index lookup & jobs: looks up index
- Index construction → Code parsing & graph: parses source
- Index construction → Symbols & embeddings: stores chunks
- Review orchestration → Context pack: packs context (evidence: `backend/apps/reviews/pipeline.py`)
- Context pack → Review orchestration: returns pack (evidence: `backend/apps/reviews/pipeline.py`)
- Review orchestration → Structured review call: requests findings (evidence: `backend/apps/reviews/pipeline.py`)
- Structured review call → NVIDIA NIM: calls model
- Review orchestration → Verdict & reasons: computes verdict (evidence: `backend/apps/reviews/pipeline.py`)
- Review orchestration → Reviews & findings: saves review (evidence: `backend/apps/reviews/pipeline.py`)
- Review orchestration → GitHub gateway: posts review (evidence: `README.md`)
- GitHub user → Dashboard pages: inspects reviews (evidence: `README.md`)
- Dashboard pages → Frontend API client: requests review (evidence: `frontend/src/pages/ReviewDetailPage.tsx`)
- Frontend API client → API routing: calls endpoints (evidence: `frontend/src/lib/api.ts`)
- Django API entry → API routing: serves routes (evidence: `api/index.py`)
- API routing → Dashboard API: routes dashboard (evidence: `backend/aethos/urls.py`)
- Dashboard API → Dashboard selectors: reads dashboard data
- Dashboard API → Reviews & findings: serves reviews
- Dashboard API → Repository records: serves repositories
