How a01l/clair works
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: app.js Express API · appeals.js Appeal intake and dashboard · worker.js Appeal worker · db.js PostgreSQL
Components 26
API and access
- Express API
src/app.js - Authentication
src/controllers/auth.js - Channel management
src/controllers/channels.js - Appeal API
src/routes/appealRoutes.js - Channel key guard
src/middlewares/channelAuthMiddleware.js - Search API
src/controllers/searchController.js - Reports and analytics
src/controllers/report.js
Appeal processing
- Appeal intake and dashboard
src/controllers/appeals.js - Appeal worker
src/worker.js - Spam detection
src/services/spamService.js - IP metadata
src/services/appealIpMetaService.js - IP lookup
src/services/ipLookupService.js
AI and assistant
- Custom prompts
src/controllers/channelPrompts.js - Gemini analysis
src/services/geminiClient.js - Prompt assembly
src/prompts/promptBuilder.js - Prompt moderation
src/services/promptModerationService.js - AI assistant API
src/controllers/assistantController.js - Assistant sessions and context
src/services/assistantService.js - Assistant modes and prompts
src/prompts/clairAssistantPrompt.js
Data and infrastructure
- RabbitMQ queues
src/queue/rabbit.js - Full-text search
src/search/elastic.js - PostgreSQL
src/db/db.js - Redis cache
src/cache/redis.js
Other components
- Users and channel clients
- Assistant widget
public/clair-widget.js - Google Gemini
Connections 38
- Users and channel clients → Express API: sends requests
src/app.js - Express API → Appeal API: routes appeals
src/app.js - Appeal API → Channel key guard: guards channel intake
src/routes/appealRoutes.js - Appeal API → Appeal intake and dashboard: dispatches
src/routes/appealRoutes.js - Express API → Authentication: routes auth
src/app.js - Express API → Channel management: routes channels
src/app.js - Channel management → PostgreSQL: reads and writes
src/controllers/channels.js - Appeal intake and dashboard → RabbitMQ queues: publishes intake
src/controllers/appeals.js - Appeal worker → RabbitMQ queues: consumes messages
src/worker.js - Appeal worker → Appeal intake and dashboard: processes appeals
src/worker.js - Appeal worker → Spam detection: checks duplicates
src/worker.js - Appeal worker → Gemini analysis: requests classification
src/worker.js - Appeal worker → Full-text search: indexes appeals
src/worker.js - Appeal worker → PostgreSQL: stores results
src/worker.js - Appeal intake and dashboard → Prompt assembly: builds analysis prompt
src/controllers/appeals.js - Appeal intake and dashboard → Gemini analysis: requests analysis
src/controllers/appeals.js - Appeal intake and dashboard → IP lookup: looks up IP
src/controllers/appeals.js - IP lookup → IP metadata: provides IP metadata
- Appeal intake and dashboard → Redis cache: uses dashboard cache
src/controllers/appeals.js - Search API → PostgreSQL: checks channel access
src/controllers/searchController.js - Search API → Full-text search: queries appeals
src/controllers/searchController.js - Express API → Search API: routes search
src/app.js - Express API → Reports and analytics: routes reporting
src/app.js - Reports and analytics → PostgreSQL: reads analytics
- Reports and analytics → Redis cache: uses aggregate cache
- Express API → Custom prompts: routes prompt management
src/app.js - Custom prompts → Prompt moderation: moderates prompt
- Custom prompts → PostgreSQL: stores prompt
src/controllers/channelPrompts.js - Express API → AI assistant API: routes assistant
src/app.js - Assistant widget → Express API: calls assistant API
- AI assistant API → Assistant sessions and context: manages sessions and context
src/controllers/assistantController.js - AI assistant API → Assistant modes and prompts: builds response prompt
src/controllers/assistantController.js - AI assistant API → Gemini analysis: requests response
src/controllers/assistantController.js - Assistant sessions and context → PostgreSQL: reads and writes sessions
src/services/assistantService.js - Gemini analysis → Google Gemini: calls model
- Express API → RabbitMQ queues: initializes broker
src/app.js - Express API → Redis cache: connects cache
src/app.js - Express API → Full-text search: initializes search
src/app.js