# mralexandrovorganization/notes-bot architecture

> Architecture diagram of the GitHub repository mralexandrovorganization/notes-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mralexandrovorganization/notes-bot
- Repository: https://github.com/mralexandrovorganization/notes-bot

## Overview

#### 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: [`frontends/telegram/clients/interfaces.go`](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/clients/interfaces.go) (Service and AI clients), [`frontends/telegram/tghandlers/app.go`](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/tghandlers/app.go) (Interaction handlers), [`cmd/core/main.go`](https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/core/main.go) (Core gRPC service), [`cmd/notifications/main.go`](https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/notifications/main.go) (Notifications gRPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram frontend"]
  node_telegram["Telegram bot<br/>Go entry point<br/>[main.go]"]
  node_handlers["Interaction handlers<br/>handler layer<br/>[app.go]"]
  node_keyboards["Inline UI<br/>Telegram keyboards"]
  node_state["Conversation state<br/>Redis state manager<br/>[manager.go]"]
  node_clients["Service and AI clients<br/>client layer<br/>[interfaces.go]"]
end

subgraph group_notes["Notes core"]
  node_core["Core gRPC service<br/>Go service<br/>[main.go]"]
  node_note_features["Note features<br/>task and rating logic<br/>[tasks.go]"]
  node_vault["Obsidian vault<br/>mounted Markdown files<br/>[stores.go]"]
end

subgraph group_reminders["Reminders"]
  node_notifications["Notifications gRPC<br/>Go service<br/>[main.go]"]
  node_scheduler["Reminder scheduler<br/>due-event publisher<br/>[scheduler.go]"]
  node_reminder_db[("Reminder store<br/>PostgreSQL persistence<br/>[db.go]")]
  node_kafka["Kafka reminders topic<br/>event bus<br/>[kafka_consumer.go]"]
end

subgraph group_search["Search"]
  node_search_service["Search gRPC service<br/>Go service<br/>[main.go]"]
  node_indexer["Indexing pipeline<br/>chunk and embed pipeline<br/>[indexer.go]"]
end

subgraph group_platform["Runtime platform"]
  node_ollama{{"Ollama<br/>LLM runtime<br/>[llm.go]"}}
  node_whisper{{"faster-whisper<br/>transcription runtime<br/>[whisper.go]"}}
  node_observability["Telemetry and monitoring<br/>cross-cutting platform<br/>[tracer.go]"]
end

node_telegram -->|"dispatches updates"| node_handlers
node_handlers -->|"renders UI"| node_keyboards
node_handlers -->|"reads and updates flow state"| node_state
node_state -.->|"uses Redis separately"| node_reminder_db
node_handlers -->|"invokes"| node_clients
node_clients -->|"notes RPCs"| node_core
node_clients -->|"reminder RPCs"| node_notifications
node_clients -->|"structured NL parsing"| node_ollama
node_clients -->|"voice transcription"| node_whisper
node_core -->|"applies transformations"| node_note_features
node_core -->|"reads and writes"| node_vault
node_notifications -->|"persists reminders"| node_reminder_db
node_notifications -->|"schedules reminders"| node_scheduler
node_scheduler -->|"publishes due events"| node_kafka
node_kafka -->|"delivers reminders"| node_handlers
node_search_service -->|"runs indexing"| node_indexer
node_indexer -->|"indexes notes"| node_vault
node_telegram -.->|"traces and metrics"| node_observability
node_core -.->|"traces and metrics"| node_observability
node_notifications -.->|"traces and metrics"| node_observability
node_search_service -.->|"traces and metrics"| node_observability

click node_telegram "https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/telegram/main.go"
click node_handlers "https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/tghandlers/app.go"
click node_state "https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/tgstates/manager.go"
click node_clients "https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/clients/interfaces.go"
click node_core "https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/core/main.go"
click node_note_features "https://github.com/mralexandrovorganization/notes-bot/blob/main/core/features/tasks.go"
click node_vault "https://github.com/mralexandrovorganization/notes-bot/blob/main/core/stores.go"
click node_notifications "https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/notifications/main.go"
click node_scheduler "https://github.com/mralexandrovorganization/notes-bot/blob/main/notifications/scheduler.go"
click node_reminder_db "https://github.com/mralexandrovorganization/notes-bot/blob/main/notifications/db.go"
click node_kafka "https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/bot/kafka_consumer.go"
click node_ollama "https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/clients/llm.go"
click node_whisper "https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/clients/whisper.go"
click node_search_service "https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/search/main.go"
click node_indexer "https://github.com/mralexandrovorganization/notes-bot/blob/main/search/indexer.go"
click node_observability "https://github.com/mralexandrovorganization/notes-bot/blob/main/internal/telemetry/tracer.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_telegram,node_handlers,node_keyboards,node_state,node_clients toneBlue
class node_core,node_note_features,node_vault toneAmber
class node_notifications,node_scheduler,node_reminder_db,node_kafka toneMint
class node_search_service,node_indexer toneRose
class node_ollama,node_whisper,node_observability toneIndigo
```

## Components

### Telegram frontend

- [Telegram bot](https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/telegram/main.go): Go entry point · Authorizes users and coordinates commands, callbacks, and messages. · `cmd/telegram/main.go`
- [Interaction handlers](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/tghandlers/app.go): handler layer · Routes stateful text, callbacks, and voice requests. · `frontends/telegram/tghandlers/app.go`
- **Inline UI**: Telegram keyboards
- [Conversation state](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/tgstates/manager.go): Redis state manager · Stores per-user UI state and reminder drafts. · `frontends/telegram/tgstates/manager.go`
- [Service and AI clients](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/clients/interfaces.go): client layer · Isolates gRPC and HTTP integrations from handlers. · `frontends/telegram/clients/interfaces.go`

### Notes core

- [Core gRPC service](https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/core/main.go): Go service · Filesystem boundary for vault notes, tasks, ratings, and calendar operations. · `cmd/core/main.go`
- [Note features](https://github.com/mralexandrovorganization/notes-bot/blob/main/core/features/tasks.go): task and rating logic · `core/features/tasks.go`
- [Obsidian vault](https://github.com/mralexandrovorganization/notes-bot/blob/main/core/stores.go): mounted Markdown files · NOTES_DIR is the durable notes store. · `core/stores.go`

### Reminders

- [Notifications gRPC](https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/notifications/main.go): Go service · Provides reminder creation and lifecycle RPCs. · `cmd/notifications/main.go`
- [Reminder scheduler](https://github.com/mralexandrovorganization/notes-bot/blob/main/notifications/scheduler.go): due-event publisher · Computes recurring schedules and emits due reminders. · `notifications/scheduler.go`
- [Reminder store](https://github.com/mralexandrovorganization/notes-bot/blob/main/notifications/db.go): PostgreSQL persistence · `notifications/db.go`
- [Kafka reminders topic](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/bot/kafka_consumer.go): event bus · Carries due reminder events with trace headers. · `frontends/telegram/bot/kafka_consumer.go`

### Search

- [Search gRPC service](https://github.com/mralexandrovorganization/notes-bot/blob/main/cmd/search/main.go): Go service · Serves search and scheduled indexing. · `cmd/search/main.go`
- [Indexing pipeline](https://github.com/mralexandrovorganization/notes-bot/blob/main/search/indexer.go): chunk and embed pipeline · Chunks notes, creates embeddings, and stores search data. · `search/indexer.go`

### Runtime platform

- [Ollama](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/clients/llm.go): LLM runtime · Parses natural-language reminder requests into structured data. · `frontends/telegram/clients/llm.go`
- [faster-whisper](https://github.com/mralexandrovorganization/notes-bot/blob/main/frontends/telegram/clients/whisper.go): transcription runtime · `frontends/telegram/clients/whisper.go`
- [Telemetry and monitoring](https://github.com/mralexandrovorganization/notes-bot/blob/main/internal/telemetry/tracer.go): cross-cutting platform · gRPC telemetry flows to Jaeger; Prometheus and Grafana monitor services. · `internal/telemetry/tracer.go`

## Connections

- 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