# kalyanm45/gitpulse architecture

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

- Interactive diagram: https://gitdiagram.com/kalyanm45/gitpulse
- Repository: https://github.com/kalyanm45/gitpulse

## Overview

GitPulse tracks a configured GitHub account: a manual API sync or scheduled job refreshes its profile, followers, following, repositories, and contributions, then records sync state in MongoDB. The frontend presents audience history, repository analytics, and contribution/dashboard views. The backend call paths are supported by excerpts or the SOURCE INDEX; frontend-to-API wiring and several unsampled UI details are not shown, so those links are omitted.

Main entry points: [`backend/app/routes/followers.py`](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/followers.py) (Manual sync route), [`backend/app/main.py`](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/database.py`](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/database.py) (MongoDB), [`backend/app/services/github_service.py`](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/github_service.py) (GitHub client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_scheduler["Sync scheduler<br/>[scheduler.py]"]
end

subgraph group_sync["Sync and collection"]
  node_follower_sync["Follower sync/history"]
  node_following_sync["Following sync"]
  node_repo_sync["Repository analytics<br/>[repo_service.py]"]
  node_contrib_sync["Contribution analytics"]
  node_profile["Profile cache<br/>[profile_service.py]"]
  node_github_client["GitHub client<br/>[github_service.py]"]
  node_sync_state["Sync state<br/>[sync_state.py]"]
end

subgraph group_analytics["Analytics API"]
  node_manual_sync["Manual sync route<br/>[followers.py]"]
  node_follower_routes["Audience routes<br/>[followers.py]"]
  node_repo_routes["Repository routes<br/>[repos.py]"]
  node_contrib_routes["Contribution routes<br/>[contributions.py]"]
end

subgraph group_storage["Persistence"]
  node_mongo[("MongoDB<br/>[database.py]")]
  node_indexes["Database indexes<br/>[indexes.py]"]
end

subgraph group_ui["Dashboard UI"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
  node_audience_ui["Audience views<br/>[page.tsx]"]
  node_dashboard_ui["Dashboard views<br/>[page.tsx]"]
  node_repos_ui["Repository views<br/>[page.tsx]"]
end

node_user(("Account owner"))
node_github{{"GitHub REST API"}}

node_user -.->|"requests sync"| node_manual_sync
node_fastapi -->|"mounts routes"| node_follower_routes
node_fastapi -->|"mounts routes"| node_repo_routes
node_fastapi -->|"mounts routes"| node_contrib_routes
node_fastapi -->|"starts scheduler"| node_scheduler
node_manual_sync -->|"refreshes profile"| node_profile
node_manual_sync -->|"syncs followers"| node_follower_sync
node_manual_sync -->|"syncs following"| node_following_sync
node_manual_sync -->|"syncs repositories"| node_repo_sync
node_manual_sync -->|"syncs contributions"| node_contrib_sync
node_manual_sync -->|"marks complete"| node_sync_state
node_follower_routes -->|"serves audience data"| node_follower_sync
node_follower_routes -->|"serves following"| node_following_sync
node_follower_routes -->|"serves profile"| node_profile
node_follower_routes -->|"serves sync status"| node_sync_state
node_repo_routes -->|"serves repository data"| node_repo_sync
node_contrib_routes -->|"serves contribution data"| node_contrib_sync
node_follower_sync -->|"fetches account data"| node_github_client
node_following_sync -->|"fetches account data"| node_github_client
node_repo_sync -->|"fetches repository data"| node_github_client
node_contrib_sync -->|"fetches contributions"| node_github_client
node_profile -->|"refreshes profile"| node_github_client
node_github_client -->|"calls API"| node_github
node_follower_sync -->|"reads and writes"| node_mongo
node_following_sync -->|"reads and writes"| node_mongo
node_repo_sync -->|"reads and writes"| node_mongo
node_contrib_sync -->|"reads and writes"| node_mongo
node_profile -->|"caches profile"| node_mongo
node_sync_state -->|"stores sync time"| node_mongo
node_fastapi -->|"connects at startup"| node_mongo
node_fastapi -->|"ensures indexes"| node_indexes
node_frontend_api -.-> node_follower_routes
node_frontend_api -.-> node_repo_routes
node_frontend_api -.-> node_contrib_routes

click node_fastapi "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/main.py"
click node_scheduler "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/scheduler.py"
click node_manual_sync "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/followers.py"
click node_follower_sync "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/follower_service.py"
click node_following_sync "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/following_service.py"
click node_repo_sync "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/repo_service.py"
click node_contrib_sync "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/contributions_service.py"
click node_profile "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/profile_service.py"
click node_github_client "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/github_service.py"
click node_sync_state "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/sync_state.py"
click node_follower_routes "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/followers.py"
click node_repo_routes "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/repos.py"
click node_contrib_routes "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/contributions.py"
click node_mongo "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/database.py"
click node_indexes "https://github.com/kalyanm45/gitpulse/blob/main/backend/app/indexes.py"
click node_frontend_api "https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/lib/api.ts"
click node_audience_ui "https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/app/(app)/audience/page.tsx"
click node_dashboard_ui "https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/app/(app)/dashboard/page.tsx"
click node_repos_ui "https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/app/(app)/repositories/page.tsx"

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_fastapi,node_scheduler toneBlue
class node_follower_sync,node_following_sync,node_repo_sync,node_contrib_sync,node_profile,node_github_client,node_sync_state toneAmber
class node_manual_sync,node_follower_routes,node_repo_routes,node_contrib_routes,node_github toneMint
class node_mongo,node_indexes toneRose
class node_frontend_api,node_audience_ui,node_dashboard_ui,node_repos_ui,node_user toneIndigo
```

## Components

### Application entry

- [FastAPI app](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/main.py): `backend/app/main.py`
- [Sync scheduler](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/scheduler.py): `backend/app/scheduler.py`

### Sync and collection

- [Follower sync/history](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/follower_service.py): `backend/app/services/follower_service.py`
- [Following sync](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/following_service.py): `backend/app/services/following_service.py`
- [Repository analytics](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/repo_service.py): `backend/app/services/repo_service.py`
- [Contribution analytics](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/contributions_service.py): `backend/app/services/contributions_service.py`
- [Profile cache](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/profile_service.py): `backend/app/services/profile_service.py`
- [GitHub client](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/github_service.py): `backend/app/services/github_service.py`
- [Sync state](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/services/sync_state.py): `backend/app/services/sync_state.py`

### Analytics API

- [Manual sync route](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/followers.py): `backend/app/routes/followers.py`
- [Audience routes](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/followers.py): `backend/app/routes/followers.py`
- [Repository routes](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/repos.py): `backend/app/routes/repos.py`
- [Contribution routes](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/routes/contributions.py): `backend/app/routes/contributions.py`

### Persistence

- [MongoDB](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/database.py): `backend/app/database.py`
- [Database indexes](https://github.com/kalyanm45/gitpulse/blob/main/backend/app/indexes.py): `backend/app/indexes.py`

### Dashboard UI

- [Frontend API client](https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Audience views](https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/app/(app)/audience/page.tsx): `frontend/src/app/(app)/audience/page.tsx`
- [Dashboard views](https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/app/(app)/dashboard/page.tsx): `frontend/src/app/(app)/dashboard/page.tsx`
- [Repository views](https://github.com/kalyanm45/gitpulse/blob/main/frontend/src/app/(app)/repositories/page.tsx): `frontend/src/app/(app)/repositories/page.tsx`

### Other components

- **Account owner**
- **GitHub REST API**

## Connections

- Account owner → Manual sync route: requests sync
- FastAPI app → Audience routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI app → Repository routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI app → Contribution routes: mounts routes (evidence: `backend/app/main.py`)
- FastAPI app → Sync scheduler: starts scheduler (evidence: `backend/app/main.py`)
- Manual sync route → Profile cache: refreshes profile (evidence: `backend/app/routes/followers.py`)
- Manual sync route → Follower sync/history: syncs followers (evidence: `backend/app/routes/followers.py`)
- Manual sync route → Following sync: syncs following (evidence: `backend/app/routes/followers.py`)
- Manual sync route → Repository analytics: syncs repositories (evidence: `backend/app/routes/followers.py`)
- Manual sync route → Contribution analytics: syncs contributions (evidence: `backend/app/routes/followers.py`)
- Manual sync route → Sync state: marks complete (evidence: `backend/app/routes/followers.py`)
- Audience routes → Follower sync/history: serves audience data (evidence: `backend/app/routes/followers.py`)
- Audience routes → Following sync: serves following (evidence: `backend/app/routes/followers.py`)
- Audience routes → Profile cache: serves profile (evidence: `backend/app/routes/followers.py`)
- Audience routes → Sync state: serves sync status (evidence: `backend/app/routes/followers.py`)
- Repository routes → Repository analytics: serves repository data (evidence: `backend/app/routes/repos.py`)
- Contribution routes → Contribution analytics: serves contribution data (evidence: `backend/app/routes/contributions.py`)
- Follower sync/history → GitHub client: fetches account data (evidence: `backend/app/services/follower_service.py`)
- Following sync → GitHub client: fetches account data (evidence: `backend/app/services/following_service.py`)
- Repository analytics → GitHub client: fetches repository data (evidence: `backend/app/services/repo_service.py`)
- Contribution analytics → GitHub client: fetches contributions (evidence: `backend/app/services/contributions_service.py`)
- Profile cache → GitHub client: refreshes profile (evidence: `backend/app/services/profile_service.py`)
- GitHub client → GitHub REST API: calls API (evidence: `backend/app/services/github_service.py`)
- Follower sync/history → MongoDB: reads and writes (evidence: `backend/app/services/follower_service.py`)
- Following sync → MongoDB: reads and writes (evidence: `backend/app/services/following_service.py`)
- Repository analytics → MongoDB: reads and writes (evidence: `backend/app/services/repo_service.py`)
- Contribution analytics → MongoDB: reads and writes (evidence: `backend/app/services/contributions_service.py`)
- Profile cache → MongoDB: caches profile (evidence: `backend/app/services/profile_service.py`)
- Sync state → MongoDB: stores sync time (evidence: `backend/app/services/sync_state.py`)
- FastAPI app → MongoDB: connects at startup (evidence: `backend/app/main.py`)
- FastAPI app → Database indexes: ensures indexes (evidence: `backend/app/main.py`)
- Frontend API client → Audience routes
- Frontend API client → Repository routes
- Frontend API client → Contribution routes
