# dennisblokland/nihongobot architecture

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

- Interactive diagram: https://gitdiagram.com/dennisblokland/nihongobot
- Repository: https://github.com/dennisblokland/nihongobot

## Overview

##### Main Components
- Telegram Bot User Interface: Represents the end-user interacting through the Telegram client.
- App Host & Server Layers: “NihongoBot.AppHost” (and possibly “NihongoBot.Server”) which include the Program.cs entry points. These provide the runtime environments, configuration (e.g., appsettings.json), container orchestration outputs (see aspirate-output/docker-compose.yaml), and overall startup orchestration.
- Application Layer: Found in “NihongoBot.Application” composed of various handlers (e.g., StartCommandHandler, StopCommandHandler, ResetStreakCommandHandler), services (BotService, CommandDispatcher, CallbackDispatcher, HangfireSchedulerService, HiraganaService, JlptVocabApiService), and workers such as “TelegramBotWorker”. This layer manages business logic, command processing, and scheduling.
- Domain Layer: Contained in “NihongoBot.Domain”, includes aggregates like Kana, Question, and User, along with domain enums, base types, and interfaces for domain entities and repositories. This represents the core business logic and rules.
- Infrastructure Layer: “NihongoBot.Infrastructure” is responsible for dependency injection and the implementations of infrastructural concerns such as repository instantiation and service collection extensions.
- Persistence Layer: “NihongoBot.Persistence” covers the database context with EF Core configurations, migrations, and the actual data access logic (using AppDbContext, configuration classes, and JSON-based assets like hiragana.json).
- Shared Components: “NihongoBot.Shared” includes common options and configuration classes for connection strings and application options.
- Tests: Unit tests are organized in the Tests folder verifying the different handlers and services.

##### Relationships & Interactions
- The Telegram client sends commands/messages to the bot. These are received and processed through the Hosting layer (AppHost/Server) which instantiates the TelegramBotWorker.
- The worker office delegates commands and callbacks to corresponding handlers in the Application layer.
- The Application layer uses services like BotService and dispatcher components to orchestrate command execution. In many cases, these services also interact with domain logic and utilize domain models or aggregates.
- Domain layer – the heart of the business logic – is used by the Repository implementations in the Infrastructure layer via domain interfaces (IDomainEntity, IRepository, etc.).
- Infrastructure and Persistence interact where the Infrastructure layer hosts the concrete implementations of the repository interfaces (e.g., KanaRepository, QuestionRepository, UserRepository), which then access the underlying database via EF Core. Database migrations and configurations are managed here.
- Optional external services (like Hangfire for scheduling) are integrated via the Application’s HangfireSchedulerService.

##### Architectural Patterns and Design Principles
- Domain Driven Design: Clear separation of Domain, Application, Infrastructure, and Persistence layers.
- Dependency Injection: Seen in Infrastructure with ServiceCollectionExtensions to register dependencies.
- Command & Callback Handling: Usage of command handlers, callback handlers, and corresponding dispatcher logic demonstrates a decoupled command/query pattern.

##### Relevant Technologies & Components
- .NET Core 9.0 for runtime.
- Entity Framework Core for data persistence and migrations.
- Hangfire for scheduling tasks.
- Telegram Bot API for external integrations.
- Potential use of Docker (as observed from the aspirate-output/docker-compose.yaml) for deployments.

##### Specific Elements
- Clear labels for each major component (e.g., “Telegram Bot Client”, “AppHost – Entry Point”, “TelegramBotWorker”, “Command Dispatcher”, “Domain Aggregates”, “Infrastructure Repositories”, “EF Core Persistence/DB”).
- External systems like Telegram’s API and potentially Docker deployment lanes.

##### Detail and Clarity
- Do not shy away from splitting the design into as many components as they logically appear. For example, you may have separate nodes for “Command Handlers”, “Callback Handlers”, “Domain Aggregates (Kana, Question, User)”, and “Repositories”.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External User Interface
    UI["Telegram Bot Client"]:::external

    %% Hosting Layer
    subgraph "Hosting Layer"
        AppHost["AppHost (Program.cs)"]:::host
        Server["Server (Program.cs)"]:::host
    end

    %% Application Layer
    subgraph "Application Layer"
        Worker["TelegramBotWorker"]:::appWorker
        CmdDispatcher["Command Dispatcher"]:::appService
        BotSvc["Bot Service"]:::appService
        Hangfire["Hangfire Scheduler Service"]:::appService
    end

    %% Domain Layer
    subgraph "Domain Layer"
        DomainAgg["Domain Aggregates (Kana, Question, User)"]:::domain
    end

    %% Infrastructure & Persistence Layer
    subgraph "Infrastructure & Persistence"
        Infra["Infrastructure Layer (DI, Repositories)"]:::infra
        Persistence["EF Core Persistence/DB"]:::persistence
    end

    %% Shared & Tests
    subgraph "Shared & Tests"
        Shared["Shared Components (Options)"]:::shared
        Tests["Unit Tests"]:::tests
    end

    %% Connections / Flow
    UI -->|"sendsMessage"| AppHost
    UI -->|"sendsMessage"| Server

    AppHost -->|"starts"| Worker
    Server -->|"starts"| Worker

    Worker -->|"dispatchesCommand"| CmdDispatcher
    CmdDispatcher -->|"invokesHandler"| BotSvc
    BotSvc -->|"appliesBusinessLogic"| DomainAgg
    DomainAgg -->|"repositoryCalls"| Infra
    Infra -->|"dataAccess"| Persistence

    %% Hangfire integration for scheduling
    Worker -->|"schedulesTask"| Hangfire

    %% Shared configurations used by Application services
    CmdDispatcher -->|"usesConfig"| Shared
    BotSvc -->|"usesConfig"| Shared

    %% Tests verifying application layer components
    Tests -->|"validates"| CmdDispatcher
    Tests -->|"validates"| BotSvc

    %% Click Events
    click Worker "https://github.com/dennisblokland/nihongobot/blob/main/NihongoBot.Application/Workers/TelegramBotWorker.cs"
    click AppHost "https://github.com/dennisblokland/nihongobot/blob/main/NihongoBot.AppHost/Program.cs"
    click Server "https://github.com/dennisblokland/nihongobot/blob/main/NihongoBot.Server/Program.cs"
    click DomainAgg "https://github.com/dennisblokland/nihongobot/blob/main/NihongoBot.Domain"
    click Infra "https://github.com/dennisblokland/nihongobot/blob/main/NihongoBot.Infrastructure"
    click Persistence "https://github.com/dennisblokland/nihongobot/blob/main/NihongoBot.Persistence"
    click Shared "https://github.com/dennisblokland/nihongobot/blob/main/NihongoBot.Shared"
    click Tests "https://github.com/dennisblokland/nihongobot/tree/main/Tests"

    %% Styles
    classDef external fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef host fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef appWorker fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef appService fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef domain fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef infra fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef persistence fill:#FDEDEC,stroke:#922B21,stroke-width:2px;
    classDef shared fill:#EBF5FB,stroke:#1F618D,stroke-width:2px;
    classDef tests fill:#EDBB99,stroke:#A04000,stroke-width:2px;
```
