# sid3612/vibe architecture

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

- Interactive diagram: https://gitdiagram.com/sid3612/vibe
- Repository: https://github.com/sid3612/vibe

## Overview

##### Project Type and Purpose
- This is a backend-only, monolithic Telegram bot (“Job Funnel Coach”) written in Python.
- Purpose: track job application funnels (active/passive), compute CVR metrics, store data locally (SQLite), send reminders, export CSVs, and serve an FAQ.

##### Main Components
a. Telegram Interface Layer
- main.py – Bot startup, polling or webhook setup
- keyboards.py – Inline keyboard definitions
- reflection_forms.py, reminder handlers, callback handlers
b. Business-Logic Layer
- cvr_analyzer.py / cvr_autoanalyzer.py – compute CVR metrics
- funnel_coach workflows (hypotheses_manager.py, metrics.py)
- reminders.py – scheduling and sending reminders
- faq.py – FAQ content
- export.py – CSV export functionality
c. Data-Access Layer
- db.py – SQLite wrapper, ORM or raw queries
- funnel_coach.db – local SQLite database
- validators.py – input validation before DB writes
d. Configuration & Environment
- config.py – reads BOT_TOKEN, can read `.env`
- pyproject.toml – dependency listing
e. Testing & Debugging
- test_*.py files – unit & integration tests
- simple_debug.py, debug_*.py – ad-hoc debugging scripts

##### Relationships & Data Flow
- Telegram User <–> Telegram Bot API (HTTPS)
- Bot API calls → main.py → dispatch to handlers (reflection_handlers.py, reminders.py, etc.)
- Handlers invoke Business Logic modules (cvr_analyzer, metrics)
- Business Logic reads/writes from/to Data Access Layer (db.py → SQLite)
- Export module reads DB, writes CSV to file system or sends it back via Telegram API
- Reminders module may rely on an internal scheduler or external cron → triggers Telegram API calls
- Tests exercise Business Logic and Data Access in isolation or end-to-end via a fake Telegram API

##### Architectural Patterns & Design Principles
- Layered architecture (Interface → Business Logic → Data Access)
- Single responsibility: each module has a clear domain (analyzer, export, reminders)
- Synchronous polling/webhook pattern for Telegram
- Local persistence (no external DB or microservices)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    User(("User")):::external
    TelegramAPI(["Telegram Bot API"]):::external

    %% Bot Server Container
    subgraph "Bot Server"
        direction TB

        %% Interface Layer
        subgraph "Interface Layer"
            direction TB
            Main["main.py"]:::interface
            Keyboards["keyboards.py"]:::interface
            ReflectionForms["reflection_forms.py"]:::interface
            ReflectionHandlers["reflection_handlers.py"]:::interface
        end

        %% Business Logic Layer
        subgraph "Business Logic Layer"
            direction TB
            CVRAnalyzer["cvr_analyzer.py"]:::logic
            CVRAutoAnalyzer["cvr_autoanalyzer.py"]:::logic
            HypothesesManager["hypotheses_manager.py"]:::logic
            Metrics["metrics.py"]:::logic
            RemindersBL["reminders.py"]:::logic
            FAQ["faq.py"]:::logic
            Export["export.py"]:::logic
        end

        %% Data Access Layer
        subgraph "Data Access Layer"
            direction TB
            DBWrapper["db.py"]:::data
            SQLiteDB[(funnel_coach.db)]:::data
            Validators["validators.py"]:::data
        end
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        direction TB
        Config["config.py"]:::config
        Pyproject["pyproject.toml"]:::config
    end

    %% Scheduler
    subgraph "Scheduler"
        Cron(["Cron / Scheduler"]):::external
    end

    %% Testing & Debugging
    subgraph "Tests & Debugging"
        direction TB
        Tests["test_*.py"]:::tests
        Tests2["tests.py"]:::tests
        SimpleDebug["simple_debug.py"]:::tests
        DebugReflection["debug_reflection_flow.py"]:::tests
        DebugTest["debug_test.py"]:::tests
    end

    %% Connections
    User -->|"Messages (JSON over HTTPS)"| TelegramAPI
    TelegramAPI -->|"Webhook/LongPolling"| Main

    %% Interface to Business Logic
    Main -->|"dispatch"| ReflectionHandlers
    Main -->|"dispatch"| RemindersBL
    Main -->|"dispatch"| FAQ
    ReflectionHandlers -->|"input validation"| Validators
    ReflectionHandlers -->|"invoke"| CVRAnalyzer
    ReflectionHandlers -->|"invoke"| Metrics

    %% Business Logic to Data Access
    CVRAnalyzer -->|"SQL queries"| DBWrapper
    CVRAutoAnalyzer -->|"SQL queries"| DBWrapper
    HypothesesManager -->|"SQL queries"| DBWrapper
    Metrics -->|"SQL queries"| DBWrapper
    RemindersBL -->|"SQL queries"| DBWrapper
    FAQ -->|"read only"| DBWrapper
    Export -->|"read only"| DBWrapper

    %% Data Access Storage
    DBWrapper -->|"stores data"| SQLiteDB
    Validators -->|"pre-write checks"| DBWrapper

    %% Export and Reminders back to Telegram
    Export -->|"CSV over API"| TelegramAPI
    RemindersBL -->|"send reminder"| TelegramAPI

    %% Scheduler triggers Reminders
    Cron -.->|"scheduled trigger"| RemindersBL

    %% Config feeds Main
    Config --> Main
    Pyproject --> Main

    %% Tests interactions
    Tests -->|"mock API"| Main
    Tests -->|"DB integration"| DBWrapper
    Tests2 --> Main
    SimpleDebug --> Main
    DebugReflection --> ReflectionHandlers
    DebugTest --> Tests

    %% Click Events
    click Main "https://github.com/sid3612/vibe/blob/main/main.py"
    click Keyboards "https://github.com/sid3612/vibe/blob/main/keyboards.py"
    click ReflectionForms "https://github.com/sid3612/vibe/blob/main/reflection_forms.py"
    click ReflectionHandlers "https://github.com/sid3612/vibe/blob/main/reflection_handlers.py"
    click CVRAnalyzer "https://github.com/sid3612/vibe/blob/main/cvr_analyzer.py"
    click CVRAutoAnalyzer "https://github.com/sid3612/vibe/blob/main/cvr_autoanalyzer.py"
    click HypothesesManager "https://github.com/sid3612/vibe/blob/main/hypotheses_manager.py"
    click Metrics "https://github.com/sid3612/vibe/blob/main/metrics.py"
    click RemindersBL "https://github.com/sid3612/vibe/blob/main/reminders.py"
    click FAQ "https://github.com/sid3612/vibe/blob/main/faq.py"
    click Export "https://github.com/sid3612/vibe/blob/main/export.py"
    click DBWrapper "https://github.com/sid3612/vibe/blob/main/db.py"
    click SQLiteDB "https://github.com/sid3612/vibe/blob/main/funnel_coach.db"
    click Validators "https://github.com/sid3612/vibe/blob/main/validators.py"
    click Config "https://github.com/sid3612/vibe/blob/main/config.py"
    click Pyproject "https://github.com/sid3612/vibe/blob/main/pyproject.toml"
    click Tests "https://github.com/sid3612/vibe/blob/main/test_*.py"
    click Tests2 "https://github.com/sid3612/vibe/blob/main/tests.py"
    click SimpleDebug "https://github.com/sid3612/vibe/blob/main/simple_debug.py"
    click DebugReflection "https://github.com/sid3612/vibe/blob/main/debug_reflection_flow.py"
    click DebugTest "https://github.com/sid3612/vibe/blob/main/debug_test.py"

    %% Styles
    classDef external fill:#cccccc,stroke:#333,stroke-width:1px
    classDef interface fill:#bbe1fa,stroke:#1f78b4,stroke-width:1px
    classDef logic fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef data fill:#fff3cd,stroke:#ffcd39,stroke-width:1px
    classDef config fill:#f4d35e,stroke:#f4d35e,stroke-width:1px
    classDef tests fill:#e0bbE4,stroke:#9b59b6,stroke-width:1px
```
