# sabarishpv/minipulse architecture

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

## Overview

MiniPulse is a two-service Slack bot for answering natural-language questions about HubSpot CRM data. A Slack mention is verified and deduplicated by the adapter, which forwards the question and thread ID to the AI service; the service applies guardrails and preserves per-thread history, then Gemini selects read-only CRM tools and returns an answer for posting into the Slack thread. The tools share a single HubSpot client. README documents the service boundary and tool capabilities; some internal tool-to-client details are supported by sampled source and the SOURCE INDEX, while unsampled implementation details are not inferred.

Main entry points: [`ai-service/app/tools/__init__.py`](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/__init__.py) (Tool registry), [`ai-service/app/hubspot/client.py`](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/hubspot/client.py) (HubSpot client), [`ai-service/app/llm/client.py`](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/llm/client.py) (Gemini tool loop), [`slack-adapter/app/main.py`](https://github.com/sabarishpv/minipulse/blob/main/slack-adapter/app/main.py) (Event adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_slack["Slack adapter"]
  node_adapter["Event adapter<br/>[main.py]"]
end

subgraph group_orchestration["AI orchestration"]
  node_ai_api["Ask API<br/>[main.py]"]
  node_ai_service["Conversation service<br/>[ai_service.py]"]
  node_thread_history["Thread history<br/>[ai_service.py]"]
  node_gemini_client["Gemini tool loop<br/>[client.py]"]
  node_system_prompt["System prompt<br/>[system_prompt.py]"]
end

subgraph group_crm_tools["CRM query tools"]
  node_tool_registry["Tool registry<br/>[__init__.py]"]
  node_count_deals["Count by stage<br/>[deals.py]"]
  node_search_deals["Search deals<br/>[search.py]"]
  node_contact_lookup["Contact lookup<br/>[contacts.py]"]
  node_deal_owner["Deal owner<br/>[owners.py]"]
  node_deal_summary["Recent deal summary<br/>[summary.py]"]
  node_company_list["New companies<br/>[companies.py]"]
end

subgraph group_integrations["External integrations"]
  node_slack_platform["Slack events"]
  node_hubspot_client["HubSpot client<br/>[client.py]"]
  node_hubspot_api["HubSpot CRM API"]
  node_gemini_api["Gemini API"]
end

node_user(("Slack user"))

node_user -->|"asks in"| node_slack_platform
node_slack_platform -->|"delivers event"| node_adapter
node_adapter -->|"forwards question"| node_ai_api
node_ai_api -->|"calls"| node_ai_service
node_ai_service -->|"loads and saves"| node_thread_history
node_ai_service -->|"runs conversation"| node_gemini_client
node_gemini_client -->|"configures with"| node_system_prompt
node_gemini_client -->|"calls"| node_gemini_api
node_gemini_client -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"registers"| node_count_deals
node_tool_registry -->|"registers"| node_search_deals
node_tool_registry -->|"registers"| node_contact_lookup
node_tool_registry -->|"registers"| node_deal_owner
node_tool_registry -->|"registers"| node_deal_summary
node_tool_registry -->|"registers"| node_company_list
node_count_deals -->|"queries"| node_hubspot_client
node_search_deals -->|"queries"| node_hubspot_client
node_contact_lookup -->|"queries"| node_hubspot_client
node_deal_owner -->|"queries"| node_hubspot_client
node_deal_summary -->|"queries"| node_hubspot_client
node_company_list -->|"queries"| node_hubspot_client
node_hubspot_client -->|"requests CRM data"| node_hubspot_api
node_adapter -->|"posts reply"| node_slack_platform

click node_adapter "https://github.com/sabarishpv/minipulse/blob/main/slack-adapter/app/main.py"
click node_ai_api "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/main.py"
click node_ai_service "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/ai_service.py"
click node_thread_history "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/ai_service.py"
click node_gemini_client "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/llm/client.py"
click node_system_prompt "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/llm/system_prompt.py"
click node_tool_registry "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/__init__.py"
click node_count_deals "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/deals.py"
click node_search_deals "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/search.py"
click node_contact_lookup "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/contacts.py"
click node_deal_owner "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/owners.py"
click node_deal_summary "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/summary.py"
click node_company_list "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/companies.py"
click node_hubspot_client "https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/hubspot/client.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_adapter,node_user toneBlue
class node_ai_api,node_ai_service,node_thread_history,node_gemini_client,node_system_prompt toneAmber
class node_tool_registry,node_count_deals,node_search_deals,node_contact_lookup,node_deal_owner,node_deal_summary,node_company_list toneMint
class node_slack_platform,node_hubspot_client,node_hubspot_api,node_gemini_api toneRose
```

## Components

### Slack adapter

- [Event adapter](https://github.com/sabarishpv/minipulse/blob/main/slack-adapter/app/main.py): `slack-adapter/app/main.py`

### AI orchestration

- [Ask API](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/main.py): `ai-service/app/main.py`
- [Conversation service](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/ai_service.py): `ai-service/app/ai_service.py`
- [Thread history](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/ai_service.py): `ai-service/app/ai_service.py`
- [Gemini tool loop](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/llm/client.py): `ai-service/app/llm/client.py`
- [System prompt](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/llm/system_prompt.py): `ai-service/app/llm/system_prompt.py`

### CRM query tools

- [Tool registry](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/__init__.py): `ai-service/app/tools/__init__.py`
- [Count by stage](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/deals.py): `ai-service/app/tools/deals.py`
- [Search deals](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/search.py): `ai-service/app/tools/search.py`
- [Contact lookup](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/contacts.py): `ai-service/app/tools/contacts.py`
- [Deal owner](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/owners.py): `ai-service/app/tools/owners.py`
- [Recent deal summary](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/summary.py): `ai-service/app/tools/summary.py`
- [New companies](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/tools/companies.py): `ai-service/app/tools/companies.py`

### External integrations

- **Slack events**
- [HubSpot client](https://github.com/sabarishpv/minipulse/blob/main/ai-service/app/hubspot/client.py): `ai-service/app/hubspot/client.py`
- **HubSpot CRM API**
- **Gemini API**

### Other components

- **Slack user**

## Connections

- Slack user → Slack events: asks in (evidence: `README.md`)
- Slack events → Event adapter: delivers event (evidence: `README.md`)
- Event adapter → Ask API: forwards question (evidence: `slack-adapter/app/main.py`)
- Ask API → Conversation service: calls (evidence: `ai-service/app/main.py`)
- Conversation service → Thread history: loads and saves (evidence: `ai-service/app/ai_service.py`)
- Conversation service → Gemini tool loop: runs conversation (evidence: `ai-service/app/ai_service.py`)
- Gemini tool loop → System prompt: configures with (evidence: `ai-service/app/llm/client.py`)
- Gemini tool loop → Gemini API: calls (evidence: `README.md`)
- Gemini tool loop → Tool registry: dispatches tools (evidence: `ai-service/app/llm/client.py`)
- Tool registry → Count by stage: registers (evidence: `ai-service/app/tools/__init__.py`)
- Tool registry → Search deals: registers (evidence: `ai-service/app/tools/__init__.py`)
- Tool registry → Contact lookup: registers (evidence: `ai-service/app/tools/__init__.py`)
- Tool registry → Deal owner: registers (evidence: `ai-service/app/tools/__init__.py`)
- Tool registry → Recent deal summary: registers (evidence: `ai-service/app/tools/__init__.py`)
- Tool registry → New companies: registers (evidence: `ai-service/app/tools/__init__.py`)
- Count by stage → HubSpot client: queries (evidence: `ai-service/app/tools/deals.py`)
- Search deals → HubSpot client: queries (evidence: `ai-service/app/tools/search.py`)
- Contact lookup → HubSpot client: queries (evidence: `ai-service/app/tools/contacts.py`)
- Deal owner → HubSpot client: queries (evidence: `ai-service/app/tools/owners.py`)
- Recent deal summary → HubSpot client: queries (evidence: `ai-service/app/tools/summary.py`)
- New companies → HubSpot client: queries (evidence: `ai-service/app/tools/companies.py`)
- HubSpot client → HubSpot CRM API: requests CRM data (evidence: `README.md`)
- Event adapter → Slack events: posts reply (evidence: `slack-adapter/app/main.py`)
