How groupultra/telegram-search works
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