How mralexandrovorganization/notes-bot works
Purpose and Entry Points
A personal, single-user Telegram bot for Obsidian daily notes, task management, ratings, reminders, natural-language reminder creation, and voice transcription. Go service entry points are cmd/telegram/main.go, cmd/core/main.go, cmd/notifications/main.go, and cmd/search/main.go. Service orchestration is defined by docker-compose.yml and docker-compose.base.yml.
Telegram Frontend and Interaction Control
The Telegram process is the user-facing coordinator: it authorizes ROOT_ID, routes commands/messages/callbacks, maintains multi-step reminder flows, and invokes downstream services. frontends/telegram/tghandlers/app.go owns injected dependencies; frontends/telegram/tghandlers/messages.go routes state-dependent text input; frontends/telegram/tghandlers/voice.go handles voice/video transcription requests. Inline UI is generated separately in frontends/telegram/tgkeyboards/.
Stateful Conversation Boundary
Per-user UI state and reminder drafts are isolated from business services through a Redis-backed state manager. This supports callback-driven workflows and natural-language reminder confirmation without embedding session state in Telegram handlers. Key paths: frontends/telegram/tgstates/manager.go, frontends/telegram/tgstates/context.go, frontends/telegram/tgstates/draft.go.
Notes Core Service
The Core gRPC service is the filesystem boundary for the Obsidian vault: it reads/writes daily Markdown notes, manipulates task checkboxes, updates ratings, and exposes calendar/note operations. Its server delegates to storage abstractions in core/stores.go; feature-level note transformations are in core/features/tasks.go and core/features/rating.go. The RPC contract is proto/notes/notes.proto. The service operates against the mounted NOTES_DIR, rather than a database.
Reminder Lifecycle and Event Delivery
The Notifications gRPC service persists reminders in PostgreSQL, computes recurring schedules, and publishes due events to Kafka. notifications/server.go exposes reminder RPCs; notifications/db.go is the PostgreSQL persistence boundary; notifications/scheduler.go finds and emits due reminders. The Telegram consumer in frontends/telegram/bot/kafka_consumer.go receives the reminder topic and dispatches delivery through frontends/telegram/tghandlers/kafka.go. Kafka headers preserve trace context via internal/kafkacarrier/carrier.go.
AI and Voice Integrations
Telegram-side clients isolate outbound protocols from handlers: gRPC clients for Core, Notifications, and Whisper, plus HTTP access to Ollama for structured natural-language reminder parsing. Primary interfaces and implementations are frontends/telegram/clients/interfaces.go, frontends/telegram/clients/llm.go, and frontends/telegram/clients/whisper.go. Ollama and faster-whisper are external/containerized runtime services; their protocol definitions include proto/whisper/whisper.proto.
Search and Shared Platform Concerns
A separate Search Go service provides an indexing/search pipeline around chunking, embeddings, storage, and scheduled indexing: search/server.go, search/indexer.go, search/embedder.go, with contract proto/search/search.proto. Cross-cutting gRPC setup, telemetry, and logging are centralized in internal/grpcutil/server.go, internal/telemetry/tracer.go, and internal/applog/applog.go. Runtime infrastructure includes PostgreSQL, Redis, Kafka, Ollama, Jaeger, Prometheus, and Grafana; scrape targets are configured in monitoring/prometheus-targets.yml.
Main entry points: interfaces.go Service and AI clients · app.go Interaction handlers · core/main.go Core gRPC service · notifications/main.go Notifications gRPC
Components 17
Telegram frontend
- Telegram bot · Authorizes users and coordinates commands, callbacks, and messages.
cmd/telegram/main.go - Interaction handlers · Routes stateful text, callbacks, and voice requests.
frontends/telegram/tghandlers/app.go - Inline UI
- Conversation state · Stores per-user UI state and reminder drafts.
frontends/telegram/tgstates/manager.go - Service and AI clients · Isolates gRPC and HTTP integrations from handlers.
frontends/telegram/clients/interfaces.go
Notes core
- Core gRPC service · Filesystem boundary for vault notes, tasks, ratings, and calendar operations.
cmd/core/main.go - Note features
core/features/tasks.go - Obsidian vault · NOTES_DIR is the durable notes store.
core/stores.go
Reminders
- Notifications gRPC · Provides reminder creation and lifecycle RPCs.
cmd/notifications/main.go - Reminder scheduler · Computes recurring schedules and emits due reminders.
notifications/scheduler.go - Reminder store
notifications/db.go - Kafka reminders topic · Carries due reminder events with trace headers.
frontends/telegram/bot/kafka_consumer.go
Search
- Search gRPC service · Serves search and scheduled indexing.
cmd/search/main.go - Indexing pipeline · Chunks notes, creates embeddings, and stores search data.
search/indexer.go
Runtime platform
- Ollama · Parses natural-language reminder requests into structured data.
frontends/telegram/clients/llm.go - faster-whisper
frontends/telegram/clients/whisper.go - Telemetry and monitoring · gRPC telemetry flows to Jaeger; Prometheus and Grafana monitor services.
internal/telemetry/tracer.go
Connections 21
- Telegram bot → Interaction handlers: dispatches updates
- Interaction handlers → Inline UI: renders UI
- Interaction handlers → Conversation state: reads and updates flow state
- Conversation state → Reminder store: uses Redis separately
- Interaction handlers → Service and AI clients: invokes
- Service and AI clients → Core gRPC service: notes RPCs
- Service and AI clients → Notifications gRPC: reminder RPCs
- Service and AI clients → Ollama: structured NL parsing
- Service and AI clients → faster-whisper: voice transcription
- Core gRPC service → Note features: applies transformations
- Core gRPC service → Obsidian vault: reads and writes
- Notifications gRPC → Reminder store: persists reminders
- Notifications gRPC → Reminder scheduler: schedules reminders
- Reminder scheduler → Kafka reminders topic: publishes due events
- Kafka reminders topic → Interaction handlers: delivers reminders
- Search gRPC service → Indexing pipeline: runs indexing
- Indexing pipeline → Obsidian vault: indexes notes
- Telegram bot → Telemetry and monitoring: traces and metrics
- Core gRPC service → Telemetry and monitoring: traces and metrics
- Notifications gRPC → Telemetry and monitoring: traces and metrics
- Search gRPC service → Telemetry and monitoring: traces and metrics