# rvs-30/yikes-slack-bot architecture

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

- Interactive diagram: https://gitdiagram.com/rvs-30/yikes-slack-bot
- Repository: https://github.com/rvs-30/yikes-slack-bot

## Overview

1. **What this repo is**
   Yikes is a Slack memory system built as a Node.js service. It ingests Slack channel messages, stores them in PostgreSQL/Supabase, enriches them with Gemini, embeds thread history for vector search, and answers `/memory` queries with RAG-style retrieval.

2. **Top-level runtime shape**
   The app is split into a main Slack-facing process and a background worker process. `index.js` and `src/app.js` boot the Bolt-based Slack app and HTTP listener, while `src/workers/startAwarenessWorker.js` launches the asynchronous enrichment worker. This separation is important because ingestion/response latency is kept distinct from AI processing.

3. **Slack event ingress**
   `src/listeners/events/message.js` handles message events, and `src/listeners/events/app-mention.js` handles direct mentions. `src/listeners/commands/memory.js` handles the `/memory` slash command. These listeners form the only inbound surface from Slack and are the first architectural boundary.

4. **Persistence layer**
   `src/repositories/` and `src/models/` encapsulate database access to PostgreSQL. The core stores are:
   - `messages`: raw Slack message ingestion plus processing state
   - `thread_embeddings`: vectorized thread summaries/content
   - `interaction_log`: audit trail and context window for commands
   - `users` and `user_channel_memberships`: identity cache and access-control data  
   The repo is designed around Supabase with pgvector enabled.

5. **Ingestion pipeline**
   When a Slack message arrives, it is persisted, then marked for downstream processing. The README describes the flow as: Slack event → PostgreSQL → BullMQ/Redis queue → awareness worker. The queue boundary is implemented in `src/queues/awareness.queue.js`, which decouples event intake from AI enrichment.

6. **Background enrichment**
   `src/workers/awareness.worker.js` is the asynchronous AI enrichment stage. It uses services in `src/services/awareness.service.js`, `embedding.service.js`, `summary.service.js`, `search.service.js`, and related modules to classify messages, extract entities, score importance, and mark threads as dirty for later embedding.

7. **Embedding pipeline**
   `src/schedulers/embedding.scheduler.js` is the periodic batch job, driven by `node-cron`. It picks up dirty threads, rebuilds thread content through `context.service.js` and `rag.service.js`, then writes a 768-dimensional embedding to `thread_embeddings`. This is the persistent semantic memory layer, backed by an HNSW vector index in PostgreSQL.

8. **Query and answer path**
   `/memory` requests go through membership checks first, then into hybrid retrieval. The query path uses `membership.service.js` to resolve which channels the user can access, `search.service.js` to combine vector and keyword search, and `rag.service.js`/`context.service.js` to feed retrieved context into Gemini for answer generation. Responses can be ephemeral or posted back to Slack.

9. **Security boundary**
   The architecture is intentionally channel-gated. DMs are blocked at the listener layer, and every query is constrained by `user_channel_memberships` at the SQL level so inaccessible private-channel data cannot leak. Membership state is cached in PostgreSQL and refreshed from Slack on a TTL basis.

10. **Cross-cutting utilities and middleware**
   `src/middleware/logger.middleware.js` provides request/event logging. `src/config/database.js` and `src/config/environment.js` centralize connection/env setup. `src/utils/text.utils.js` supports text normalization and content assembly. These are supporting pieces rather than core subsystems, but they keep the ingestion, worker, and query paths consistent.

11. **External services that materially shape the design**
   The architecture depends on Slack Bolt for event/command handling, PostgreSQL on Supabase for durable storage and vector search, Redis/BullMQ for async processing, and Gemini for both classification and generation. Those choices explain why the repo is organized around event listeners, queues, schedulers, and service layers rather than a single synchronous request handler.

12. **How to draw the architecture**
   A good diagram would show three main flows: inbound Slack events into persistence and queueing; background worker/scheduler turning stored messages into embeddings; and `/memory` queries reading from membership-gated PostgreSQL and Gemini-backed retrieval. The clear trust boundaries are Slack ingress, database access, background AI processing, and membership-enforced query access.

Main entry points: [`src/app.js`](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/app.js) (Slack app), [`src/listeners/index.js`](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/index.js) (Listeners), [`src/services/rag.service.js`](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/rag.service.js) (RAG), [`src/listeners/commands/memory.js`](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/commands/memory.js) (/memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Slack runtime"]
  node_index["index.js<br/>entrypoint<br/>[index.js]"]
  node_app["Slack app<br/>bolt app<br/>[app.js]"]
  node_listeners["Listeners<br/>slack ingress<br/>[index.js]"]
  node_message_listener["Message event<br/>event handler<br/>[message.js]"]
  node_mention_listener["Mention event<br/>event handler<br/>[app-mention.js]"]
  node_memory_command["/memory<br/>slash command<br/>[memory.js]"]
end

subgraph group_ai["AI pipeline"]
  node_awareness_queue["Awareness queue<br/>bullmq queue<br/>[awareness.queue.js]"]
  node_awareness_worker["Awareness worker<br/>async worker"]
  node_worker_boot["Worker boot<br/>worker launcher"]
  node_awareness_service["Awareness<br/>enrichment service"]
  node_summary_service["Summary<br/>llm service<br/>[summary.service.js]"]
  node_embedding_service["Embeddings<br/>vector service"]
  node_search_service["Search<br/>retrieval service<br/>[search.service.js]"]
  node_rag_service["RAG<br/>answer service<br/>[rag.service.js]"]
  node_context_service["Context<br/>[context.service.js]"]
  node_embedding_scheduler["Embedding job<br/>cron scheduler"]
end

subgraph group_data["Data layer"]
  node_messages[("Messages<br/>message model<br/>[message.model.js]")]
  node_message_repo["Message repo<br/>db access"]
  node_membership["Membership<br/>access control"]
  node_save_service["Save service<br/>ingest service<br/>[save.service.js]"]
end

subgraph group_support["Support"]
  node_logger["Logger<br/>middleware"]
  node_config["Config<br/>env/db setup<br/>[environment.js]"]
  node_text_utils["Text utils<br/>[text.utils.js]"]
end

node_index -->|"boot"| node_app
node_app -->|"register"| node_listeners
node_listeners -->|"message"| node_message_listener
node_listeners -->|"mention"| node_mention_listener
node_listeners -->|"command"| node_memory_command
node_app -->|"log"| node_logger
node_app -->|"init"| node_config
node_message_listener -->|"persist"| node_save_service
node_save_service -->|"db write"| node_message_repo
node_message_repo -->|"maps"| node_messages
node_save_service -->|"enqueue"| node_awareness_queue
node_awareness_queue -->|"start"| node_worker_boot
node_worker_boot -->|"run"| node_awareness_worker
node_awareness_worker -->|"enrich"| node_awareness_service
node_awareness_service -->|"summarize"| node_summary_service
node_awareness_service -->|"prepare"| node_embedding_service
node_embedding_scheduler -->|"build"| node_context_service
node_embedding_scheduler -->|"assemble"| node_rag_service
node_rag_service -->|"retrieve"| node_search_service
node_search_service -->|"gate"| node_membership
node_membership -->|"lookup"| node_message_repo
node_rag_service -->|"context"| node_context_service
node_memory_command -->|"authorize"| node_membership
node_memory_command -->|"answer"| node_rag_service
node_context_service -->|"normalize"| node_text_utils

click node_index "https://github.com/rvs-30/yikes-slack-bot/blob/main/index.js"
click node_app "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/app.js"
click node_listeners "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/index.js"
click node_message_listener "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/events/message.js"
click node_mention_listener "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/events/app-mention.js"
click node_memory_command "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/commands/memory.js"
click node_logger "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/middleware/logger.middleware.js"
click node_config "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/config/environment.js"
click node_messages "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/models/message.model.js"
click node_message_repo "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/repositories/message.repository.js"
click node_membership "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/membership.service.js"
click node_save_service "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/save.service.js"
click node_awareness_queue "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/queues/awareness.queue.js"
click node_awareness_worker "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/workers/awareness.worker.js"
click node_worker_boot "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/workers/startAwarenessWorker.js"
click node_awareness_service "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/awareness.service.js"
click node_summary_service "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/summary.service.js"
click node_embedding_service "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/embedding.service.js"
click node_search_service "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/search.service.js"
click node_rag_service "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/rag.service.js"
click node_context_service "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/context.service.js"
click node_embedding_scheduler "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/schedulers/embedding.scheduler.js"
click node_text_utils "https://github.com/rvs-30/yikes-slack-bot/blob/main/src/utils/text.utils.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_index,node_app,node_listeners,node_message_listener,node_mention_listener,node_memory_command toneBlue
class node_awareness_queue,node_awareness_worker,node_worker_boot,node_awareness_service,node_summary_service,node_embedding_service,node_search_service,node_rag_service,node_context_service,node_embedding_scheduler toneAmber
class node_messages,node_message_repo,node_membership,node_save_service toneMint
class node_logger,node_config,node_text_utils toneRose
```

## Components

### Slack runtime

Main Bolt app and inbound Slack handlers.

- [index.js](https://github.com/rvs-30/yikes-slack-bot/blob/main/index.js): entrypoint · Boots the service process. · `index.js`
- [Slack app](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/app.js): bolt app · Initializes the Bolt listener and HTTP server. · `src/app.js`
- [Listeners](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/index.js): slack ingress · Routes Slack events and commands. · `src/listeners/index.js`
- [Message event](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/events/message.js): event handler · Ingests channel messages from Slack. · `src/listeners/events/message.js`
- [Mention event](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/events/app-mention.js): event handler · Handles direct app mentions. · `src/listeners/events/app-mention.js`
- [/memory](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/listeners/commands/memory.js): slash command · Handles retrieval queries from Slack. · `src/listeners/commands/memory.js`

### AI pipeline

Background enrichment, embedding, and retrieval stages.

- [Awareness queue](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/queues/awareness.queue.js): bullmq queue · Decouples ingestion from AI enrichment. · `src/queues/awareness.queue.js`
- [Awareness worker](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/workers/awareness.worker.js): async worker · Processes queued messages for enrichment. · `src/workers/awareness.worker.js`
- [Worker boot](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/workers/startAwarenessWorker.js): worker launcher · Starts the background worker process. · `src/workers/startAwarenessWorker.js`
- [Awareness](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/awareness.service.js): enrichment service · Classifies messages and marks threads dirty. · `src/services/awareness.service.js`
- [Summary](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/summary.service.js): llm service · Builds thread summaries for memory. · `src/services/summary.service.js`
- [Embeddings](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/embedding.service.js): vector service · Creates vectors for thread memory. · `src/services/embedding.service.js`
- [Search](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/search.service.js): retrieval service · Combines keyword and vector search. · `src/services/search.service.js`
- [RAG](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/rag.service.js): answer service · Assembles context and generates answers. · `src/services/rag.service.js`
- [Context](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/context.service.js): context builder · Reconstructs thread and query context. · `src/services/context.service.js`
- [Embedding job](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/schedulers/embedding.scheduler.js): cron scheduler · Rebuilds dirty thread embeddings on a schedule. · `src/schedulers/embedding.scheduler.js`

### Data layer

Persistence, models, and PostgreSQL-backed state.

- [Messages](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/models/message.model.js): message model · Represents Slack message records and state. · `src/models/message.model.js`
- [Message repo](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/repositories/message.repository.js): db access · Persistence operations for message storage. · `src/repositories/message.repository.js`
- [Membership](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/membership.service.js): access control · Resolves channel access for users. · `src/services/membership.service.js`
- [Save service](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/services/save.service.js): ingest service · Stores inbound messages and processing metadata. · `src/services/save.service.js`

### Support

Cross-cutting config, middleware, and utilities.

- [Logger](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/middleware/logger.middleware.js): middleware · Central event and request logging. · `src/middleware/logger.middleware.js`
- [Config](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/config/environment.js): env/db setup · Environment and database configuration. · `src/config/environment.js`
- [Text utils](https://github.com/rvs-30/yikes-slack-bot/blob/main/src/utils/text.utils.js): utility · Normalizes and assembles text content. · `src/utils/text.utils.js`

## Connections

- index.js → Slack app: boot · Starts the main Slack-facing process.
- Slack app → Listeners: register · Wires inbound Slack handlers.
- Listeners → Message event: message · Routes channel message events.
- Listeners → Mention event: mention · Routes app mentions.
- Listeners → /memory: command · Routes /memory queries.
- Slack app → Logger: log · Applies event/request logging.
- Slack app → Config: init · Loads runtime and database settings.
- Message event → Save service: persist · Stores inbound Slack messages.
- Save service → Message repo: db write · Writes message records to PostgreSQL.
- Message repo → Messages: maps · Persists the message model.
- Save service → Awareness queue: enqueue · Marks messages for async processing.
- Awareness queue → Worker boot: start · Consumes jobs in the background.
- Worker boot → Awareness worker: run · Launches the enrichment worker.
- Awareness worker → Awareness: enrich · Classifies and scores messages.
- Awareness → Summary: summarize · Builds thread summaries.
- Awareness → Embeddings: prepare · Prepares content for vectorization.
- Embedding job → Context: build · Reconstructs thread context for batching.
- Embedding job → RAG: assemble · Feeds retrieval context into memory generation.
- RAG → Search: retrieve · Performs hybrid search over stored memory.
- Search → Membership: gate · Limits retrieval to accessible channels.
- Membership → Message repo: lookup · Reads membership-aware state from the database.
- RAG → Context: context · Builds prompt context for Gemini.
- /memory → Membership: authorize · Checks user channel access before answering.
- /memory → RAG: answer · Generates the /memory response.
- Context → Text utils: normalize · Uses shared text assembly helpers.