# artemchuban/telegram-test-birthday architecture

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

- Interactive diagram: https://gitdiagram.com/artemchuban/telegram-test-birthday
- Repository: https://github.com/artemchuban/telegram-test-birthday

## Overview

##### A VueJS-based frontend using Pinia for state management.
2. A FastAPI-powered backend (run by Uvicorn) using Turtle ORM to interact with a PostgreSQL database.
3. A Telegram Bot component that currently uses long-polling for updates (with a note that a TLS-encrypted server/w/webhook would be used in production).

##### Main Components
- Frontend:
- Represents the client-side application built with VueJS.
- Includes directories for assets, components, views, router, and state (Pinia).
- Communicates with the backend via API calls.
- Backend:
- Contains the FastAPI application (organized with routers, models, schemas, settings, etc.).
- Responsible for serving API endpoints and business logic.
- Utilizes a PostgreSQL database via the Turtle ORM.
- Bot:
- The Telegram Bot module that handles messaging – currently implemented with long-polling.
- Will eventually integrate with the Telegram API using webhooks.
- May also interact with the backend for user data and scheduling tasks.
- Database:
- PostgreSQL database container.
- The backend’s ORM (Turtle ORM) handles migrations and model interactions.
- External Services:
- Telegram Bot API (external to your infrastructure).
- Docker (and docker-compose) managing the overall container orchestration.

##### Relationships and Interactions
- Frontend ↔ Backend:
- The frontend makes HTTP/API requests to the FastAPI backend.
- Backend ↔ Database:
- FastAPI interacts with PostgreSQL for persistent storage.
- Bot ↔ Telegram API:
- The Bot communicates with Telegram servers using long-polling (or later, webhooks).
- This external connection clearly.
- Bot ↔ Backend (if applicable):
- The Bot might pull additional data from or push updates to the backend.
- This interaction if the integration exists in your design.

##### Architectural Patterns and Technologies
- Microservices/Containerization:
- Each component (frontend, backend, bot, database) is containerized using Docker.
- docker-compose orchestrates the containers, connecting them as per defined environment variables.
- Separation of Concerns:
- Frontend handles user interaction.
- Backend encapsulates core business logic and API endpoint definitions.
- Bot handles real-time interaction with Telegram.
- Technology Stack:
- Frontend: VueJS, Pinia, Vite, and supporting tools (ESLint, Prettier, TypeScript configurations).
- Backend: FastAPI running on Uvicorn, Docker, and Turtle ORM for database interactions.
- Bot: Python-based, with a similar structure to the backend, operated via Docker.
- Database: PostgreSQL hosted as a separate service/container.
- CI/CD: GitHub workflows for frontend, backend, and bot deployments.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Docker Compose Orchestration"
        F["Frontend (VueJS, Pinia)"]:::frontend
        B["Backend (FastAPI, Turtle ORM)"]:::backend
        T["Bot (Telegram Bot: Long-polling)"]:::bot
        DB(("Database (PostgreSQL)")):::database
    end
    Tg["Telegram API"]:::external

    F -->|"API calls(HTTP)"| B
    B -->|"ORM queries(Turtle ORM)"| DB
    T -->|"Long-polling/Webhook"| Tg
    T <-->|"Data Exchange"| B

    click F "https://github.com/artemchuban/telegram-test-birthday/tree/main/frontend/"
    click B "https://github.com/artemchuban/telegram-test-birthday/tree/main/backend/app/"
    click T "https://github.com/artemchuban/telegram-test-birthday/tree/main/bot/app/"

    classDef frontend fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef backend fill:#66cc66,stroke:#333,stroke-width:2px;
    classDef bot fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef database fill:#ff9966,stroke:#333,stroke-width:2px;
    classDef external fill:#ff6699,stroke:#333,stroke-width:2px;
```
