# deekshithgowda85/agile_scrum_master architecture

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

- Interactive diagram: https://gitdiagram.com/deekshithgowda85/agile_scrum_master
- Repository: https://github.com/deekshithgowda85/agile_scrum_master

## Overview

#### Purpose and Deployable Entry Points
Sprint is an agentic, multi-tenant Scrum-management platform: it automates planning, task assignment, monitoring, reporting, GitHub/Jira ingestion, AI assistance, and live meetings. It ships as a web application and an Electron desktop client.
- Web/App Router entry: `cloud/app/layout.tsx`, `cloud/app/page.tsx`
- Express gateway entry: `cloud/backend/api-gateway/src/app.js`
- FastAPI AI entry: `cloud/backend/ai-service/app/main.py`
- Electron main/preload boundary: `desktop/electron/main.js`, `desktop/electron/preload.js`

#### Client and BFF Boundary
The primary browser UI is a Next.js 16 App Router application. Public/auth pages are separate from the authenticated dashboard; dashboard pages cover projects, tasks, sprints, boards, teams, meetings, monitoring, integrations, and agent workflows. Next route handlers act as a BFF: browser clients do not directly call the gateway, preserving JWT/cookie handling server-side.
- Dashboard shell and routes: `cloud/app/(dashboard)/layout.tsx`, `cloud/app/(dashboard)/board/page.tsx`
- BFF proxy and gateway client: `cloud/app/api/proxy/[...path]/route.ts`, `cloud/lib/api-gateway.ts`
- Auth surface: `cloud/app/api/auth/sign-in/route.ts`, `cloud/app/auth/sign-in/page.tsx`

#### Core Domain Gateway
The Node/Express API gateway is the authoritative domain-service layer. Routes/controllers/services organize CRUD and workflows around organizations, teams/developers, projects, tasks, sprints, assignments, meetings, reporting, and monitoring. Middleware authenticates requests and resolves the organization-specific data connection before services execute.
- Composition and runtime config: `cloud/backend/api-gateway/src/app.js`, `cloud/backend/api-gateway/src/config/database.js`
- Tenant/auth boundary: `cloud/backend/api-gateway/src/middleware/auth.js`, `cloud/backend/api-gateway/src/middleware/orgDb.js`
- Central work-management services: `cloud/backend/api-gateway/src/services/task.service.js`, `cloud/backend/api-gateway/src/services/sprint.service.js`, `cloud/backend/api-gateway/src/services/assignment.service.js`

#### Multi-Tenant Persistence and Realtime
A universal PostgreSQL schema holds shared/organization metadata; each organization has an isolated tenant database selected from JWT organization claims. The gateway supports Neon-compatible provisioning. Redis backs queues/caching, while Socket.IO distributes project-room updates such as approvals and agent actions.
- Schemas/migrations: `cloud/backend/api-gateway/db/universal_schema.sql`, `cloud/backend/api-gateway/db/org_schema.sql`
- Tenant provisioning: `cloud/backend/api-gateway/src/services/org.service.js`, `cloud/backend/api-gateway/src/utils/tenant-db.js`
- Realtime and Redis: `cloud/backend/api-gateway/src/realtime/io.js`, `cloud/backend/api-gateway/src/config/redis.js`

#### Automation, Integrations, and Failure Handling
GitHub and Jira are ingress boundaries. Verified webhook deliveries are processed into domain updates and task-generation flows; async work is handled through BullMQ/Redis workers and Inngest durable functions. Retry/DLQ endpoints provide operational recovery rather than silently losing external events.
- Webhook handlers and validation: `cloud/backend/api-gateway/src/services/githubWebhookHandler.js`, `cloud/backend/api-gateway/src/middleware/jiraWebhookVerify.js`
- Workers and retry: `cloud/backend/api-gateway/src/workers/webhookProcessing.worker.js`, `cloud/backend/api-gateway/src/jobs/webhookRetryWorker.js`
- Inngest functions: `cloud/inngest/functions/task-factory.ts`, `cloud/inngest/functions/ingestGitnexus.ts`

#### AI, Agents, and Code Automation
The gateway/BFF invokes a separate Python FastAPI service for ML, Groq-backed LLM features, RAG/embeddings, autonomous sprint planning, and agentic sprint builds. Git Nexus analyzes repositories and can execute code-oriented flows in E2B sandbox templates, including PR creation. Human approval APIs constrain agent actions.
- AI routes/services: `cloud/backend/ai-service/app/routes/sprint_planning.py`, `cloud/backend/ai-service/app/services/agentic_sprint_service.py`
- Planning graph and ML: `cloud/backend/ai-service/app/agents/sprint_planning_graph.py`, `cloud/backend/ai-service/app/ml/velocity_predictor.py`
- Git Nexus sandbox: `cloud/backend/ai-service/git_nexus/routes/api.py`, `cloud/backend/ai-service/git_nexus/sandbox.py`
- Approval boundary: `cloud/app/api/agent/approvals/[id]/approve/route.ts`

#### Meetings, Desktop, and External Services
Meeting workflows combine application APIs, LiveKit-style room/token endpoints, and Deepgram transcription integration; post-meeting jobs summarize/process outcomes. The Electron desktop app hosts a Vite/React rendering layer and exposes only explicit IPC handlers to its frontend, which then bridges to gateway/BFF-compatible operations.
- Meetings UI/API: `cloud/components/meetings/MeetingRoom.tsx`, `cloud/app/api/meetings/token/route.ts`
- Meeting lifecycle automation: `cloud/backend/api-gateway/src/jobs/post-meeting.job.js`, `cloud/backend/api-gateway/src/workers/post-meeting.worker.js`
- Desktop IPC bridge: `desktop/electron/ipc/gateway.js`, `desktop/frontend/src/lib/desktop-fetch-bridge.ts`
- Material external infrastructure: PostgreSQL/Neon, Redis/BullMQ, Inngest, Groq, GitHub, Jira, Stripe, LiveKit, Deepgram, and Brevo.

Main entry points: [`cloud/backend/api-gateway/src/app.js`](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/app.js) (Express API gateway), [`cloud/backend/ai-service/app/main.py`](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/ai-service/app/main.py) (FastAPI AI service), [`cloud/backend/api-gateway/src/services/task.service.js`](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/services/task.service.js) (Work management), [`cloud/backend/api-gateway/src/workers/webhookProcessing.worker.js`](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/workers/webhookProcessing.worker.js) (Webhook and meeting workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_desktop["Electron desktop<br/>Electron main process<br/>[main.js]"]
  node_desktop_ipc["Desktop gateway IPC<br/>IPC handlers<br/>[gateway.js]"]
end

subgraph group_cloud["Cloud application"]
  node_web["Next.js web app<br/>App Router UI<br/>[layout.tsx]"]
  node_dashboard["Dashboard workspace<br/>dashboard routes<br/>[layout.tsx]"]
  node_auth["Authentication<br/>auth routes<br/>[route.ts]"]
  node_bff["Next BFF proxy<br/>route handler<br/>[route.ts]"]
  node_approvals["Agent approvals<br/>approval route<br/>[route.ts]"]
  node_meetings["Meeting experience<br/>meeting UI and API<br/>[MeetingRoom.tsx]"]
end

subgraph group_gateway["Domain gateway"]
  node_gateway_app["Express API gateway<br/>domain API<br/>[app.js]"]
  node_tenant_auth["Tenant auth context<br/>middleware<br/>[auth.js]"]
  node_work_services["Work management<br/>domain services<br/>[task.service.js]"]
  node_tenant_provisioning["Tenant provisioning<br/>organization service<br/>[org.service.js]"]
  node_realtime["Project realtime<br/>Socket.IO<br/>[io.js]"]
end

subgraph group_automation["Automation and AI"]
  node_webhook_ingress["GitHub and Jira webhooks<br/>verified webhook handlers"]
  node_async_workers["Webhook and meeting workers<br/>BullMQ workers"]
  node_inngest["Inngest workflows<br/>durable functions<br/>[task-factory.ts]"]
  node_ai_service["FastAPI AI service<br/>AI API<br/>[main.py]"]
  node_planning_graph["Sprint planning agent<br/>planning graph"]
  node_git_nexus["Git Nexus automation<br/>code agent sandbox<br/>[api.py]"]
end

subgraph group_external["External infrastructure"]
  node_postgres[("Universal and tenant PostgreSQL<br/>PostgreSQL / Neon")]
  node_redis["Redis and BullMQ<br/>cache and queues<br/>[redis.js]"]
  node_integrations{{"External providers<br/>SaaS integrations"}}
end

node_web -->|"renders"| node_dashboard
node_web -->|"sign-in"| node_auth
node_dashboard -->|"application requests"| node_bff
node_bff -->|"server-side proxy"| node_gateway_app
node_desktop -->|"exposes"| node_desktop_ipc
node_desktop_ipc -->|"gateway operations"| node_gateway_app
node_gateway_app -->|"applies"| node_tenant_auth
node_tenant_auth -->|"scoped requests"| node_work_services
node_work_services -->|"tenant data"| node_postgres
node_tenant_provisioning -->|"provisions databases"| node_postgres
node_gateway_app -->|"publishes updates"| node_realtime
node_realtime -->|"adapter and cache"| node_redis
node_integrations -->|"GitHub and Jira events"| node_webhook_ingress
node_webhook_ingress -->|"queues deliveries"| node_redis
node_redis -->|"jobs and retries"| node_async_workers
node_async_workers -->|"domain updates"| node_work_services
node_inngest -->|"durable task flows"| node_work_services
node_gateway_app -->|"AI requests"| node_ai_service
node_ai_service -->|"planning execution"| node_planning_graph
node_ai_service -->|"code automation"| node_git_nexus
node_ai_service -->|"LLM and sandbox providers"| node_integrations
node_approvals -->|"approves actions"| node_gateway_app
node_meetings -->|"meeting APIs"| node_bff
node_meetings -->|"LiveKit and transcription"| node_integrations
node_async_workers -->|"post-meeting processing"| node_integrations

click node_web "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/layout.tsx"
click node_dashboard "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/(dashboard)/layout.tsx"
click node_auth "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/api/auth/sign-in/route.ts"
click node_bff "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/api/proxy/%5B...path%5D/route.ts"
click node_approvals "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/api/agent/approvals/%5Bid%5D/approve/route.ts"
click node_meetings "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/components/meetings/MeetingRoom.tsx"
click node_desktop "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/desktop/electron/main.js"
click node_desktop_ipc "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/desktop/electron/ipc/gateway.js"
click node_gateway_app "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/app.js"
click node_tenant_auth "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/middleware/auth.js"
click node_work_services "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/services/task.service.js"
click node_tenant_provisioning "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/services/org.service.js"
click node_realtime "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/realtime/io.js"
click node_webhook_ingress "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/services/githubWebhookHandler.js"
click node_async_workers "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/workers/webhookProcessing.worker.js"
click node_inngest "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/inngest/functions/task-factory.ts"
click node_ai_service "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/ai-service/app/main.py"
click node_planning_graph "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/ai-service/app/agents/sprint_planning_graph.py"
click node_git_nexus "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/ai-service/git_nexus/routes/api.py"
click node_postgres "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/db/universal_schema.sql"
click node_redis "https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/config/redis.js"

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_desktop,node_desktop_ipc toneBlue
class node_web,node_dashboard,node_auth,node_bff,node_approvals,node_meetings toneAmber
class node_gateway_app,node_tenant_auth,node_work_services,node_tenant_provisioning,node_realtime toneMint
class node_webhook_ingress,node_async_workers,node_inngest,node_ai_service,node_planning_graph,node_git_nexus toneRose
class node_postgres,node_redis,node_integrations toneIndigo
```

## Components

### Clients

- [Electron desktop](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/desktop/electron/main.js): Electron main process · Desktop host with explicit preload and IPC boundary. · `desktop/electron/main.js`
- [Desktop gateway IPC](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/desktop/electron/ipc/gateway.js): IPC handlers · `desktop/electron/ipc/gateway.js`

### Cloud application

- [Next.js web app](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/layout.tsx): App Router UI · Public auth and authenticated Scrum dashboard. · `cloud/app/layout.tsx`
- [Dashboard workspace](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/(dashboard)/layout.tsx): dashboard routes · Projects, boards, tasks, sprints, teams, meetings, and agents. · `cloud/app/(dashboard)/layout.tsx`
- [Authentication](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/api/auth/sign-in/route.ts): auth routes · `cloud/app/api/auth/sign-in/route.ts`
- [Next BFF proxy](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/api/proxy/%5B...path%5D/route.ts): route handler · Keeps browser-to-gateway JWT and cookie handling server-side. · `cloud/app/api/proxy/[...path]/route.ts`
- [Agent approvals](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/app/api/agent/approvals/%5Bid%5D/approve/route.ts): approval route · Human gate for agent actions. · `cloud/app/api/agent/approvals/[id]/approve/route.ts`
- [Meeting experience](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/components/meetings/MeetingRoom.tsx): meeting UI and API · `cloud/components/meetings/MeetingRoom.tsx`

### Domain gateway

- [Express API gateway](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/app.js): domain API · Authoritative work-management and organization service layer. · `cloud/backend/api-gateway/src/app.js`
- [Tenant auth context](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/middleware/auth.js): middleware · Authenticates requests and selects an organization database from claims. · `cloud/backend/api-gateway/src/middleware/auth.js`
- [Work management](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/services/task.service.js): domain services · Task, sprint, and assignment workflows. · `cloud/backend/api-gateway/src/services/task.service.js`
- [Tenant provisioning](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/services/org.service.js): organization service · Creates and manages isolated organization databases. · `cloud/backend/api-gateway/src/services/org.service.js`
- [Project realtime](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/realtime/io.js): Socket.IO · Distributes project-room approvals and agent updates. · `cloud/backend/api-gateway/src/realtime/io.js`

### Automation and AI

- [GitHub and Jira webhooks](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/services/githubWebhookHandler.js): verified webhook handlers · `cloud/backend/api-gateway/src/services/githubWebhookHandler.js`
- [Webhook and meeting workers](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/workers/webhookProcessing.worker.js): BullMQ workers · Processes async deliveries, retries, and post-meeting work. · `cloud/backend/api-gateway/src/workers/webhookProcessing.worker.js`
- [Inngest workflows](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/inngest/functions/task-factory.ts): durable functions · Runs task factory and repository ingestion flows. · `cloud/inngest/functions/task-factory.ts`
- [FastAPI AI service](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/ai-service/app/main.py): AI API · Planning, RAG, LLM, and agentic sprint capabilities. · `cloud/backend/ai-service/app/main.py`
- [Sprint planning agent](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/ai-service/app/agents/sprint_planning_graph.py): planning graph · Combines planning graph and velocity prediction. · `cloud/backend/ai-service/app/agents/sprint_planning_graph.py`
- [Git Nexus automation](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/ai-service/git_nexus/routes/api.py): code agent sandbox · Analyzes repositories and executes code-oriented sandbox flows. · `cloud/backend/ai-service/git_nexus/routes/api.py`

### External infrastructure

- [Universal and tenant PostgreSQL](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/db/universal_schema.sql): PostgreSQL / Neon · Shared metadata plus isolated organization schemas. · `cloud/backend/api-gateway/db/universal_schema.sql`
- [Redis and BullMQ](https://github.com/deekshithgowda85/agile_scrum_master/blob/Production/cloud/backend/api-gateway/src/config/redis.js): cache and queues · `cloud/backend/api-gateway/src/config/redis.js`
- **External providers**: SaaS integrations · GitHub, Jira, Groq, LiveKit, Deepgram, Stripe, and Brevo.

## Connections

- Next.js web app → Dashboard workspace: renders
- Next.js web app → Authentication: sign-in
- Dashboard workspace → Next BFF proxy: application requests
- Next BFF proxy → Express API gateway: server-side proxy
- Electron desktop → Desktop gateway IPC: exposes
- Desktop gateway IPC → Express API gateway: gateway operations
- Express API gateway → Tenant auth context: applies
- Tenant auth context → Work management: scoped requests
- Work management → Universal and tenant PostgreSQL: tenant data
- Tenant provisioning → Universal and tenant PostgreSQL: provisions databases
- Express API gateway → Project realtime: publishes updates
- Project realtime → Redis and BullMQ: adapter and cache
- External providers → GitHub and Jira webhooks: GitHub and Jira events
- GitHub and Jira webhooks → Redis and BullMQ: queues deliveries
- Redis and BullMQ → Webhook and meeting workers: jobs and retries
- Webhook and meeting workers → Work management: domain updates
- Inngest workflows → Work management: durable task flows
- Express API gateway → FastAPI AI service: AI requests
- FastAPI AI service → Sprint planning agent: planning execution
- FastAPI AI service → Git Nexus automation: code automation
- FastAPI AI service → External providers: LLM and sandbox providers
- Agent approvals → Express API gateway: approves actions
- Meeting experience → Next BFF proxy: meeting APIs
- Meeting experience → External providers: LiveKit and transcription
- Webhook and meeting workers → External providers: post-meeting processing