# zagart47/tasktrackerbot architecture

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

- Interactive diagram: https://gitdiagram.com/zagart47/tasktrackerbot
- Repository: https://github.com/zagart47/tasktrackerbot

## Overview

#### Purpose and execution
TaskTrackerBot is a Go Telegram bot that captures a user’s prior group-chat message as a task and sends that user a private reminder after a requested interval. The process starts at `cmd/tasktrackerbot/main.go`, which assembles configuration, migrations, storage, use cases, and bot transport.

#### Transport and command boundary
`internal/transport/bot.go` owns Telegram bot integration and update processing. `internal/transport/handler/handler.go` and `internal/transport/handler/tools.go` interpret incoming messages/commands, including the `ctrl <duration>` workflow. The transport layer should only translate Telegram updates into application operations; Telegram is the external boundary.

#### Application use cases
`internal/usecase/usecase.go` defines application-level dependencies/contracts, while `internal/usecase/task.go` coordinates task capture, persistence, and reminder behavior. This layer enforces the workflow: retain relevant chat-message context, associate it with the requesting user, parse/control the reminder deadline, and trigger task operations without depending directly on Telegram or SQL details.

#### Domain and service layer
`internal/entity/task.go` contains the core task representation. `internal/service/service.go` and `internal/service/task.go` implement domain-oriented task operations used by use cases. This separates reminder/task rules from delivery and persistence mechanisms.

#### Persistence and cache
`internal/storage/storage.go` defines storage-facing abstractions. PostgreSQL is the durable task store, implemented by `internal/storage/postgresql/postgresql.go` and `internal/storage/postgresql/task.go`, with schema creation in `internal/storage/postgresql/migrations/000001_tasks.up.sql`. `internal/storage/cache/memcache.go` provides an in-memory/cache-oriented storage component, likely supporting transient message/task context; despite the README naming Redis, the repository path identifies this implementation as `memcache`.

#### Reminder scheduling
`pkg/remind/reminder.go` is the reminder mechanism invoked around stored task deadlines. It forms the time-based boundary between task creation and later private Telegram notification; use cases/services provide task data, while transport delivers the notification.

#### Runtime, configuration, and deployment
`config/config.go` loads application settings, with defaults/sample values in `config/_config.yaml`; the bot token is required for Telegram access. `pkg/migration/migration.go` applies database migrations at startup or deployment. `Dockerfile` and `docker-compose.yml` define the containerized runtime, with PostgreSQL and cache infrastructure expected alongside the Go service.

Main entry points: [`cmd/tasktrackerbot/main.go`](https://github.com/zagart47/tasktrackerbot/blob/master/cmd/tasktrackerbot/main.go) (Application bootstrap), [`internal/usecase/task.go`](https://github.com/zagart47/tasktrackerbot/blob/master/internal/usecase/task.go) (Task workflow), [`internal/service/task.go`](https://github.com/zagart47/tasktrackerbot/blob/master/internal/service/task.go) (Task operations), [`internal/transport/bot.go`](https://github.com/zagart47/tasktrackerbot/blob/master/internal/transport/bot.go) (Bot update processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_docker["Container runtime<br/>deployment"]
  node_compose["Compose stack<br/>deployment<br/>[docker-compose.yml]"]
  node_main["Application bootstrap<br/>Go entrypoint<br/>[main.go]"]
  node_config["Configuration<br/>Go config<br/>[config.go]"]
  node_migration["Migration runner<br/>Go migration<br/>[migration.go]"]
end

subgraph group_transport["Telegram transport"]
  node_telegram{{"Telegram API<br/>external service"}}
  node_bot["Bot update processor<br/>Go transport<br/>[bot.go]"]
  node_handler["Command handler<br/>Go handler<br/>[handler.go]"]
  node_handler_tools["Handler tools<br/>Go handler support<br/>[tools.go]"]
end

subgraph group_application["Application"]
  node_usecase_contracts["Use case contracts<br/>Go contracts<br/>[usecase.go]"]
  node_task_usecase["Task workflow<br/>Go use case<br/>[task.go]"]
  node_task_entity["Task<br/>domain entity<br/>[task.go]"]
  node_task_service["Task operations<br/>Go domain service<br/>[task.go]"]
  node_service_contracts["Service contracts<br/>Go service<br/>[service.go]"]
  node_reminder["Reminder scheduler<br/>Go time service<br/>[reminder.go]"]
end

subgraph group_persistence["Persistence"]
  node_storage_contracts["Storage contracts<br/>Go contracts<br/>[storage.go]"]
  node_postgres[("PostgreSQL task store<br/>Go repository<br/>[task.go]")]
  node_postgres_base["PostgreSQL connection<br/>Go storage<br/>[postgresql.go]"]
  node_schema["Tasks schema<br/>SQL migration"]
  node_cache[("Message context cache<br/>Go cache<br/>[memcache.go]")]
end

node_compose -->|"runs"| node_docker
node_docker -->|"starts"| node_main
node_main -->|"loads"| node_config
node_main -->|"runs"| node_migration
node_migration -->|"applies"| node_schema
node_main -->|"wires"| node_bot
node_main -->|"constructs"| node_task_usecase
node_main -->|"connects"| node_postgres_base
node_bot -->|"receives updates / sends messages"| node_telegram
node_bot -->|"dispatches"| node_handler
node_handler -->|"uses"| node_handler_tools
node_handler -->|"invokes"| node_task_usecase
node_task_usecase -.->|"depends on"| node_usecase_contracts
node_task_usecase -->|"creates and manages"| node_task_entity
node_task_usecase -->|"coordinates"| node_task_service
node_task_service -.->|"implements"| node_service_contracts
node_task_service -->|"persists through"| node_storage_contracts
node_storage_contracts -.->|"implemented by"| node_postgres
node_storage_contracts -.->|"implemented by"| node_cache
node_postgres -->|"uses connection"| node_postgres_base
node_postgres -->|"stores tasks in"| node_schema
node_task_service -->|"schedules deadlines"| node_reminder
node_reminder -->|"triggers private notification"| node_bot

click node_docker "https://github.com/zagart47/tasktrackerbot/blob/master/Dockerfile"
click node_compose "https://github.com/zagart47/tasktrackerbot/blob/master/docker-compose.yml"
click node_main "https://github.com/zagart47/tasktrackerbot/blob/master/cmd/tasktrackerbot/main.go"
click node_config "https://github.com/zagart47/tasktrackerbot/blob/master/config/config.go"
click node_migration "https://github.com/zagart47/tasktrackerbot/blob/master/pkg/migration/migration.go"
click node_bot "https://github.com/zagart47/tasktrackerbot/blob/master/internal/transport/bot.go"
click node_handler "https://github.com/zagart47/tasktrackerbot/blob/master/internal/transport/handler/handler.go"
click node_handler_tools "https://github.com/zagart47/tasktrackerbot/blob/master/internal/transport/handler/tools.go"
click node_usecase_contracts "https://github.com/zagart47/tasktrackerbot/blob/master/internal/usecase/usecase.go"
click node_task_usecase "https://github.com/zagart47/tasktrackerbot/blob/master/internal/usecase/task.go"
click node_task_entity "https://github.com/zagart47/tasktrackerbot/blob/master/internal/entity/task.go"
click node_task_service "https://github.com/zagart47/tasktrackerbot/blob/master/internal/service/task.go"
click node_service_contracts "https://github.com/zagart47/tasktrackerbot/blob/master/internal/service/service.go"
click node_reminder "https://github.com/zagart47/tasktrackerbot/blob/master/pkg/remind/reminder.go"
click node_storage_contracts "https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/storage.go"
click node_postgres "https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/postgresql/task.go"
click node_postgres_base "https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/postgresql/postgresql.go"
click node_schema "https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/postgresql/migrations/000001_tasks.up.sql"
click node_cache "https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/cache/memcache.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_docker,node_compose,node_main,node_config,node_migration toneBlue
class node_telegram,node_bot,node_handler,node_handler_tools toneAmber
class node_usecase_contracts,node_task_usecase,node_task_entity,node_task_service,node_service_contracts,node_reminder toneMint
class node_storage_contracts,node_postgres,node_postgres_base,node_schema,node_cache toneRose
```

## Components

### Runtime

- [Container runtime](https://github.com/zagart47/tasktrackerbot/blob/master/Dockerfile): deployment · Runs the bot with PostgreSQL and cache infrastructure. · `Dockerfile`
- [Compose stack](https://github.com/zagart47/tasktrackerbot/blob/master/docker-compose.yml): deployment · `docker-compose.yml`
- [Application bootstrap](https://github.com/zagart47/tasktrackerbot/blob/master/cmd/tasktrackerbot/main.go): Go entrypoint · Assembles configuration, migrations, storage, use cases, and bot transport. · `cmd/tasktrackerbot/main.go`
- [Configuration](https://github.com/zagart47/tasktrackerbot/blob/master/config/config.go): Go config · Loads bot and application settings. · `config/config.go`
- [Migration runner](https://github.com/zagart47/tasktrackerbot/blob/master/pkg/migration/migration.go): Go migration · Applies database migrations during startup or deployment. · `pkg/migration/migration.go`

### Telegram transport

- **Telegram API**: external service · Receives group updates and sends private reminders.
- [Bot update processor](https://github.com/zagart47/tasktrackerbot/blob/master/internal/transport/bot.go): Go transport · Owns Telegram integration and update processing. · `internal/transport/bot.go`
- [Command handler](https://github.com/zagart47/tasktrackerbot/blob/master/internal/transport/handler/handler.go): Go handler · Interprets messages and the ctrl duration workflow. · `internal/transport/handler/handler.go`
- [Handler tools](https://github.com/zagart47/tasktrackerbot/blob/master/internal/transport/handler/tools.go): Go handler support · `internal/transport/handler/tools.go`

### Application

- [Use case contracts](https://github.com/zagart47/tasktrackerbot/blob/master/internal/usecase/usecase.go): Go contracts · Defines application dependencies and contracts. · `internal/usecase/usecase.go`
- [Task workflow](https://github.com/zagart47/tasktrackerbot/blob/master/internal/usecase/task.go): Go use case · Captures prior chat context, associates a user, and controls reminder deadlines. · `internal/usecase/task.go`
- [Task](https://github.com/zagart47/tasktrackerbot/blob/master/internal/entity/task.go): domain entity · Core task representation. · `internal/entity/task.go`
- [Task operations](https://github.com/zagart47/tasktrackerbot/blob/master/internal/service/task.go): Go domain service · Applies domain-oriented task and reminder rules. · `internal/service/task.go`
- [Service contracts](https://github.com/zagart47/tasktrackerbot/blob/master/internal/service/service.go): Go service · `internal/service/service.go`
- [Reminder scheduler](https://github.com/zagart47/tasktrackerbot/blob/master/pkg/remind/reminder.go): Go time service · Bridges stored deadlines to later private notification. · `pkg/remind/reminder.go`

### Persistence

- [Storage contracts](https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/storage.go): Go contracts · Defines storage-facing abstractions. · `internal/storage/storage.go`
- [PostgreSQL task store](https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/postgresql/task.go): Go repository · Durable task persistence implementation. · `internal/storage/postgresql/task.go`
- [PostgreSQL connection](https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/postgresql/postgresql.go): Go storage · `internal/storage/postgresql/postgresql.go`
- [Tasks schema](https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/postgresql/migrations/000001_tasks.up.sql): SQL migration · `internal/storage/postgresql/migrations/000001_tasks.up.sql`
- [Message context cache](https://github.com/zagart47/tasktrackerbot/blob/master/internal/storage/cache/memcache.go): Go cache · In-memory cache-oriented storage for transient context. · `internal/storage/cache/memcache.go`

## Connections

- Compose stack → Container runtime: runs
- Container runtime → Application bootstrap: starts
- Application bootstrap → Configuration: loads
- Application bootstrap → Migration runner: runs
- Migration runner → Tasks schema: applies
- Application bootstrap → Bot update processor: wires
- Application bootstrap → Task workflow: constructs
- Application bootstrap → PostgreSQL connection: connects
- Bot update processor → Telegram API: receives updates / sends messages
- Bot update processor → Command handler: dispatches
- Command handler → Handler tools: uses
- Command handler → Task workflow: invokes
- Task workflow → Use case contracts: depends on
- Task workflow → Task: creates and manages
- Task workflow → Task operations: coordinates
- Task operations → Service contracts: implements
- Task operations → Storage contracts: persists through
- Storage contracts → PostgreSQL task store: implemented by
- Storage contracts → Message context cache: implemented by
- PostgreSQL task store → PostgreSQL connection: uses connection
- PostgreSQL task store → Tasks schema: stores tasks in
- Task operations → Reminder scheduler: schedules deadlines
- Reminder scheduler → Bot update processor: triggers private notification