Skip to content

Architecture Overview

JickleJime is a multi-interface application built on .NET, Azure services, and PostgreSQL with pgvector.

System diagram

graph TB
    subgraph Clients
        Slack[Slack Bot]
        MCP[MCP Server]
        CLI[CLI - jime]
    end

    subgraph Core["Core Services"]
        RAG[RAG Chat Service]
        Hybrid[Hybrid Search]
        Ingest[Ingestion Pipeline]
    end

    subgraph External["Azure Services"]
        OpenAI[Azure OpenAI<br/>gpt-4o + embeddings]
        DocInt[Document Intelligence]
        Speech[Speech Services]
        Blob[Blob Storage]
    end

    DB[(PostgreSQL<br/>+ pgvector)]

    Slack --> RAG
    MCP --> RAG
    MCP --> Hybrid
    CLI --> RAG
    CLI --> Hybrid
    CLI --> Ingest

    RAG --> Hybrid
    RAG --> OpenAI
    Hybrid --> DB
    Hybrid --> OpenAI

    Ingest --> DocInt
    Ingest -.-> Blob
    Ingest --> OpenAI
    Ingest --> DB

    CLI -.-> Speech
    CLI -.-> Blob

Project structure

Project Type Purpose
JickleJime.Core Library Domain logic — RAG chat, hybrid search, vector store, conversations, document registry
JickleJime.Ingestion Library Document extraction, chunking, embedding pipeline
JickleJime.Cli Application Command-line interface for DMs
JickleJime.Mcp Application MCP server for AI agent access (stdio + HTTP)
JickleJime.SlackBot Application Slack Socket Mode bot for player questions
JickleJime.Agent Library Azure AI Foundry agent orchestration
JickleJime.Transcription Library Audio transcription from Google Drive via Azure Speech

Data flow

Ingestion

Documents flow through: Extract → Chunk → Register → Archive → Interpret → Embed → Store

  • Extraction uses Azure AI Document Intelligence to parse PDFs into structural elements
  • Chunking respects document structure (sections, pages) with configurable overlap
  • Source files are archived to Azure Blob Storage for durable backup (when configured)
  • Each ingestion creates a new interpretation version, preserving previous processing runs
  • Embeddings are generated in batches with retry logic for rate limits
  • Re-ingesting a file creates a new interpretation — previous versions are preserved

Queries flow through: Embed → Three-way search → RRF merge → Top-K results

  • The query embedding is compared against stored vectors (cosine similarity)
  • Full-text and trigram searches run in parallel
  • Reciprocal Rank Fusion merges all three result sets
  • See How Search Works for details

Chat (RAG)

Questions flow through: Search → Build prompt → LLM → Answer with citations

  • Top-K search results are included as context in the system prompt
  • The LLM generates an answer citing specific sources
  • Conversation history is maintained for multi-turn interactions

External services

Service Purpose
Azure OpenAI Chat completion (gpt-4o) and embeddings (text-embedding-3-small)
Azure AI Document Intelligence PDF extraction using the prebuilt-layout model
Azure Speech Services Audio transcription with speaker diarization
Azure Blob Storage Source document archival (default jime-documents) and audio staging for transcription (default session-audio), both configurable
PostgreSQL 17 + pgvector Vector store, document registry, conversations
Slack API Socket Mode for real-time bot events

Database

PostgreSQL with the pgvector extension stores all persistent data:

  • chunks — Embedded text passages with vector embeddings, page ranges, and section headings
  • documents — Document registry with categories, scopes, descriptions, and source blob URI
  • document_interpretations — Versioned full-text representations of documents
  • conversations / conversation_messages — Chat history for multi-turn interactions

Indexes

  • HNSW on chunk embeddings for fast approximate nearest neighbor search
  • GIN on tsvector columns for full-text keyword search
  • GIN with pg_trgm on content for trigram fuzzy matching