# sissoko90/uniconnect-ai architecture

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

- Interactive diagram: https://gitdiagram.com/sissoko90/uniconnect-ai
- Repository: https://github.com/sissoko90/uniconnect-ai

## Overview

UniConnect AI ingests a group’s chat, call recordings, and shared documents into a searchable history, then answers members with citations or refuses when evidence is missing. Members interact through a WhatsApp worker or the API; the worker decides when group replies are appropriate, while the API routes requests to retrieval and answer features. The README documents hybrid retrieval and Claude-grounded answers. Sampled source confirms live ingestion, voice handling, and worker/API calls; several other feature links reflect README capabilities and their exact enclosing source paths, not inspected call sites.

Main entry points: [`core/main.py`](https://github.com/sissoko90/uniconnect-ai/blob/main/core/main.py) (FastAPI surface), [`db/schema.sql`](https://github.com/sissoko90/uniconnect-ai/blob/main/db/schema.sql) (PostgreSQL and pgvector), [`core/answer.py`](https://github.com/sissoko90/uniconnect-ai/blob/main/core/answer.py) (Hybrid retrieval), [`adapters/whatsapp/index.js`](https://github.com/sissoko90/uniconnect-ai/blob/main/adapters/whatsapp/index.js) (WhatsApp worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interact["Member interaction"]
  node_worker["WhatsApp worker<br/>[index.js]"]
  node_workerapi["API client<br/>[api.js]"]
  node_http["FastAPI surface<br/>[main.py]"]
end

subgraph group_ingest["History ingestion"]
  node_chatparse["Export parser<br/>[parse_whatsapp.py]"]
  node_liveingest["Live message ingestion<br/>[ingest.py]"]
  node_transcribe["Call transcription<br/>[transcribe.py]"]
  node_documents["Document ingestion<br/>[document.py]"]
  node_embedload["Document embedding<br/>[embed.py]"]
end

subgraph group_answer["Answers and retrieval"]
  node_retrieval["Hybrid retrieval<br/>[answer.py]"]
  node_queryembed["Query embeddings<br/>[embeddings.py]"]
  node_intent["Intent routing<br/>[intent.py]"]
end

subgraph group_features["Group features"]
  node_catchup["Personal catch-up<br/>[catchup.py]"]
  node_recap["Daily recap<br/>[recap.py]"]
  node_vision["Image questions<br/>[vision.py]"]
  node_voice["Voice notes<br/>[voice.py]"]
  node_polls["Polls<br/>[poll.py]"]
  node_alerts["Mention alerts<br/>[alerts.py]"]
  node_people["People lookup<br/>[identity.py]"]
  node_documentsvc["Document rendering<br/>[documents.py]"]
end

subgraph group_state["Persistence and identity"]
  node_db[("PostgreSQL and pgvector<br/>[schema.sql]")]
  node_auth["Worker authentication<br/>[auth.py]"]
end

node_members(("Group members"))
node_whatsapp(("WhatsApp"))
node_claude(("Claude"))
node_voyage(("Voyage embeddings"))
node_groq(("Groq transcription"))

node_members -->|"message"| node_whatsapp
node_whatsapp -->|"deliver chats"| node_worker
node_worker -->|"request API"| node_workerapi
node_workerapi -->|"HTTP calls"| node_http
node_http -->|"authorize worker"| node_auth
node_http -->|"answer query"| node_retrieval
node_http -->|"route intent"| node_intent
node_retrieval -->|"embed query"| node_queryembed
node_queryembed -.->|"request vector"| node_voyage
node_retrieval -->|"hybrid search"| node_db
node_retrieval -.->|"ground answer"| node_claude
node_http -->|"request briefing"| node_catchup
node_http -->|"request digest"| node_recap
node_http -->|"handle image"| node_vision
node_http -->|"store voice note"| node_voice
node_http -->|"poll actions"| node_polls
node_http -->|"alert actions"| node_alerts
node_http -->|"resolve people"| node_people
node_http -->|"render document"| node_documentsvc
node_chatparse -->|"load messages"| node_db
node_workerapi -->|"post messages"| node_liveingest
node_liveingest -->|"store messages"| node_db
node_transcribe -.->|"transcribe audio"| node_groq
node_transcribe -->|"store transcript"| node_db
node_documents -->|"store chunks"| node_db
node_embedload -->|"write vectors"| node_db
node_members -->|"ask questions"| node_http
node_worker -->|"send reply"| node_members
node_catchup -->|"read history"| node_db
node_recap -->|"read history"| node_db
node_voice -->|"store transcript"| node_db
node_people -->|"lookup names"| node_db
node_alerts -->|"read mentions"| node_db
node_polls -->|"store votes"| node_db
node_documentsvc -->|"read document"| node_db

click node_worker "https://github.com/sissoko90/uniconnect-ai/blob/main/adapters/whatsapp/index.js"
click node_workerapi "https://github.com/sissoko90/uniconnect-ai/blob/main/adapters/whatsapp/api.js"
click node_http "https://github.com/sissoko90/uniconnect-ai/blob/main/core/main.py"
click node_chatparse "https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/parse_whatsapp.py"
click node_liveingest "https://github.com/sissoko90/uniconnect-ai/blob/main/core/ingest.py"
click node_transcribe "https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/transcribe.py"
click node_documents "https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/document.py"
click node_embedload "https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/embed.py"
click node_retrieval "https://github.com/sissoko90/uniconnect-ai/blob/main/core/answer.py"
click node_queryembed "https://github.com/sissoko90/uniconnect-ai/blob/main/core/embeddings.py"
click node_intent "https://github.com/sissoko90/uniconnect-ai/blob/main/core/intent.py"
click node_catchup "https://github.com/sissoko90/uniconnect-ai/blob/main/core/catchup.py"
click node_recap "https://github.com/sissoko90/uniconnect-ai/blob/main/core/recap.py"
click node_vision "https://github.com/sissoko90/uniconnect-ai/blob/main/core/vision.py"
click node_voice "https://github.com/sissoko90/uniconnect-ai/blob/main/core/voice.py"
click node_polls "https://github.com/sissoko90/uniconnect-ai/blob/main/core/poll.py"
click node_alerts "https://github.com/sissoko90/uniconnect-ai/blob/main/core/alerts.py"
click node_people "https://github.com/sissoko90/uniconnect-ai/blob/main/core/identity.py"
click node_documentsvc "https://github.com/sissoko90/uniconnect-ai/blob/main/core/documents.py"
click node_db "https://github.com/sissoko90/uniconnect-ai/blob/main/db/schema.sql"
click node_auth "https://github.com/sissoko90/uniconnect-ai/blob/main/core/auth.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_worker,node_workerapi,node_http toneBlue
class node_chatparse,node_liveingest,node_transcribe,node_documents,node_embedload toneAmber
class node_retrieval,node_queryembed,node_intent toneMint
class node_catchup,node_recap,node_vision,node_voice,node_polls,node_alerts,node_people,node_documentsvc toneRose
class node_db,node_auth,node_members,node_whatsapp,node_claude,node_voyage,node_groq toneIndigo
```

## Components

### Member interaction

- [WhatsApp worker](https://github.com/sissoko90/uniconnect-ai/blob/main/adapters/whatsapp/index.js): `adapters/whatsapp/index.js`
- [API client](https://github.com/sissoko90/uniconnect-ai/blob/main/adapters/whatsapp/api.js): `adapters/whatsapp/api.js`
- [FastAPI surface](https://github.com/sissoko90/uniconnect-ai/blob/main/core/main.py): `core/main.py`

### History ingestion

- [Export parser](https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/parse_whatsapp.py): `ingestion/parse_whatsapp.py`
- [Live message ingestion](https://github.com/sissoko90/uniconnect-ai/blob/main/core/ingest.py): `core/ingest.py`
- [Call transcription](https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/transcribe.py): `ingestion/transcribe.py`
- [Document ingestion](https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/document.py): `ingestion/document.py`
- [Document embedding](https://github.com/sissoko90/uniconnect-ai/blob/main/ingestion/embed.py): `ingestion/embed.py`

### Answers and retrieval

- [Hybrid retrieval](https://github.com/sissoko90/uniconnect-ai/blob/main/core/answer.py): `core/answer.py`
- [Query embeddings](https://github.com/sissoko90/uniconnect-ai/blob/main/core/embeddings.py): `core/embeddings.py`
- [Intent routing](https://github.com/sissoko90/uniconnect-ai/blob/main/core/intent.py): `core/intent.py`

### Group features

- [Personal catch-up](https://github.com/sissoko90/uniconnect-ai/blob/main/core/catchup.py): `core/catchup.py`
- [Daily recap](https://github.com/sissoko90/uniconnect-ai/blob/main/core/recap.py): `core/recap.py`
- [Image questions](https://github.com/sissoko90/uniconnect-ai/blob/main/core/vision.py): `core/vision.py`
- [Voice notes](https://github.com/sissoko90/uniconnect-ai/blob/main/core/voice.py): `core/voice.py`
- [Polls](https://github.com/sissoko90/uniconnect-ai/blob/main/core/poll.py): `core/poll.py`
- [Mention alerts](https://github.com/sissoko90/uniconnect-ai/blob/main/core/alerts.py): `core/alerts.py`
- [People lookup](https://github.com/sissoko90/uniconnect-ai/blob/main/core/identity.py): `core/identity.py`
- [Document rendering](https://github.com/sissoko90/uniconnect-ai/blob/main/core/documents.py): `core/documents.py`

### Persistence and identity

- [PostgreSQL and pgvector](https://github.com/sissoko90/uniconnect-ai/blob/main/db/schema.sql): `db/schema.sql`
- [Worker authentication](https://github.com/sissoko90/uniconnect-ai/blob/main/core/auth.py): `core/auth.py`

### Other components

- **Group members**
- **WhatsApp**
- **Claude**
- **Voyage embeddings**
- **Groq transcription**

## Connections

- Group members → WhatsApp: message
- WhatsApp → WhatsApp worker: deliver chats
- WhatsApp worker → API client: request API
- API client → FastAPI surface: HTTP calls
- FastAPI surface → Worker authentication: authorize worker
- FastAPI surface → Hybrid retrieval: answer query
- FastAPI surface → Intent routing: route intent
- Hybrid retrieval → Query embeddings: embed query
- Query embeddings → Voyage embeddings: request vector
- Hybrid retrieval → PostgreSQL and pgvector: hybrid search
- Hybrid retrieval → Claude: ground answer
- FastAPI surface → Personal catch-up: request briefing
- FastAPI surface → Daily recap: request digest
- FastAPI surface → Image questions: handle image
- FastAPI surface → Voice notes: store voice note
- FastAPI surface → Polls: poll actions
- FastAPI surface → Mention alerts: alert actions
- FastAPI surface → People lookup: resolve people
- FastAPI surface → Document rendering: render document
- Export parser → PostgreSQL and pgvector: load messages
- API client → Live message ingestion: post messages
- Live message ingestion → PostgreSQL and pgvector: store messages
- Call transcription → Groq transcription: transcribe audio
- Call transcription → PostgreSQL and pgvector: store transcript
- Document ingestion → PostgreSQL and pgvector: store chunks
- Document embedding → PostgreSQL and pgvector: write vectors
- Group members → FastAPI surface: ask questions
- WhatsApp worker → Group members: send reply
- Personal catch-up → PostgreSQL and pgvector: read history
- Daily recap → PostgreSQL and pgvector: read history
- Voice notes → PostgreSQL and pgvector: store transcript
- People lookup → PostgreSQL and pgvector: lookup names
- Mention alerts → PostgreSQL and pgvector: read mentions
- Polls → PostgreSQL and pgvector: store votes
- Document rendering → PostgreSQL and pgvector: read document