# adnanquazi/zap architecture

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

- Interactive diagram: https://gitdiagram.com/adnanquazi/zap
- Repository: https://github.com/adnanquazi/zap

## Overview

##### Project type and purpose
- This is a full-stack, microservices-style application built to integrate with Slack.
- Purpose: Provide a “knowledge assistant” (Zap) in Slack channels that answers questions using channel history, uploaded documents, and an embedding-backed LLM.

##### File structure
- Top‐level monorepo managed by Turbo/pnpm workspaces.
- apps/client: Next.js app hosting the marketing site & Slack install/oauth pages.
- apps/server: Node.js app handling Slack OAuth, event subscriptions, slash commands, business logic, rate‐limiting, context pipelines.
- services/embedding-service: Python FastAPI (or similar) microservice that computes embeddings.
- supabase: Database schema & migrations for storing messages, user settings.
- Redis used for rate limits, context cooldown, concurrency limiting.

##### README for additional insights
- Built with Next.js, Node.js, Supabase, Redis, Python embedding service, Modal (for serverless?).
- Key flows: OAuth, installing Slack app, event webhook processing, slash‐command handlers, privacy controls, embedding pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    SlackAPI["Slack API"]:::external
    LLMAPI["LLM API (Gemini)"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        MarketingUI["Next.js Marketing & Install UI"]:::frontend
        OAuthUI["OAuth Page"]:::frontend
        OAuthCallbackUI["OAuth Callback Page"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        SlackHandler["Slack Handler Service"]:::backend

        subgraph "Routes & Scripts"
            direction TB
            OAuthRoute["OAuth Route"]:::backend
            GenManifest["Generate Manifest Script"]:::backend
            ManifestTemplate["Slack App Manifest Template"]:::backend
        end

        subgraph "Handlers"
            direction TB
            SlashCommands["Slash Command Handlers"]:::backend
            EventHandlers["Event Handlers"]:::backend
            subgraph "/zap-ask Pipeline"
                direction TB
                AskHandler["AskCommandHandler"]:::backend
                ConcurrencyLimiter["Concurrency Limiter"]:::backend
                FileProcessor["File Processor"]:::backend
                QueryProcessor["Query Processor"]:::backend
                ResponseGenerator["Response Generator"]:::backend
                MessageSync["Slack Message Synchronizer"]:::backend
            end
        end

        subgraph "Services"
            direction TB
            EmbeddingConnector["Embedding Service Connector"]:::backend
            FetchMessages["Message Fetching Services"]:::backend
            BatchStorage["Batch Storage Service"]:::backend
            InstallService["Installation Services"]:::backend
        end

        subgraph "Pipelines & Middleware"
            direction TB
            HybridSearch["Hybrid Search Pipeline"]:::backend
            RateLimit["Rate-Limiting & Cooldown Helpers"]:::backend
            Middleware["Concurrency & Scoped DB Middleware"]:::backend
        end

        subgraph "Configs & Prompts"
            direction TB
            RedisConfig["Redis Config"]:::backend
            SlackConfig["Slack SDK Config"]:::backend
            SupabaseConfig["Supabase Config"]:::backend
            PlanningPrompt["Planning Prompt"]:::backend
            ResponsePrompt["Response Generation Prompt"]:::backend
        end
    end

    %% Services Layer
    subgraph "Embedding Service"
        direction TB
        EmbService["Python FastAPI Embedding Service"]:::service
        EmbCode["embedding_service.py"]:::service
        EmbReqs["requirements.txt"]:::service
        EmbPkg["package.json"]:::service
    end

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        SupabaseDB["Supabase (PostgreSQL + Storage)"]:::datastore
        Migrations["DB Migrations"]:::datastore
        RedisStore["Redis (Rate Limits, Cooldowns)"]:::datastore
    end

    %% Relations
    MarketingUI -->|"User clicks Add to Slack"| SlackAPI
    OAuthUI -->|"/slack/oauth"| SlackAPI
    SlackAPI -->|"oauth_callback"| OAuthRoute
    SlackAPI -->|"message_event /slash_command"| SlackHandler
    OAuthRoute -->|writes| SupabaseDB
    SlackHandler -->|reads/writes| SupabaseDB
    SlackHandler -->|reads/writes| RedisStore
    SlackHandler -->|"fetch context"| HybridSearch
    HybridSearch -->|calls| SupabaseDB
    HybridSearch -->|calls| RedisStore
    SlackHandler -->|embed call| EmbeddingConnector
    EmbeddingConnector -->|"HTTP request"| EmbService
    EmbService -->|"embed vectors"| LLMAPI
    EmbService -->|"response"| SlackHandler
    SlackHandler -->|"post message"| SlackAPI

    %% Developer workflow
    SlackHandler --> GenManifest
    GenManifest --> ManifestTemplate

    %% Click Events
    click MarketingUI "https://github.com/adnanquazi/zap/tree/main/apps/client"
    click OAuthUI "https://github.com/adnanquazi/zap/tree/main/apps/client/app/slack/oauth"
    click OAuthCallbackUI "https://github.com/adnanquazi/zap/tree/main/apps/client/app/slack/oauth/callback"
    click SlackHandler "https://github.com/adnanquazi/zap/tree/main/apps/server"
    click OAuthRoute "https://github.com/adnanquazi/zap/blob/main/apps/server/src/routes/oauth.js"
    click GenManifest "https://github.com/adnanquazi/zap/blob/main/apps/server/scripts/generate-manifest.js"
    click ManifestTemplate "https://github.com/adnanquazi/zap/blob/main/apps/server/slack/manifest.template.json"
    click SlashCommands "https://github.com/adnanquazi/zap/tree/main/apps/server/src/handlers/commands"
    click AskHandler "https://github.com/adnanquazi/zap/blob/main/apps/server/src/handlers/commands/zap-ask/AskCommandHandler.js"
    click ConcurrencyLimiter "https://github.com/adnanquazi/zap/blob/main/apps/server/src/handlers/commands/zap-ask/Concurrency-Limiter.js"
    click FileProcessor "https://github.com/adnanquazi/zap/blob/main/apps/server/src/handlers/commands/zap-ask/FileProcessor.js"
    click QueryProcessor "https://github.com/adnanquazi/zap/blob/main/apps/server/src/handlers/commands/zap-ask/QueryProcessor.js"
    click ResponseGenerator "https://github.com/adnanquazi/zap/blob/main/apps/server/src/handlers/commands/zap-ask/ResponseGenerator.js"
    click MessageSync "https://github.com/adnanquazi/zap/blob/main/apps/server/src/handlers/commands/zap-ask/SlackMessageSynchronizer.js"
    click EventHandlers "https://github.com/adnanquazi/zap/tree/main/apps/server/src/handlers/events"
    click RateLimit "https://github.com/adnanquazi/zap/blob/main/apps/server/src/helpers/ask-rate-limit.js"
    click Middleware "https://github.com/adnanquazi/zap/tree/main/apps/server/src/middlewares"
    click HybridSearch "https://github.com/adnanquazi/zap/blob/main/apps/server/src/pipelines/hybrid-search-pipeline.js"
    click EmbeddingConnector "https://github.com/adnanquazi/zap/blob/main/apps/server/src/services/xenovo-embedding-service.js"
    click FetchMessages "https://github.com/adnanquazi/zap/blob/main/apps/server/src/services/fetch-channel-messages.js"
    click BatchStorage "https://github.com/adnanquazi/zap/blob/main/apps/server/src/services/batch-store-messages.js"
    click InstallService "https://github.com/adnanquazi/zap/blob/main/apps/server/src/services/installation-services.js"
    click RedisConfig "https://github.com/adnanquazi/zap/blob/main/apps/server/src/config/redis.js"
    click SupabaseConfig "https://github.com/adnanquazi/zap/blob/main/apps/server/src/config/supabase.js"
    click PlanningPrompt "https://github.com/adnanquazi/zap/blob/main/apps/server/src/prompts/planning-prompt.js"
    click ResponsePrompt "https://github.com/adnanquazi/zap/blob/main/apps/server/src/prompts/response-generation-prompt.js"
    click EmbCode "https://github.com/adnanquazi/zap/blob/main/services/embedding-service/embedding_service.py"
    click EmbReqs "https://github.com/adnanquazi/zap/blob/main/services/embedding-service/requirements.txt"
    click EmbPkg "https://github.com/adnanquazi/zap/blob/main/services/embedding-service/package.json"
    click Migrations "https://github.com/adnanquazi/zap/blob/main/supabase/migrations/20250430195733_inital_prod_schema.sql"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef backend fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef service fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef datastore fill:#B2DFDB,stroke:#004D40,color:#004D40
    classDef external fill:#E0E0E0,stroke:#424242,color:#424242
```
