# a01l/clair architecture

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

- Interactive diagram: https://gitdiagram.com/a01l/clair
- Repository: https://github.com/a01l/clair

## Overview

Clair is a backend platform for collecting feedback across customer channels, classifying and enriching appeals, then supporting dashboard search, reporting, and an AI assistant. The main path is authenticated or channel-key ingestion, asynchronous RabbitMQ processing, AI/spam and metadata enrichment, and storage/search. The README documents additional moderation, geo, caching, and DLQ capabilities; several implementation files were not excerpted, so those branches are shown at their supported directory level and unverified links are omitted.

Main entry points: [`src/app.js`](https://github.com/a01l/clair/blob/main/src/app.js) (Express API), [`src/controllers/appeals.js`](https://github.com/a01l/clair/blob/main/src/controllers/appeals.js) (Appeal intake and dashboard), [`src/worker.js`](https://github.com/a01l/clair/blob/main/src/worker.js) (Appeal worker), [`src/db/db.js`](https://github.com/a01l/clair/blob/main/src/db/db.js) (PostgreSQL)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_server["Express API<br/>[app.js]"]
  node_auth["Authentication<br/>[auth.js]"]
  node_channels["Channel management<br/>[channels.js]"]
  node_appealroutes["Appeal API<br/>[appealRoutes.js]"]
  node_channelguard["Channel key guard"]
  node_searchapi["Search API"]
  node_reports["Reports and analytics<br/>[report.js]"]
end

subgraph group_appeals["Appeal processing"]
  node_appeals["Appeal intake and dashboard<br/>[appeals.js]"]
  node_worker["Appeal worker<br/>[worker.js]"]
  node_spam["Spam detection<br/>[spamService.js]"]
  node_geo["IP metadata"]
  node_ipservice["IP lookup<br/>[ipLookupService.js]"]
end

subgraph group_ai["AI and assistant"]
  node_customprompts["Custom prompts<br/>[channelPrompts.js]"]
  node_gemini["Gemini analysis<br/>[geminiClient.js]"]
  node_prompts["Prompt assembly<br/>[promptBuilder.js]"]
  node_moderation["Prompt moderation"]
  node_assistant["AI assistant API"]
  node_assistantservice["Assistant sessions and context"]
  node_assistantprompt["Assistant modes and prompts"]
end

subgraph group_platform["Data and infrastructure"]
  node_queue["RabbitMQ queues<br/>[rabbit.js]"]
  node_search["Full-text search<br/>[elastic.js]"]
  node_database[("PostgreSQL<br/>[db.js]")]
  node_cache[("Redis cache<br/>[redis.js]")]
end

node_users(("Users and channel clients"))
node_widget["Assistant widget<br/>[clair-widget.js]"]
node_geminiservice["Google Gemini"]

node_users -->|"sends requests"| node_server
node_server -->|"routes appeals"| node_appealroutes
node_appealroutes -->|"guards channel intake"| node_channelguard
node_appealroutes -->|"dispatches"| node_appeals
node_server -->|"routes auth"| node_auth
node_server -->|"routes channels"| node_channels
node_channels -->|"reads and writes"| node_database
node_appeals -->|"publishes intake"| node_queue
node_worker -->|"consumes messages"| node_queue
node_worker -->|"processes appeals"| node_appeals
node_worker -->|"checks duplicates"| node_spam
node_worker -->|"requests classification"| node_gemini
node_worker -->|"indexes appeals"| node_search
node_worker -->|"stores results"| node_database
node_appeals -->|"builds analysis prompt"| node_prompts
node_appeals -->|"requests analysis"| node_gemini
node_appeals -->|"looks up IP"| node_ipservice
node_ipservice -.->|"provides IP metadata"| node_geo
node_appeals -->|"uses dashboard cache"| node_cache
node_searchapi -->|"checks channel access"| node_database
node_searchapi -->|"queries appeals"| node_search
node_server -->|"routes search"| node_searchapi
node_server -->|"routes reporting"| node_reports
node_reports -.->|"reads analytics"| node_database
node_reports -.->|"uses aggregate cache"| node_cache
node_server -->|"routes prompt management"| node_customprompts
node_customprompts -.->|"moderates prompt"| node_moderation
node_customprompts -->|"stores prompt"| node_database
node_server -->|"routes assistant"| node_assistant
node_widget -.->|"calls assistant API"| node_server
node_assistant -->|"manages sessions and context"| node_assistantservice
node_assistant -->|"builds response prompt"| node_assistantprompt
node_assistant -->|"requests response"| node_gemini
node_assistantservice -->|"reads and writes sessions"| node_database
node_gemini -.->|"calls model"| node_geminiservice
node_server -->|"initializes broker"| node_queue
node_server -->|"connects cache"| node_cache
node_server -->|"initializes search"| node_search

click node_server "https://github.com/a01l/clair/blob/main/src/app.js"
click node_auth "https://github.com/a01l/clair/blob/main/src/controllers/auth.js"
click node_channels "https://github.com/a01l/clair/blob/main/src/controllers/channels.js"
click node_customprompts "https://github.com/a01l/clair/blob/main/src/controllers/channelPrompts.js"
click node_appealroutes "https://github.com/a01l/clair/blob/main/src/routes/appealRoutes.js"
click node_channelguard "https://github.com/a01l/clair/blob/main/src/middlewares/channelAuthMiddleware.js"
click node_appeals "https://github.com/a01l/clair/blob/main/src/controllers/appeals.js"
click node_queue "https://github.com/a01l/clair/blob/main/src/queue/rabbit.js"
click node_worker "https://github.com/a01l/clair/blob/main/src/worker.js"
click node_spam "https://github.com/a01l/clair/blob/main/src/services/spamService.js"
click node_geo "https://github.com/a01l/clair/blob/main/src/services/appealIpMetaService.js"
click node_gemini "https://github.com/a01l/clair/blob/main/src/services/geminiClient.js"
click node_prompts "https://github.com/a01l/clair/blob/main/src/prompts/promptBuilder.js"
click node_moderation "https://github.com/a01l/clair/blob/main/src/services/promptModerationService.js"
click node_assistant "https://github.com/a01l/clair/blob/main/src/controllers/assistantController.js"
click node_assistantservice "https://github.com/a01l/clair/blob/main/src/services/assistantService.js"
click node_assistantprompt "https://github.com/a01l/clair/blob/main/src/prompts/clairAssistantPrompt.js"
click node_searchapi "https://github.com/a01l/clair/blob/main/src/controllers/searchController.js"
click node_search "https://github.com/a01l/clair/blob/main/src/search/elastic.js"
click node_reports "https://github.com/a01l/clair/blob/main/src/controllers/report.js"
click node_database "https://github.com/a01l/clair/blob/main/src/db/db.js"
click node_cache "https://github.com/a01l/clair/blob/main/src/cache/redis.js"
click node_ipservice "https://github.com/a01l/clair/blob/main/src/services/ipLookupService.js"
click node_widget "https://github.com/a01l/clair/blob/main/public/clair-widget.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_server,node_auth,node_channels,node_appealroutes,node_channelguard,node_searchapi,node_reports,node_users toneBlue
class node_appeals,node_worker,node_spam,node_geo,node_ipservice toneAmber
class node_customprompts,node_gemini,node_prompts,node_moderation,node_assistant,node_assistantservice,node_assistantprompt toneMint
class node_queue,node_search,node_database,node_cache toneRose
class node_widget toneTeal
class node_geminiservice toneIndigo
```

## Components

### API and access

- [Express API](https://github.com/a01l/clair/blob/main/src/app.js): `src/app.js`
- [Authentication](https://github.com/a01l/clair/blob/main/src/controllers/auth.js): `src/controllers/auth.js`
- [Channel management](https://github.com/a01l/clair/blob/main/src/controllers/channels.js): `src/controllers/channels.js`
- [Appeal API](https://github.com/a01l/clair/blob/main/src/routes/appealRoutes.js): `src/routes/appealRoutes.js`
- [Channel key guard](https://github.com/a01l/clair/blob/main/src/middlewares/channelAuthMiddleware.js): `src/middlewares/channelAuthMiddleware.js`
- [Search API](https://github.com/a01l/clair/blob/main/src/controllers/searchController.js): `src/controllers/searchController.js`
- [Reports and analytics](https://github.com/a01l/clair/blob/main/src/controllers/report.js): `src/controllers/report.js`

### Appeal processing

- [Appeal intake and dashboard](https://github.com/a01l/clair/blob/main/src/controllers/appeals.js): `src/controllers/appeals.js`
- [Appeal worker](https://github.com/a01l/clair/blob/main/src/worker.js): `src/worker.js`
- [Spam detection](https://github.com/a01l/clair/blob/main/src/services/spamService.js): `src/services/spamService.js`
- [IP metadata](https://github.com/a01l/clair/blob/main/src/services/appealIpMetaService.js): `src/services/appealIpMetaService.js`
- [IP lookup](https://github.com/a01l/clair/blob/main/src/services/ipLookupService.js): `src/services/ipLookupService.js`

### AI and assistant

- [Custom prompts](https://github.com/a01l/clair/blob/main/src/controllers/channelPrompts.js): `src/controllers/channelPrompts.js`
- [Gemini analysis](https://github.com/a01l/clair/blob/main/src/services/geminiClient.js): `src/services/geminiClient.js`
- [Prompt assembly](https://github.com/a01l/clair/blob/main/src/prompts/promptBuilder.js): `src/prompts/promptBuilder.js`
- [Prompt moderation](https://github.com/a01l/clair/blob/main/src/services/promptModerationService.js): `src/services/promptModerationService.js`
- [AI assistant API](https://github.com/a01l/clair/blob/main/src/controllers/assistantController.js): `src/controllers/assistantController.js`
- [Assistant sessions and context](https://github.com/a01l/clair/blob/main/src/services/assistantService.js): `src/services/assistantService.js`
- [Assistant modes and prompts](https://github.com/a01l/clair/blob/main/src/prompts/clairAssistantPrompt.js): `src/prompts/clairAssistantPrompt.js`

### Data and infrastructure

- [RabbitMQ queues](https://github.com/a01l/clair/blob/main/src/queue/rabbit.js): `src/queue/rabbit.js`
- [Full-text search](https://github.com/a01l/clair/blob/main/src/search/elastic.js): `src/search/elastic.js`
- [PostgreSQL](https://github.com/a01l/clair/blob/main/src/db/db.js): `src/db/db.js`
- [Redis cache](https://github.com/a01l/clair/blob/main/src/cache/redis.js): `src/cache/redis.js`

### Other components

- **Users and channel clients**
- [Assistant widget](https://github.com/a01l/clair/blob/main/public/clair-widget.js): `public/clair-widget.js`
- **Google Gemini**

## Connections

- Users and channel clients → Express API: sends requests (evidence: `src/app.js`)
- Express API → Appeal API: routes appeals (evidence: `src/app.js`)
- Appeal API → Channel key guard: guards channel intake (evidence: `src/routes/appealRoutes.js`)
- Appeal API → Appeal intake and dashboard: dispatches (evidence: `src/routes/appealRoutes.js`)
- Express API → Authentication: routes auth (evidence: `src/app.js`)
- Express API → Channel management: routes channels (evidence: `src/app.js`)
- Channel management → PostgreSQL: reads and writes (evidence: `src/controllers/channels.js`)
- Appeal intake and dashboard → RabbitMQ queues: publishes intake (evidence: `src/controllers/appeals.js`)
- Appeal worker → RabbitMQ queues: consumes messages (evidence: `src/worker.js`)
- Appeal worker → Appeal intake and dashboard: processes appeals (evidence: `src/worker.js`)
- Appeal worker → Spam detection: checks duplicates (evidence: `src/worker.js`)
- Appeal worker → Gemini analysis: requests classification (evidence: `src/worker.js`)
- Appeal worker → Full-text search: indexes appeals (evidence: `src/worker.js`)
- Appeal worker → PostgreSQL: stores results (evidence: `src/worker.js`)
- Appeal intake and dashboard → Prompt assembly: builds analysis prompt (evidence: `src/controllers/appeals.js`)
- Appeal intake and dashboard → Gemini analysis: requests analysis (evidence: `src/controllers/appeals.js`)
- Appeal intake and dashboard → IP lookup: looks up IP (evidence: `src/controllers/appeals.js`)
- IP lookup → IP metadata: provides IP metadata
- Appeal intake and dashboard → Redis cache: uses dashboard cache (evidence: `src/controllers/appeals.js`)
- Search API → PostgreSQL: checks channel access (evidence: `src/controllers/searchController.js`)
- Search API → Full-text search: queries appeals (evidence: `src/controllers/searchController.js`)
- Express API → Search API: routes search (evidence: `src/app.js`)
- Express API → Reports and analytics: routes reporting (evidence: `src/app.js`)
- Reports and analytics → PostgreSQL: reads analytics
- Reports and analytics → Redis cache: uses aggregate cache
- Express API → Custom prompts: routes prompt management (evidence: `src/app.js`)
- Custom prompts → Prompt moderation: moderates prompt
- Custom prompts → PostgreSQL: stores prompt (evidence: `src/controllers/channelPrompts.js`)
- Express API → AI assistant API: routes assistant (evidence: `src/app.js`)
- Assistant widget → Express API: calls assistant API
- AI assistant API → Assistant sessions and context: manages sessions and context (evidence: `src/controllers/assistantController.js`)
- AI assistant API → Assistant modes and prompts: builds response prompt (evidence: `src/controllers/assistantController.js`)
- AI assistant API → Gemini analysis: requests response (evidence: `src/controllers/assistantController.js`)
- Assistant sessions and context → PostgreSQL: reads and writes sessions (evidence: `src/services/assistantService.js`)
- Gemini analysis → Google Gemini: calls model
- Express API → RabbitMQ queues: initializes broker (evidence: `src/app.js`)
- Express API → Redis cache: connects cache (evidence: `src/app.js`)
- Express API → Full-text search: initializes search (evidence: `src/app.js`)
