# zhmpng/notes-ai-bot architecture

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

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

## Overview

##### Project type and purpose
- Type: A single-service (monolith) AI chatbot written in Go.
- Purpose: Accept user messages (text or audio), convert speech to text, enrich or summarize via an LLM, store notes, and reply via a messaging API (e.g., Telegram).

##### File structure
Top-level packages:
- bot/ – all Telegram-bot or chat-interface related code (handlers, commands, keyboards, messaging utilities).
- llm/ – wrapper around the large language model API.
- speechkit/ – client for speech-to-text processing (e.g., Yandex SpeechKit).
- storage/ – persistence layer (e.g., database or key-value store).
- models/ – shared data structures across modules.
- main.go – application entry point: wires modules, loads config, starts the bot loop.
Supporting files: go.mod/go.sum, .gitignore, LICENSE.

##### README for additional insights
- Only project name present.
- No explicit architecture section—derive structure from code.

1) User Interface (Messaging API)
– External: Telegram (or alternative chat platform).
2) Bot Core
– Internal modules:
- bot package: CommandHandler, KeyboardHandler, MessageDispatcher
- audio_processing.go: orchestrates audio receipt & initial decoding
- note_processing.go: applies business logic to text notes
3) SpeechKit Client
– Calls external Speech-to-Text service
4) LLM Client
– Calls external LLM API (e.g., OpenAI GPT)
5) Storage Layer
– Persists notes, user sessions, settings
6) Shared Models
– DTOs, request/response structs

b. Relationships and data flow
1) User → Messaging API → Bot Core
2) Bot Core detects audio:
- sends binary to SpeechKit → receives transcript
3) Bot Core (note_processing) → sends text prompt to LLM → receives enriched/summarized text
4) Bot Core → Storage Layer → saves or retrieves notes
5) Bot Core → Messaging API → replies to User

c. Architectural patterns / design principles
- Package separation by concern (bot, llm, speechkit, storage)
- Dependency injection in main.go (wiring clients to handlers)
- Single responsibility: each package wraps one external API or function
- Monolithic service exposing a long-polling or webhook loop

d. Key technologies/frameworks
- Go standard library + popular HTTP client
- Telegram Bot API client (wrapped in bot/utils.go)
- SpeechKit API (speechkit/speechkit.go)
- LLM API (llm/llm.go)
- Storage (likely using database/sql in storage/storage.go)

##### Important details to capture
- The entry point (main.go) wiring all components.
- Separation of concerns by package.
- Asynchronous or blocking call patterns (LLM and SpeechKit calls).
- Data models flowing across boundaries (models/models.go).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Entities
    User((User)):::external
    Telegram["Telegram API"]:::external
    SpeechKitService["SpeechKit Service"]:::external
    LLMService["LLM Service"]:::external
    StorageDB[(Database)]:::datastore

    %% Monolith Service
    subgraph "Monolith: notes-ai-bot"
        direction TB
        main["main.go"]:::internal
        subgraph "Internal Modules"
            direction TB
            CH["CommandHandler"]:::internal
            KH["KeyboardHandler"]:::internal
            MD["MessageDispatcher"]:::internal
            AP["AudioProcessing"]:::internal
            NP["NoteProcessing"]:::internal
            UT["Utils"]:::internal
            MS["Messages"]:::internal
            Init["Bot Initialization (bot.go)"]:::internal
        end
    end

    %% Data Flow
    User --> Telegram
    Telegram --> MD
    MD --> CH
    MD --> KH
    MD --> AP
    AP --> SpeechKitService
    SpeechKitService --> AP
    AP --> NP
    NP --> LLMService
    LLMService --> NP
    NP --> StorageDB
    StorageDB --> NP
    NP --> MD
    MD --> Telegram
    Telegram --> User

    %% Wiring
    main --> Init
    Init --> CH
    Init --> KH
    Init --> MD
    Init --> AP
    Init --> NP
    Init --> UT
    Init --> MS

    %% Click Events
    click CH "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/command_handlers.go"
    click KH "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/keyboard_handlers.go"
    click MD "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/handlers.go"
    click UT "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/utils.go"
    click MS "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/messages.go"
    click AP "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/audio_processing.go"
    click NP "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/note_processing.go"
    click Init "https://github.com/zhmpng/notes-ai-bot/blob/trunk/bot/bot.go"
    click main "https://github.com/zhmpng/notes-ai-bot/blob/trunk/main.go"
    click SpeechKitService "https://github.com/zhmpng/notes-ai-bot/blob/trunk/speechkit/speechkit.go"
    click LLMService "https://github.com/zhmpng/notes-ai-bot/blob/trunk/llm/llm.go"
    click StorageDB "https://github.com/zhmpng/notes-ai-bot/blob/trunk/storage/storage.go"
    click Models "https://github.com/zhmpng/notes-ai-bot/blob/trunk/models/models.go"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef datastore fill:#FFD700,stroke:#000,stroke-width:1px;
```
