# prok0l/nakormi architecture

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

- Interactive diagram: https://gitdiagram.com/prok0l/nakormi
- Repository: https://github.com/prok0l/nakormi

## Overview

##### Project type and purpose
- This is a two-part Python system:
- A Django-based REST API server (“nakormi_back”) that manages users, points, feeds, and core business logic.
- A Telegram Bot service (“nakormi_bot”) that interacts with end users via the Telegram API and forwards requests to the backend.
- The README confirms this: you install dependencies for each, configure `.env` files, run the Django server, then launch the bot.

##### File structure
- Top-level directories:
- `nakormi_back/` – a standard Django project (apps: feed, main, point, user).
- `nakormi_bot/` – an event-driven bot with modules for handlers, middlewares, entities, services, keyboards, phrases, etc.
- Deployment artifacts:
- `docker-compose.yaml` orchestrates at least the backend + database.
- Two `Dockerfile`s for backend and bot.
- Look for patterns:
- Django uses MVC (Models, Views, Serializers, URLs).
- Bot follows a command/handler pattern with a service layer (`services/api`) that calls the backend.

##### README for additional insights
- Environment variables: database connectivity for backend; API address and secrets for the bot.
- Startup steps: migrate and run Django, then launch the bot as a Python module.

a. Main components
- Telegram End User (people chatting in Telegram)
- Telegram API (external service)
- Bot Service (`nakormi_bot`)
- REST API Server (`nakormi_back`)
- Database (PostgreSQL or similar)
- (Optionally) Docker-Compose / Kubernetes orchestrator
b. Relationships & data flows
1. User → Telegram API → Bot Service → Backend API → Database
2. Bot Service ← Backend API responses ← Database
3. Bot Service → Telegram API → User
4. Backend API’s Django apps interact internally (feed, point, user, main)
c. Architectural patterns & design principles
- Backend: Monolithic Django REST app with clearly separated apps (each app has models, serializers, views, URLs).
- Bot: Modular handler-based design, with a thin “service” layer that wraps HTTP calls to the API.
- Use of environment-based configuration, Docker for immutability, and a clear client-server boundary.
d. Key technologies & frameworks
- Python 3.x, Django, Django REST Framework
- Telegram Bot API (via `python-telegram-bot` or similar)
- Docker & docker-compose
- PostgreSQL (or any RDBMS configured via `.env`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External
    subgraph "External"
        direction TB
        User["Telegram End User"]:::external
        TelegramAPI["Telegram API"]:::external
    end

    %% Bot Service
    subgraph "Bot Service" 
        direction TB
        BotRoot["Service Root"]:::client
        BotMain["Main Entry (__main__.py)"]:::client
        subgraph "Handlers & Middleware"
            direction TB
            Handlers["Handlers"]:::client
            Middlewares["Middlewares"]:::client
        end
        subgraph "Bot Core Layers"
            direction TB
            ServicesAPI["Service Layer (API Client)"]:::client
            Entities["Entities"]:::client
            Keyboards["Keyboards"]:::client
            Phrases["Phrases"]:::client
            Globals["Globals & Common"]:::client
            Functional["Functional Helpers"]:::client
        end
    end

    %% Docker Compose Orchestration
    subgraph "Orchestration (docker-compose)" 
        direction TB
        subgraph "REST API Service"
            direction TB
            APIService["Django REST API"]:::server
            subgraph "Django Project"
                direction TB
                Manage["manage.py"]:::server
                Settings["settings.py"]:::server
                URLsConfig["urls.py"]:::server
                subgraph "Apps"
                    direction TB
                    FeedApp["Feed App"]:::server
                    MainApp["Main App"]:::server
                    PointApp["Point App"]:::server
                    UserApp["User App"]:::server
                end
            end
        end
        Database["Database (PostgreSQL)"]:::database
    end

    %% Flows
    User -->|"messages"| TelegramAPI
    TelegramAPI -->|"updates"| Handlers
    Handlers -->|"apply filters"| Middlewares
    Middlewares -->|"HTTP calls"| ServicesAPI
    ServicesAPI -->|"REST endpoints"| APIService
    APIService -->|"ORM queries"| Database
    Database -->|"data"| APIService
    APIService -->|"JSON response"| ServicesAPI
    ServicesAPI -->|"send reply"| TelegramAPI
    TelegramAPI -->|"messages"| User

    %% Click Events - Bot
    click BotRoot "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/"
    click BotMain "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/__main__.py"
    click BotDockerfile "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/Dockerfile"
    click BotHandlers "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/handlers/"
    click BotMidd "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/middlewares/"
    click BotAPIServ "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/services/api/"
    click backendWrapper "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/services/api/backend.py"
    click feedService "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/services/api/internal/feed_service.py"
    click mainService "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/services/api/internal/main_service.py"
    click pointService "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/services/api/internal/point_service.py"
    click userService "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/services/api/internal/user_service.py"
    click BotEntities "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/entities/"
    click BotKeyboards "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/keyboards/"
    click BotPhrases "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/phrases/"
    click BotGlobals "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/globals.py"
    click BotCommon "https://github.com/prok0l/nakormi/blob/main/nakormi_bot/services/common.py"
    click BotFunctional "https://github.com/prok0l/nakormi/tree/main/nakormi_bot/functional/"

    %% Click Events - Backend
    click RESTAPI "https://github.com/prok0l/nakormi/tree/main/nakormi_back/"
    click Settings "https://github.com/prok0l/nakormi/blob/main/nakormi_back/nakormi_back/settings.py"
    click URLsConfig "https://github.com/prok0l/nakormi/blob/main/nakormi_back/nakormi_back/urls.py"
    click Manage "https://github.com/prok0l/nakormi/blob/main/nakormi_back/manage.py"
    click BackendDockerfile "https://github.com/prok0l/nakormi/tree/main/nakormi_back/Dockerfile"
    click DockerCompose "https://github.com/prok0l/nakormi/blob/main/docker-compose.yaml"
    click FeedApp "https://github.com/prok0l/nakormi/tree/main/nakormi_back/feed/"
    click feedModels "https://github.com/prok0l/nakormi/blob/main/nakormi_back/feed/models.py"
    click feedSerializers "https://github.com/prok0l/nakormi/blob/main/nakormi_back/feed/serializers.py"
    click feedViews "https://github.com/prok0l/nakormi/blob/main/nakormi_back/feed/views.py"
    click feedURLs "https://github.com/prok0l/nakormi/blob/main/nakormi_back/feed/urls.py"
    click MainApp "https://github.com/prok0l/nakormi/tree/main/nakormi_back/main/"
    click functions "https://github.com/prok0l/nakormi/blob/main/nakormi_back/main/functions.py"
    click mainModels "https://github.com/prok0l/nakormi/blob/main/nakormi_back/main/models.py"
    click mainSerializers "https://github.com/prok0l/nakormi/blob/main/nakormi_back/main/serializers.py"
    click mainViews "https://github.com/prok0l/nakormi/blob/main/nakormi_back/main/views.py"
    click mainURLs "https://github.com/prok0l/nakormi/blob/main/nakormi_back/main/urls.py"
    click PointApp "https://github.com/prok0l/nakormi/tree/main/nakormi_back/point/"
    click pointModels "https://github.com/prok0l/nakormi/blob/main/nakormi_back/point/models.py"
    click pointSerializers "https://github.com/prok0l/nakormi/blob/main/nakormi_back/point/serializers.py"
    click pointViews "https://github.com/prok0l/nakormi/blob/main/nakormi_back/point/views.py"
    click pointURLs "https://github.com/prok0l/nakormi/blob/main/nakormi_back/point/urls.py"
    click UserApp "https://github.com/prok0l/nakormi/tree/main/nakormi_back/user/"
    click userModels "https://github.com/prok0l/nakormi/blob/main/nakormi_back/user/models.py"
    click userSerializers "https://github.com/prok0l/nakormi/blob/main/nakormi_back/user/serializers.py"
    click userViews "https://github.com/prok0l/nakormi/blob/main/nakormi_back/user/views.py"
    click userURLs "https://github.com/prok0l/nakormi/blob/main/nakormi_back/user/urls.py"

    %% Styles
    classDef external fill:#dddddd,stroke:#888,stroke-width:1px;
    classDef client fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef server fill:#80cbc4,stroke:#00796b,stroke-width:1px;
    classDef database fill:#c8e6c9,stroke:#388e3c,stroke-width:1px;
```
