# maheesh09/synkron-backend architecture

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

- Interactive diagram: https://gitdiagram.com/maheesh09/synkron-backend
- Repository: https://github.com/maheesh09/synkron-backend

## Overview

Synkron is a FastAPI backend for turning repository pushes into documentation-update pull requests, with a dashboard and a feedback loop that learns from merged edits. The principal workflow validates and filters GitHub webhook events, dispatches accepted work, analyzes code changes, identifies affected documentation, rewrites it, and opens a pull request. Pipeline runs and feedback are persisted in MongoDB. The README describes GitLab, but the sampled runtime code uses GitHub webhook signatures, GitHub App authentication, and pull requests; unsampled dashboard and feedback internals are represented only at their documented boundaries.

Main entry points: [`app/agents/orchestrator.py`](https://github.com/maheesh09/synkron-backend/blob/main/app/agents/orchestrator.py) (Pipeline orchestrator), [`app/services/github.py`](https://github.com/maheesh09/synkron-backend/blob/main/app/services/github.py) (GitHub client), [`app/routers/webhook.py`](https://github.com/maheesh09/synkron-backend/blob/main/app/routers/webhook.py) (Webhook handler), [`app/database.py`](https://github.com/maheesh09/synkron-backend/blob/main/app/database.py) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Webhook and API"]
  node_webhook["Webhook handler<br/>[webhook.py]"]
  node_internal_api["Internal API<br/>[pipeline.py]"]
  node_rate_limit["Rate limiting<br/>[rate_limit.py]"]
end

subgraph group_pipeline["Documentation pipeline"]
  node_orchestrator["Pipeline orchestrator<br/>[orchestrator.py]"]
  node_analyzer["Code analyzer<br/>[code_analyzer.py]"]
  node_impact_mapper["Impact mapper<br/>[impact_mapper.py]"]
  node_doc_writer["Document writer<br/>[doc_writer.py]"]
  node_pr_creator["Pull request creator<br/>[pr_creator.py]"]
end

subgraph group_integrations["External integrations"]
  node_task_dispatch["Task dispatch<br/>[cloud_tasks.py]"]
  node_github_client["GitHub client<br/>[github.py]"]
  node_github_auth["GitHub App auth<br/>[github_auth.py]"]
  node_gemini["Gemini service<br/>[gemini.py]"]
end

subgraph group_state["Persistence and feedback"]
  node_database["Database access<br/>[database.py]"]
  node_feedback["Feedback processing<br/>[feedback.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_api["Dashboard API<br/>[dashboard.py]"]
  node_auth["User authentication<br/>[auth.py]"]
end

node_developer(("Developer"))
node_github(("GitHub"))
node_cloud_tasks["Cloud Tasks"]
node_gemini_api(("Gemini API"))
node_mongo[("MongoDB")]
node_firebase(("Firebase Auth"))

node_developer -->|"pushes code"| node_github
node_github -->|"sends events"| node_webhook
node_webhook -->|"enqueues work"| node_task_dispatch
node_webhook -->|"records deliveries"| node_database
node_webhook -->|"checks quota"| node_rate_limit
node_task_dispatch -->|"creates tasks"| node_cloud_tasks
node_cloud_tasks -->|"posts work"| node_internal_api
node_task_dispatch -.->|"starts locally"| node_orchestrator
node_internal_api -->|"runs pipeline"| node_orchestrator
node_internal_api -->|"processes feedback"| node_feedback
node_orchestrator -->|"records runs"| node_database
node_orchestrator -->|"runs first"| node_analyzer
node_orchestrator -->|"maps affected docs"| node_impact_mapper
node_orchestrator -->|"rewrites sections"| node_doc_writer
node_orchestrator -->|"opens pull request"| node_pr_creator
node_analyzer -->|"reads changes"| node_github_client
node_impact_mapper -->|"scans documentation"| node_github_client
node_doc_writer -->|"reads repository docs"| node_github_client
node_doc_writer -->|"requests rewrites"| node_gemini
node_pr_creator -->|"creates branch and PR"| node_github_client
node_pr_creator -->|"writes PR description"| node_gemini
node_github_client -->|"gets installation token"| node_github_auth
node_github_client -->|"uses repository API"| node_github
node_gemini -->|"sends prompts"| node_gemini_api
node_database -->|"reads and writes"| node_mongo
node_feedback -->|"stores corrections"| node_database
node_feedback -->|"reads merged changes"| node_github_client
node_github -->|"reports merged PRs"| node_webhook
node_developer -->|"uses dashboard"| node_dashboard_api
node_dashboard_api -->|"verifies user"| node_auth
node_auth -->|"validates token"| node_firebase
node_dashboard_api -->|"reads repository data"| node_database

click node_webhook "https://github.com/maheesh09/synkron-backend/blob/main/app/routers/webhook.py"
click node_internal_api "https://github.com/maheesh09/synkron-backend/blob/main/app/routers/pipeline.py"
click node_task_dispatch "https://github.com/maheesh09/synkron-backend/blob/main/app/services/cloud_tasks.py"
click node_orchestrator "https://github.com/maheesh09/synkron-backend/blob/main/app/agents/orchestrator.py"
click node_analyzer "https://github.com/maheesh09/synkron-backend/blob/main/app/agents/code_analyzer.py"
click node_impact_mapper "https://github.com/maheesh09/synkron-backend/blob/main/app/agents/impact_mapper.py"
click node_doc_writer "https://github.com/maheesh09/synkron-backend/blob/main/app/agents/doc_writer.py"
click node_pr_creator "https://github.com/maheesh09/synkron-backend/blob/main/app/agents/pr_creator.py"
click node_github_client "https://github.com/maheesh09/synkron-backend/blob/main/app/services/github.py"
click node_github_auth "https://github.com/maheesh09/synkron-backend/blob/main/app/services/github_auth.py"
click node_gemini "https://github.com/maheesh09/synkron-backend/blob/main/app/services/gemini.py"
click node_database "https://github.com/maheesh09/synkron-backend/blob/main/app/database.py"
click node_feedback "https://github.com/maheesh09/synkron-backend/blob/main/app/services/feedback.py"
click node_dashboard_api "https://github.com/maheesh09/synkron-backend/blob/main/app/routers/dashboard.py"
click node_auth "https://github.com/maheesh09/synkron-backend/blob/main/app/auth.py"
click node_rate_limit "https://github.com/maheesh09/synkron-backend/blob/main/app/services/rate_limit.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_webhook,node_internal_api,node_rate_limit toneBlue
class node_orchestrator,node_analyzer,node_impact_mapper,node_doc_writer,node_pr_creator,node_mongo toneAmber
class node_task_dispatch,node_github_client,node_github_auth,node_gemini,node_gemini_api toneMint
class node_database,node_feedback,node_cloud_tasks toneRose
class node_dashboard_api,node_auth,node_developer,node_github,node_firebase toneIndigo
```

## Components

### Webhook and API

- [Webhook handler](https://github.com/maheesh09/synkron-backend/blob/main/app/routers/webhook.py): `app/routers/webhook.py`
- [Internal API](https://github.com/maheesh09/synkron-backend/blob/main/app/routers/pipeline.py): `app/routers/pipeline.py`
- [Rate limiting](https://github.com/maheesh09/synkron-backend/blob/main/app/services/rate_limit.py): `app/services/rate_limit.py`

### Documentation pipeline

- [Pipeline orchestrator](https://github.com/maheesh09/synkron-backend/blob/main/app/agents/orchestrator.py): `app/agents/orchestrator.py`
- [Code analyzer](https://github.com/maheesh09/synkron-backend/blob/main/app/agents/code_analyzer.py): `app/agents/code_analyzer.py`
- [Impact mapper](https://github.com/maheesh09/synkron-backend/blob/main/app/agents/impact_mapper.py): `app/agents/impact_mapper.py`
- [Document writer](https://github.com/maheesh09/synkron-backend/blob/main/app/agents/doc_writer.py): `app/agents/doc_writer.py`
- [Pull request creator](https://github.com/maheesh09/synkron-backend/blob/main/app/agents/pr_creator.py): `app/agents/pr_creator.py`

### External integrations

- [Task dispatch](https://github.com/maheesh09/synkron-backend/blob/main/app/services/cloud_tasks.py): `app/services/cloud_tasks.py`
- [GitHub client](https://github.com/maheesh09/synkron-backend/blob/main/app/services/github.py): `app/services/github.py`
- [GitHub App auth](https://github.com/maheesh09/synkron-backend/blob/main/app/services/github_auth.py): `app/services/github_auth.py`
- [Gemini service](https://github.com/maheesh09/synkron-backend/blob/main/app/services/gemini.py): `app/services/gemini.py`

### Persistence and feedback

- [Database access](https://github.com/maheesh09/synkron-backend/blob/main/app/database.py): `app/database.py`
- [Feedback processing](https://github.com/maheesh09/synkron-backend/blob/main/app/services/feedback.py): `app/services/feedback.py`

### Dashboard

- [Dashboard API](https://github.com/maheesh09/synkron-backend/blob/main/app/routers/dashboard.py): `app/routers/dashboard.py`
- [User authentication](https://github.com/maheesh09/synkron-backend/blob/main/app/auth.py): `app/auth.py`

### Other components

- **Developer**
- **GitHub**
- **Cloud Tasks**
- **Gemini API**
- **MongoDB**
- **Firebase Auth**

## Connections

- Developer → GitHub: pushes code
- GitHub → Webhook handler: sends events
- Webhook handler → Task dispatch: enqueues work
- Webhook handler → Database access: records deliveries
- Webhook handler → Rate limiting: checks quota
- Task dispatch → Cloud Tasks: creates tasks
- Cloud Tasks → Internal API: posts work
- Task dispatch → Pipeline orchestrator: starts locally
- Internal API → Pipeline orchestrator: runs pipeline
- Internal API → Feedback processing: processes feedback
- Pipeline orchestrator → Database access: records runs
- Pipeline orchestrator → Code analyzer: runs first
- Pipeline orchestrator → Impact mapper: maps affected docs
- Pipeline orchestrator → Document writer: rewrites sections
- Pipeline orchestrator → Pull request creator: opens pull request
- Code analyzer → GitHub client: reads changes
- Impact mapper → GitHub client: scans documentation
- Document writer → GitHub client: reads repository docs
- Document writer → Gemini service: requests rewrites
- Pull request creator → GitHub client: creates branch and PR
- Pull request creator → Gemini service: writes PR description
- GitHub client → GitHub App auth: gets installation token
- GitHub client → GitHub: uses repository API
- Gemini service → Gemini API: sends prompts
- Database access → MongoDB: reads and writes
- Feedback processing → Database access: stores corrections
- Feedback processing → GitHub client: reads merged changes
- GitHub → Webhook handler: reports merged PRs
- Developer → Dashboard API: uses dashboard
- Dashboard API → User authentication: verifies user
- User authentication → Firebase Auth: validates token
- Dashboard API → Database access: reads repository data