# altiordev/easy_quiz_bot architecture

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

- Interactive diagram: https://gitdiagram.com/altiordev/easy_quiz_bot
- Repository: https://github.com/altiordev/easy_quiz_bot

## Overview

##### Project Overview and Main Components
- This project is a backend service for a Telegram-based quiz bot. It manages user authentication, quiz/test creation and execution, and integrates with PostgreSQL via Sequelize.
- The major building blocks include:
- Bot Module: Manages Telegram bot functionality using Telegraf, including scenes and keyboard interactions.
- API/Authentication Module: Provides Express endpoints for authentication (login, user registration) and CRUD operations for topics/tests/questions using RESTful design.
- Test Module: Handles quiz test logic, including question flow, managing user responses, and calculating results.
- Database Layer: Uses Sequelize to interface with a PostgreSQL database, mapping topics, tests, questions, options, and user answers.
- Middleware and Error Handling: Includes admin-checks, error handlers, and request/response validations.
- Utilities and Enums: Provides supporting functions and constants to support validation, data escaping, and status/error management.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize that each main feature (auth, bot, tests) is in its own module and folder structure, simplifying maintenance and future extension.
- Separation of Concerns: Differentiate the Telegram bot logic from the RESTful API logic. Show clear boundaries between external communication (Telegram API) and internal service logic.
- Data Flow Direction:
- Incoming requests or messages (via webhook/polling or API calls) hit the Express app.
- Controllers route requests to service layers (auth.service, test.service, bot.service, etc.).
- Service layers interact with the database through Sequelize.
- Responses and updates flow back to the requester or, for bot interactions, are sent as Telegram messages.
- Use of TypeScript: Note that strong typing assists in maintaining well-defined interfaces (stored under src/interfaces).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Services
    EXT_TG["Telegram API"]:::external
    EXT_AD["Client/Admin"]:::external

    %% Backend Core System
    EAPI["Express API Server"]:::internal
    BOT["Bot Module"]:::internal
    AUTH["Auth Module"]:::internal
    TEST["Test Module"]:::internal
    MW["Middleware & Error Handling"]:::internal
    CORE["Core Modules/Repository"]:::internal
    UTIL["Utilities & Enums"]:::internal

    %% Data Persistence
    DB[(PostgreSQL via Sequelize)]:::db

    %% Data Flow: External to Backend
    EXT_AD -->|"HTTP_Request"| EAPI
    EXT_TG -->|"Webhook_Callback"| BOT

    %% Express API Server flows
    EAPI -->|"RouteTo"_AUTH| AUTH
    EAPI -->|"RouteTo"_TEST| TEST
    EAPI -->|"Invoke"_MW| MW
    EAPI -->|"DB_Query"| DB

    %% Bot Module flows
    BOT -->|"DB_Query"| DB
    BOT -->|"ServiceCall"| CORE
    BOT -->|"Utilize"| UTIL

    %% Auth Module flows
    AUTH -->|"DB_Query"| DB
    AUTH -->|"ServiceCall"| CORE
    AUTH -->|"Utilize"| UTIL

    %% Test Module flows
    TEST -->|"DB_Query"| DB
    TEST -->|"ServiceCall"| CORE
    TEST -->|"Utilize"| UTIL

    %% Click Events
    click EAPI "https://github.com/altiordev/easy_quiz_bot/blob/main/src/app.ts"
    click BOT "https://github.com/altiordev/easy_quiz_bot/tree/main/src/bot"
    click AUTH "https://github.com/altiordev/easy_quiz_bot/tree/main/src/auth"
    click TEST "https://github.com/altiordev/easy_quiz_bot/tree/main/src/test"
    click DB "https://github.com/altiordev/easy_quiz_bot/blob/main/src/database/sequelize.ts"
    click MW "https://github.com/altiordev/easy_quiz_bot/tree/main/src/middleware"
    click UTIL "https://github.com/altiordev/easy_quiz_bot/tree/main/src/enums"
    click CORE "https://github.com/altiordev/easy_quiz_bot/blob/main/src/core/core.repo.ts"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px,color:#000;
    classDef internal fill:#AED581,stroke:#333,stroke-width:2px,color:#000;
    classDef db fill:#FFAB91,stroke:#D84315,stroke-width:2px,color:#000;
```
