# priyankshu-07/voltmail architecture

> Architecture diagram of the GitHub repository priyankshu-07/voltmail, 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/priyankshu-07/voltmail
- Repository: https://github.com/priyankshu-07/voltmail

## Overview

VoltMail’s main user workflow is a Streamlit cold-email form calling an Express API, which builds a prompt, requests Groq generation, sends the message through Gmail, and records success or failure in MongoDB. The repository also contains a separate RAG context-retrieval path using Cohere embeddings and Chroma; sampled UI code does not connect it to email generation. Analytics and campaign tracking are documented, but their data flow is not established by the sampled source, so that relationship is left unverified.

Main entry points: [`backend/controllers/emailController.js`](https://github.com/priyankshu-07/voltmail/blob/main/backend/controllers/emailController.js) (Email controller), [`backend/server.js`](https://github.com/priyankshu-07/voltmail/blob/main/backend/server.js) (Express server), [`frontend/utils/chroma_connector.py`](https://github.com/priyankshu-07/voltmail/blob/main/frontend/utils/chroma_connector.py) (Vector connector), [`frontend/pages/Voltmail.py`](https://github.com/priyankshu-07/voltmail/blob/main/frontend/pages/Voltmail.py) (Email composer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_email_form["Email composer<br/>[Voltmail.py]"]
  node_analytics_ui["Analytics dashboard<br/>[analytics.py]"]
  node_api_client["API client<br/>[api_handler.py]"]
end

subgraph group_api["Email API"]
  node_server["Express server<br/>[server.js]"]
  node_email_routes["Email routes<br/>[emailRoutes.js]"]
  node_controller["Email controller<br/>[emailController.js]"]
end

subgraph group_generation["Generation and delivery"]
  node_prompt["Prompt builder<br/>[promptBuilder.js]"]
  node_groq["Groq inference<br/>[groqService.js]"]
  node_sender["Email sender<br/>[emailsender.js]"]
end

subgraph group_rag["Context retrieval"]
  node_rag_service["RAG retrieval<br/>[langchain.py]"]
  node_vector_connector["Vector connector"]
  node_vector_store[("Chroma store")]
end

subgraph group_data["Persistence and analytics"]
  node_mongo_init["Mongo connection<br/>[mongo.js]"]
  node_email_log[("Email logs<br/>[emaillog.js]")]
end

node_user(("Outreach user"))
node_groq_service["Groq API"]
node_mail_service["Gmail delivery"]
node_cohere["Cohere embeddings"]
node_mongo[("MongoDB")]

node_user -->|"enters details"| node_email_form
node_email_form -->|"submits email"| node_api_client
node_api_client -.->|"POSTs request"| node_server
node_server -->|"mounts routes"| node_email_routes
node_email_routes -->|"routes requests"| node_controller
node_controller -->|"builds prompt"| node_prompt
node_controller -->|"requests generation"| node_groq
node_groq -->|"calls inference"| node_groq_service
node_controller -->|"sends message"| node_sender
node_sender -->|"delivers email"| node_mail_service
node_controller -->|"writes and reads"| node_email_log
node_server -->|"initializes"| node_mongo_init
node_mongo_init -->|"connects"| node_mongo
node_email_log -.->|"stores records"| node_mongo
node_user -.->|"views metrics"| node_analytics_ui
node_rag_service -->|"searches context"| node_vector_connector
node_vector_connector -->|"queries and adds"| node_vector_store
node_vector_connector -.->|"embeds documents"| node_cohere

click node_email_form "https://github.com/priyankshu-07/voltmail/blob/main/frontend/pages/Voltmail.py"
click node_analytics_ui "https://github.com/priyankshu-07/voltmail/blob/main/frontend/pages/analytics.py"
click node_api_client "https://github.com/priyankshu-07/voltmail/blob/main/frontend/utils/api_handler.py"
click node_server "https://github.com/priyankshu-07/voltmail/blob/main/backend/server.js"
click node_email_routes "https://github.com/priyankshu-07/voltmail/blob/main/backend/routes/emailRoutes.js"
click node_controller "https://github.com/priyankshu-07/voltmail/blob/main/backend/controllers/emailController.js"
click node_prompt "https://github.com/priyankshu-07/voltmail/blob/main/backend/services/promptBuilder.js"
click node_groq "https://github.com/priyankshu-07/voltmail/blob/main/backend/services/groqService.js"
click node_sender "https://github.com/priyankshu-07/voltmail/blob/main/backend/services/emailsender.js"
click node_rag_service "https://github.com/priyankshu-07/voltmail/blob/main/frontend/services/langchain.py"
click node_vector_connector "https://github.com/priyankshu-07/voltmail/blob/main/frontend/utils/chroma_connector.py"
click node_mongo_init "https://github.com/priyankshu-07/voltmail/blob/main/backend/db/mongo.js"
click node_email_log "https://github.com/priyankshu-07/voltmail/blob/main/backend/db/emaillog.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_email_form,node_analytics_ui,node_api_client,node_user toneBlue
class node_server,node_email_routes,node_controller,node_mongo toneAmber
class node_prompt,node_groq,node_sender,node_groq_service toneMint
class node_rag_service,node_vector_connector,node_vector_store toneRose
class node_mongo_init,node_email_log,node_mail_service,node_cohere toneIndigo
```

## Components

### User interface

- [Email composer](https://github.com/priyankshu-07/voltmail/blob/main/frontend/pages/Voltmail.py): `frontend/pages/Voltmail.py`
- [Analytics dashboard](https://github.com/priyankshu-07/voltmail/blob/main/frontend/pages/analytics.py): `frontend/pages/analytics.py`
- [API client](https://github.com/priyankshu-07/voltmail/blob/main/frontend/utils/api_handler.py): `frontend/utils/api_handler.py`

### Email API

- [Express server](https://github.com/priyankshu-07/voltmail/blob/main/backend/server.js): `backend/server.js`
- [Email routes](https://github.com/priyankshu-07/voltmail/blob/main/backend/routes/emailRoutes.js): `backend/routes/emailRoutes.js`
- [Email controller](https://github.com/priyankshu-07/voltmail/blob/main/backend/controllers/emailController.js): `backend/controllers/emailController.js`

### Generation and delivery

- [Prompt builder](https://github.com/priyankshu-07/voltmail/blob/main/backend/services/promptBuilder.js): `backend/services/promptBuilder.js`
- [Groq inference](https://github.com/priyankshu-07/voltmail/blob/main/backend/services/groqService.js): `backend/services/groqService.js`
- [Email sender](https://github.com/priyankshu-07/voltmail/blob/main/backend/services/emailsender.js): `backend/services/emailsender.js`

### Context retrieval

- [RAG retrieval](https://github.com/priyankshu-07/voltmail/blob/main/frontend/services/langchain.py): `frontend/services/langchain.py`
- [Vector connector](https://github.com/priyankshu-07/voltmail/blob/main/frontend/utils/chroma_connector.py): `frontend/utils/chroma_connector.py`
- **Chroma store**

### Persistence and analytics

- [Mongo connection](https://github.com/priyankshu-07/voltmail/blob/main/backend/db/mongo.js): `backend/db/mongo.js`
- [Email logs](https://github.com/priyankshu-07/voltmail/blob/main/backend/db/emaillog.js): `backend/db/emaillog.js`

### Other components

- **Outreach user**
- **Groq API**
- **Gmail delivery**
- **Cohere embeddings**
- **MongoDB**

## Connections

- Outreach user → Email composer: enters details (evidence: `frontend/pages/Voltmail.py`)
- Email composer → API client: submits email (evidence: `frontend/pages/Voltmail.py`)
- API client → Express server: POSTs request
- Express server → Email routes: mounts routes (evidence: `backend/server.js`)
- Email routes → Email controller: routes requests (evidence: `backend/routes/emailRoutes.js`)
- Email controller → Prompt builder: builds prompt (evidence: `backend/controllers/emailController.js`)
- Email controller → Groq inference: requests generation (evidence: `backend/controllers/emailController.js`)
- Groq inference → Groq API: calls inference (evidence: `backend/services/groqService.js`)
- Email controller → Email sender: sends message (evidence: `backend/controllers/emailController.js`)
- Email sender → Gmail delivery: delivers email (evidence: `backend/services/emailsender.js`)
- Email controller → Email logs: writes and reads (evidence: `backend/controllers/emailController.js`)
- Express server → Mongo connection: initializes (evidence: `backend/server.js`)
- Mongo connection → MongoDB: connects (evidence: `backend/db/mongo.js`)
- Email logs → MongoDB: stores records
- Outreach user → Analytics dashboard: views metrics (evidence: `README.md`)
- RAG retrieval → Vector connector: searches context (evidence: `frontend/services/langchain.py`)
- Vector connector → Chroma store: queries and adds (evidence: `frontend/utils/chroma_connector.py`)
- Vector connector → Cohere embeddings: embeds documents
