# nitishsaini-44/synapsesync architecture

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

- Interactive diagram: https://gitdiagram.com/nitishsaini-44/synapsesync
- Repository: https://github.com/nitishsaini-44/synapsesync

## Overview

SynapseSync turns Gmail messages into categorized, summarized leads and presents them in a live dashboard. The documented main path is Pub/Sub webhook → queued Celery task → Gmail fetch and parallel email processing → AI classification → PostgreSQL persistence, with optional Discord notification and Socket.IO updates. The graph also preserves manual AI tools, account/OAuth and automation settings, lead management, and analytics. The README documents several pipeline links; source-index references and excerpts support others. Some unsampled route and frontend details are represented at their exact tree paths without asserting unshown internal calls.

Main entry points: [`backend/app.py`](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/app.py) (Flask application), [`backend/services/automation_service.py`](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/automation_service.py) (Automation pipeline), [`backend/database/db.py`](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/database/db.py) (PostgreSQL data), [`frontend/src/App.jsx`](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/App.jsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion and queue"]
  node_backend_app["Flask application<br/>[app.py]"]
  node_webhook["Gmail webhook<br/>[webhooks.py]"]
  node_redis["Redis queue"]
  node_celery_task["Celery task<br/>[tasks.py]"]
end

subgraph group_processing["Email processing"]
  node_automation["Automation pipeline"]
  node_gmail_service["Gmail service<br/>[gmail_service.py]"]
  node_cleaner["Email cleaner<br/>[email_cleaner.py]"]
  node_ai_service["AI engine<br/>[ai_service.py]"]
  node_db[("PostgreSQL data<br/>[db.py]")]
  node_discord_service["Discord notifications<br/>[discord_service.py]"]
end

subgraph group_account["Accounts and integrations"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_oauth_routes["Google OAuth<br/>[oauth.py]"]
  node_user_routes["User settings<br/>[user.py]"]
  node_encryption["Token encryption<br/>[encryption.py]"]
end

subgraph group_api["Backend capabilities"]
  node_leads_routes["Lead management<br/>[leads.py]"]
  node_analytics_routes["Analytics API<br/>[analytics.py]"]
  node_analytics_service["Analytics service"]
  node_ai_routes["Manual AI tools<br/>[classify.py]"]
  node_summarize_routes["Summarization API<br/>[summarize.py]"]
  node_reply_routes["Reply generation API<br/>[reply.py]"]
end

subgraph group_frontend["Web application"]
  node_frontend_app["React application<br/>[App.jsx]"]
  node_auth_context["Session context<br/>[AuthContext.jsx]"]
  node_api_client["HTTP API client<br/>[client.js]"]
  node_dashboard["Dashboard<br/>[Dashboard.jsx]"]
  node_socket["Live updates<br/>[socket.js]"]
  node_lead_page["Lead management UI<br/>[LeadManagement.jsx]"]
  node_assistant_page["AI assistant UI<br/>[AIAssistant.jsx]"]
  node_integrations_page["Integrations UI<br/>[Integrations.jsx]"]
  node_landing["Public landing pages<br/>[Landing.jsx]"]
end

node_user(("Mailbox owner"))
node_gmail["Gmail and Pub/Sub"]
node_discord["Discord"]

node_gmail -->|"pushes notifications"| node_webhook
node_webhook -->|"looks up user"| node_db
node_webhook -->|"sets cooldown"| node_redis
node_webhook -->|"dispatches task"| node_celery_task
node_celery_task -->|"runs processing"| node_automation
node_automation -->|"loads and saves leads"| node_db
node_automation -->|"fetches messages"| node_gmail_service
node_automation -->|"cleans message"| node_cleaner
node_automation -->|"classifies message"| node_ai_service
node_ai_service -->|"requests AI completion"| node_gmail
node_automation -->|"formats notification"| node_discord_service
node_automation -->|"decrypts webhook"| node_encryption
node_discord_service -->|"sends embed"| node_discord
node_oauth_routes -->|"exchanges OAuth"| node_gmail_service
node_oauth_routes -->|"protects token"| node_encryption
node_oauth_routes -->|"stores account"| node_db
node_user_routes -->|"reads and updates settings"| node_db
node_user_routes -->|"renews Gmail watch"| node_gmail_service
node_user_routes -->|"handles credentials"| node_encryption
node_auth_routes -->|"uses user records"| node_db
node_leads_routes -->|"reads leads"| node_db
node_analytics_routes -->|"gets analytics"| node_analytics_service
node_analytics_service -.->|"aggregates data"| node_db
node_ai_routes -->|"classifies text"| node_ai_service
node_ai_routes -->|"cleans input"| node_cleaner
node_summarize_routes -->|"summarizes text"| node_ai_service
node_summarize_routes -->|"cleans input"| node_cleaner
node_reply_routes -->|"generates reply"| node_ai_service
node_backend_app -->|"registers routes"| node_webhook
node_backend_app -->|"registers routes"| node_auth_routes
node_backend_app -->|"registers routes"| node_oauth_routes
node_backend_app -->|"registers routes"| node_user_routes
node_backend_app -->|"registers routes"| node_leads_routes
node_backend_app -->|"registers routes"| node_analytics_routes
node_backend_app -->|"registers routes"| node_ai_routes
node_backend_app -->|"registers routes"| node_summarize_routes
node_backend_app -->|"registers routes"| node_reply_routes
node_frontend_app -->|"provides session"| node_auth_context
node_frontend_app -->|"routes to"| node_dashboard
node_frontend_app -->|"routes to"| node_lead_page
node_frontend_app -->|"routes to"| node_assistant_page
node_frontend_app -->|"routes to"| node_integrations_page
node_frontend_app -->|"routes to"| node_landing
node_auth_context -->|"sets auth header"| node_api_client
node_dashboard -->|"requests data"| node_api_client
node_dashboard -->|"receives live events"| node_socket
node_dashboard -.->|"shows persisted leads"| node_db
node_assistant_page -->|"calls AI tools"| node_api_client

click node_backend_app "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/app.py"
click node_webhook "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/webhooks.py"
click node_celery_task "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/tasks.py"
click node_automation "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/automation_service.py"
click node_gmail_service "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/gmail_service.py"
click node_cleaner "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/utils/email_cleaner.py"
click node_ai_service "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/ai_service.py"
click node_db "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/database/db.py"
click node_discord_service "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/discord_service.py"
click node_auth_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/auth.py"
click node_oauth_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/oauth.py"
click node_user_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/user.py"
click node_encryption "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/utils/encryption.py"
click node_leads_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/leads.py"
click node_analytics_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/analytics.py"
click node_analytics_service "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/analytics_service.py"
click node_ai_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/classify.py"
click node_summarize_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/summarize.py"
click node_reply_routes "https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/reply.py"
click node_frontend_app "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/components/AuthContext.jsx"
click node_api_client "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/api/client.js"
click node_dashboard "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/Dashboard.jsx"
click node_socket "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/api/socket.js"
click node_lead_page "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/LeadManagement.jsx"
click node_assistant_page "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/AIAssistant.jsx"
click node_integrations_page "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/Integrations.jsx"
click node_landing "https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/Landing.jsx"

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_backend_app,node_webhook,node_redis,node_celery_task toneBlue
class node_automation,node_gmail_service,node_cleaner,node_ai_service,node_db,node_discord_service toneAmber
class node_auth_routes,node_oauth_routes,node_user_routes,node_encryption toneMint
class node_leads_routes,node_analytics_routes,node_analytics_service,node_ai_routes,node_summarize_routes,node_reply_routes toneRose
class node_frontend_app,node_auth_context,node_api_client,node_dashboard,node_socket,node_lead_page,node_assistant_page,node_integrations_page,node_landing,node_user,node_gmail,node_discord toneIndigo
```

## Components

### Ingestion and queue

- [Flask application](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/app.py): `backend/app.py`
- [Gmail webhook](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/webhooks.py): `backend/routes/webhooks.py`
- **Redis queue**
- [Celery task](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/tasks.py): `backend/tasks.py`

### Email processing

- [Automation pipeline](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/automation_service.py): `backend/services/automation_service.py`
- [Gmail service](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/gmail_service.py): `backend/services/gmail_service.py`
- [Email cleaner](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/utils/email_cleaner.py): `backend/utils/email_cleaner.py`
- [AI engine](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/ai_service.py): `backend/services/ai_service.py`
- [PostgreSQL data](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/database/db.py): `backend/database/db.py`
- [Discord notifications](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/discord_service.py): `backend/services/discord_service.py`

### Accounts and integrations

- [Authentication](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/auth.py): `backend/routes/auth.py`
- [Google OAuth](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/oauth.py): `backend/routes/oauth.py`
- [User settings](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/user.py): `backend/routes/user.py`
- [Token encryption](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/utils/encryption.py): `backend/utils/encryption.py`

### Backend capabilities

- [Lead management](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/leads.py): `backend/routes/leads.py`
- [Analytics API](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/analytics.py): `backend/routes/analytics.py`
- [Analytics service](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/services/analytics_service.py): `backend/services/analytics_service.py`
- [Manual AI tools](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/classify.py): `backend/routes/classify.py`
- [Summarization API](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/summarize.py): `backend/routes/summarize.py`
- [Reply generation API](https://github.com/nitishsaini-44/synapsesync/blob/main/backend/routes/reply.py): `backend/routes/reply.py`

### Web application

- [React application](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session context](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/components/AuthContext.jsx): `frontend/src/components/AuthContext.jsx`
- [HTTP API client](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`
- [Dashboard](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Live updates](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/api/socket.js): `frontend/src/api/socket.js`
- [Lead management UI](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/LeadManagement.jsx): `frontend/src/pages/LeadManagement.jsx`
- [AI assistant UI](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/AIAssistant.jsx): `frontend/src/pages/AIAssistant.jsx`
- [Integrations UI](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/Integrations.jsx): `frontend/src/pages/Integrations.jsx`
- [Public landing pages](https://github.com/nitishsaini-44/synapsesync/blob/main/frontend/src/pages/Landing.jsx): `frontend/src/pages/Landing.jsx`

### Other components

- **Mailbox owner**
- **Gmail and Pub/Sub**
- **Discord**

## Connections

- Gmail and Pub/Sub → Gmail webhook: pushes notifications
- Gmail webhook → PostgreSQL data: looks up user (evidence: `backend/routes/webhooks.py`)
- Gmail webhook → Redis queue: sets cooldown (evidence: `backend/routes/webhooks.py`)
- Gmail webhook → Celery task: dispatches task (evidence: `backend/routes/webhooks.py`)
- Celery task → Automation pipeline: runs processing (evidence: `backend/tasks.py`)
- Automation pipeline → PostgreSQL data: loads and saves leads (evidence: `backend/services/automation_service.py`)
- Automation pipeline → Gmail service: fetches messages (evidence: `backend/services/automation_service.py`)
- Automation pipeline → Email cleaner: cleans message (evidence: `backend/services/automation_service.py`)
- Automation pipeline → AI engine: classifies message (evidence: `backend/services/automation_service.py`)
- AI engine → Gmail and Pub/Sub: requests AI completion (evidence: `backend/services/ai_service.py`)
- Automation pipeline → Discord notifications: formats notification (evidence: `backend/services/automation_service.py`)
- Automation pipeline → Token encryption: decrypts webhook (evidence: `backend/services/automation_service.py`)
- Discord notifications → Discord: sends embed
- Google OAuth → Gmail service: exchanges OAuth (evidence: `backend/routes/oauth.py`)
- Google OAuth → Token encryption: protects token (evidence: `backend/routes/oauth.py`)
- Google OAuth → PostgreSQL data: stores account (evidence: `backend/routes/oauth.py`)
- User settings → PostgreSQL data: reads and updates settings (evidence: `backend/routes/user.py`)
- User settings → Gmail service: renews Gmail watch (evidence: `backend/routes/user.py`)
- User settings → Token encryption: handles credentials (evidence: `backend/routes/user.py`)
- Authentication → PostgreSQL data: uses user records (evidence: `backend/routes/auth.py`)
- Lead management → PostgreSQL data: reads leads (evidence: `backend/routes/leads.py`)
- Analytics API → Analytics service: gets analytics (evidence: `backend/routes/analytics.py`)
- Analytics service → PostgreSQL data: aggregates data
- Manual AI tools → AI engine: classifies text (evidence: `backend/routes/classify.py`)
- Manual AI tools → Email cleaner: cleans input (evidence: `backend/routes/classify.py`)
- Summarization API → AI engine: summarizes text (evidence: `backend/routes/summarize.py`)
- Summarization API → Email cleaner: cleans input (evidence: `backend/routes/summarize.py`)
- Reply generation API → AI engine: generates reply (evidence: `backend/routes/reply.py`)
- Flask application → Gmail webhook: registers routes (evidence: `backend/app.py`)
- Flask application → Authentication: registers routes (evidence: `backend/app.py`)
- Flask application → Google OAuth: registers routes (evidence: `backend/app.py`)
- Flask application → User settings: registers routes (evidence: `backend/app.py`)
- Flask application → Lead management: registers routes (evidence: `backend/app.py`)
- Flask application → Analytics API: registers routes (evidence: `backend/app.py`)
- Flask application → Manual AI tools: registers routes (evidence: `backend/app.py`)
- Flask application → Summarization API: registers routes (evidence: `backend/app.py`)
- Flask application → Reply generation API: registers routes (evidence: `backend/app.py`)
- React application → Session context: provides session (evidence: `frontend/src/App.jsx`)
- React application → Dashboard: routes to (evidence: `frontend/src/App.jsx`)
- React application → Lead management UI: routes to (evidence: `frontend/src/App.jsx`)
- React application → AI assistant UI: routes to (evidence: `frontend/src/App.jsx`)
- React application → Integrations UI: routes to (evidence: `frontend/src/App.jsx`)
- React application → Public landing pages: routes to (evidence: `frontend/src/App.jsx`)
- Session context → HTTP API client: sets auth header (evidence: `frontend/src/components/AuthContext.jsx`)
- Dashboard → HTTP API client: requests data (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → Live updates: receives live events (evidence: `frontend/src/pages/Dashboard.jsx`)
- Dashboard → PostgreSQL data: shows persisted leads
- AI assistant UI → HTTP API client: calls AI tools (evidence: `frontend/src/pages/AIAssistant.jsx`)
