# groupultra/telegram-search architecture

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

- Interactive diagram: https://gitdiagram.com/groupultra/telegram-search
- Repository: https://github.com/groupultra/telegram-search

## Overview

##### Project Type and Purpose
- This is a full-stack, mono-repo application for “Telegram Search,” a powerful Telegram chat record search tool leveraging semantic vector search (OpenAI embeddings) and a web/Electron UI.
- Key purpose: ingest Telegram chat history, store it in a database, index it for vector/semantic search, and expose search interfaces via frontend (browser) or desktop (Electron) clients.

##### File Structure Analysis
- Top-level directories:
- apps/ – contains frontend clients:
– electron/ – desktop app (Node/Electron + Vue)
– frontend/ – web app (Vue + Vite)
– server/ – backend service (Node + TypeScript + Drizzle ORM + WebSocket events)
- packages/ – shared libraries:
– common/ – generic helpers and composables (config, paths, flags, logger)
– core/ – business logic: context, models, services, event-handlers, message resolvers
- config/, docker-compose.yml – environment and deployment
- drizzle/, sql/ – database migrations and initial SQL scripts
- assets/ – dictionary files for vectorization
- CI/CD and build configs:
- .github/workflows, bump.config.ts, various tsconfig.json, build.config.ts
- Scripts and tooling:
- scripts/db.ts, drizzle.config.ts, uno.config.ts

##### README Insights
- Describes usage: clone → install → configure → Dockerize DB → migrate → start server & frontend
- Key components mentioned: backend service, frontend UI, database container
- Underlying tech: OpenAI semantic vector, Docker, pnpm, Vue, Electron, TypeScript

a. Main Components
1) Clients:
– Web Frontend (Vue + Vite)
– Electron Desktop App (Node + Electron + Vue)
2) Backend Service:
– HTTP/REST + WebSocket API (apps/server)
– Core Business Logic (packages/core)
– Common Utilities (packages/common)
3) Data Storage:
– Relational Database (PostgreSQL via Docker Compose)
– Vector Storage / Embeddings (in-DB or external)
4) External Services:
– OpenAI API (for semantic embeddings)
– Telegram API (ingest chat history)
5) CI/CD & Dev Tools
– pnpm workspace, Drizzle migrations, GitHub Actions

b. Relationships & Interactions
– Clients ↔ Backend:
- Web/Electron use HTTP REST for configuration, search queries
- Use WebSocket for real-time events (new messages, sync progress)
– Backend ↔ Database:
- Drizzle ORM runs migrations & models map to chat/message tables
- Stores raw messages, computed embeddings, metadata
– Backend ↔ OpenAI:
- On ingest or indexing, backend calls OpenAI embeddings API
– Backend ↔ Telegram API:
- Sync process (takeout) fetches chat history
– Shared Code:
- Both server and clients import from packages/common and packages/core
– CI/CD:
- GitHub Actions run tests, lints, builds

c. Architectural Patterns & Principles
– Mono-repo with PNPM workspaces for shared code
– Layered architecture:
- Presentation (apps/electron, apps/frontend)
- Application/Service layer (apps/server + packages/core services)
- Data layer (Drizzle ORM + database)
– Event-driven handling: WebSocket events, internal event-handlers for domain operations
– MVC-like separation in frontend (components, composables, stores)
– Configuration-as-code (YAML, environment files)

d. Key Technologies & Frameworks
– Frontend: Vue 3, Vite, UnoCSS
– Desktop: Electron, Electron Builder, Vue
– Backend: Node.js, TypeScript, Drizzle ORM, WebSocket
– Database: PostgreSQL (Docker), SQL migrations
– Vector/AI: OpenAI embeddings API
– Build/Workspace: pnpm, ts-configs, GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Web["Web Frontend (Vue + Vite)"]:::frontend
        Electron["Electron Desktop App"]:::frontend
        WebEventHandlers["Client-Side Event Handlers (Web)"]:::shared
        ElectronEventHandlers["Client-Side Event Handlers (Electron)"]:::shared
    end

    %% Backend Layer
    subgraph "Backend Service" 
        direction TB
        API["HTTP/REST API"]:::backend
        WS["WebSocket Handler"]:::backend
        subgraph "Server Core"
            direction TB
            Common["Common Utilities"]:::shared
            Core["Core Business Logic"]:::shared
            subgraph "Core Modules"
                direction TB
                Services["Services"]:::shared
                EventHandlers["Event Handlers"]:::shared
                MessageResolvers["Message Resolvers"]:::shared
                Models["Data Models & Schema"]:::shared
            end
        end
    end

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        DB["PostgreSQL Database"]:::datastore
        Migrations["Database Migrations (Drizzle)"]:::datastore
        InitSQL["Initial SQL Scripts"]:::datastore
        DockerCompose["Docker Compose"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        TelegramAPI["Telegram API"]:::external
        OpenAI["OpenAI Embeddings API"]:::external
    end

    %% CI/CD & Tools
    subgraph "CI/CD & Dev Tools"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        DBScript["Database CLI Script"]:::ci
        ConfigExample["App Configuration"]:::ci
    end

    %% Relationships
    Web -->|HTTP| API
    Electron -->|HTTP| API
    Web -->|WS| WS
    Electron -->|WS| WS
    Web --> WebEventHandlers
    Electron --> ElectronEventHandlers

    API -->|imports| Common
    API -->|imports| Core
    WS -->|imports| Common
    WS -->|imports| Core

    Core --> Services
    Core --> EventHandlers
    Core --> MessageResolvers
    Core --> Models

    WS --> Services
    API --> Services

    Services -->|reads/writes| DB
    EventHandlers -->|migrates| Migrations
    Migrations -->|runs| DB
    InitSQL -->|bootstrap| DB
    DockerCompose -->|hosts| DB

    Services -->|calls| OpenAI
    EventHandlers -->|calls| TelegramAPI

    GitHubActions -->|builds| Web
    GitHubActions -->|builds| Electron
    GitHubActions -->|builds| API
    GitHubActions -->|runs| DBScript
    GitHubActions -->|deploys| DockerCompose
    ConfigExample -->|configures| API

    %% Click Events
    click Electron "https://github.com/groupultra/telegram-search/tree/main/apps/electron"
    click Web "https://github.com/groupultra/telegram-search/tree/main/apps/frontend"
    click API "https://github.com/groupultra/telegram-search/blob/main/apps/server/src/app.ts"
    click API "https://github.com/groupultra/telegram-search/blob/main/apps/server/src/index.ts"
    click WS "https://github.com/groupultra/telegram-search/blob/main/apps/server/src/ws-event.ts"
    click Services "https://github.com/groupultra/telegram-search/tree/main/packages/core/src/services"
    click EventHandlers "https://github.com/groupultra/telegram-search/tree/main/packages/core/src/event-handlers"
    click MessageResolvers "https://github.com/groupultra/telegram-search/tree/main/packages/core/src/message-resolvers"
    click Models "https://github.com/groupultra/telegram-search/tree/main/packages/core/src/models"
    click Models "https://github.com/groupultra/telegram-search/blob/main/packages/core/src/db/schema.ts"
    click Common "https://github.com/groupultra/telegram-search/tree/main/packages/common/src"
    click Migrations "https://github.com/groupultra/telegram-search/tree/main/drizzle/"
    click Migrations "https://github.com/groupultra/telegram-search/blob/main/drizzle.config.ts"
    click InitSQL "https://github.com/groupultra/telegram-search/blob/main/sql/init.sql"
    click DockerCompose "https://github.com/groupultra/telegram-search/blob/main/docker-compose.yml"
    click TelegramAPI "https://github.com/groupultra/telegram-search/blob/main/packages/core/src/services/takeout.ts"
    click TelegramAPI "https://github.com/groupultra/telegram-search/blob/main/packages/core/src/event-handlers/takeout.ts"
    click MessageResolvers "https://github.com/groupultra/telegram-search/blob/main/packages/core/src/message-resolvers/embedding-resolver.ts"
    click WS "https://github.com/groupultra/telegram-search/blob/main/apps/electron/src/main/ws-event.ts"
    click WebEventHandlers "https://github.com/groupultra/telegram-search/tree/main/apps/frontend/src/event-handlers"
    click ElectronEventHandlers "https://github.com/groupultra/telegram-search/tree/main/apps/electron/src/renderer/src/event-handlers"
    click ConfigExample "https://github.com/groupultra/telegram-search/blob/main/config/config.example.yaml"
    click DBScript "https://github.com/groupultra/telegram-search/blob/main/scripts/db.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#000
    classDef backend fill:#D5F5E3,stroke:#000
    classDef datastore fill:#FDEBD0,stroke:#000
    classDef external fill:#E8DAEF,stroke:#000
    classDef shared fill:#D5D8DC,stroke:#000
    classDef ci fill:#E5E7E9,stroke:#000
```
