# nvh0610/polyglothub-be architecture

> Architecture diagram of the GitHub repository nvh0610/polyglothub-be, 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/nvh0610/polyglothub-be
- Repository: https://github.com/nvh0610/polyglothub-be

## Overview

This project is a backend service written in Go that appears to serve as an API for handling user authentication, vocabulary management, flashcard scheduling, and related functionalities. The file tree showcases a clear layered or modular architecture with directories for controllers, repositories, entities, configuration, middleware, and platform-specific database connectors. Although the README has no content, we can deduce the system’s purpose by reading into the components and file names.

##### Main Components
- API Gateway/Router: Represented by the internal/router directory—the entry point that directs incoming HTTP requests to the appropriate controller endpoints.
- Controllers: Found in internal/controller, which handles various domains (auth, category, flashcard_daily, user, vocabulary, etc.). These implement business logic and request handling.
- Repository Layer: Housed in internal/repository for data access. Each domain (e.g., category, user, vocabulary) has its own repository, often with interfaces to allow abstraction.
- Entities: Found in internal/entity, representing the data models for business objects.
- Shared/Common Utilities: Directories like pkg (configuration, JWT, middleware, logging, utility functions) provide cross-cutting concerns and shared tools.
- Platform-Specific Integrations: In the platform directory, which includes database connection modules (MySQL, Redis) and an OTP sending service.
- Jobs and Migrations: The job directory (for scheduling tasks) and the migration directory (for database schema management) provide additional support functions.
- Supporting Infrastructure: Files like Dockerfile, Makefile, and GitHub workflows indicate continuous deployment/integration aspects.

##### Relationships and Interactions
- Incoming requests flow from external clients to the API Gateway (router). The router then routes requests to the appropriate controller based on the URL mapping or API endpoint.
- Controllers process the inputs, use payload/request/response definitions (under internal/router/payload) for validation and formatting, and call underlying repository methods.
- The Repository layer interacts with the physical data storage, such as MySQL (via platform/mysqldb) and caching/data-store like Redis (via platform/redisdb).
- The code also handles authentication via JWTs (in pkg/jwt) and validation/middleware (in pkg/middleware and pkg/utils).
- The layered structure of controllers calling repositories (which then use platform connectors) reflects principles like separation of concerns and dependency inversion.

##### Architectural Patterns and Design Principles
- Modular Design: Separation of controllers, repositories, entities, and shared packages.
- Layered Architecture / Hexagonal Architecture: Clear boundaries between the presentation (controllers), business logic (services within controllers), and data access layers (repositories).
- Dependency Inversion: Interfaces in controllers and repositories allow for easier testing and replacement of underlying implementations.
- Use of Infrastructure as Code: Docker and CI/CD (GitHub workflows) illustrate modern devops practices.
- Scheduled Jobs: The job/schedule module indicates that background tasks or batch jobs are part of the system.

##### Visualizing Details
- Use clear labels for each component:
– “Router (internal/router)”
– “Auth Controller, User Controller, etc.”
– “Category Repository,” “User Repository,” etc.
– “Business Entities”
– “MySQL Database (platform/mysqldb)”
– “Redis Cache (platform/redisdb)”
– “JWT Service (pkg/jwt)” and so on.
– From External Clients to the API Gateway.
– From the Router to various Controllers.
– From Controllers to their respective Repository layers.
– From Repositories to external databases (MySQL, Redis) and services (OTP via email).
– A different style for business or service layers (repositories, entities).
– Another distinct representation for external services (databases, email, third-party integrations).

##### Detail and Granularity
- Architectural elements are captured explicitly. Include supporting modules (configuration, JWT, logging, middleware), as they are crucial to how the system operates.
- Be meticulous in labeling each module, showing data flows and interactions clearly. The goal is to provide a comprehensive view of all layers – from client request to persistent storage.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% External Clients
    subgraph "External Clients"
        EC("External Clients"):::external
    end

    %% API Gateway/Router Layer
    subgraph "API Gateway/Router"
        R("Router (internal/router)"):::router
        P("Payload (internal/router/payload)"):::router
    end

    %% Controllers Layer
    subgraph "Controllers"
        C("Controllers (internal/controller)"):::controller
    end

    %% Repository Layer
    subgraph "Repositories"
        REP("Repositories (internal/repository)"):::repository
    end

    %% Data Storage & Platform Services
    subgraph "Platform Services & Data Storage"
        MYSQL("MySQL DB (platform/mysqldb)"):::data
        REDIS("Redis Cache (platform/redisdb)"):::data
        OTP("OTP Service (platform/send_otp)"):::data
    end

    %% Shared/Common Utilities
    subgraph "Shared Services"
        CONF("Config (pkg/config)"):::utility
        JWT("JWT (pkg/jwt)"):::utility
        LOG("Logger (pkg/logger)"):::utility
        MID("Middleware (pkg/middleware)"):::utility
        PWD("Password (pkg/password)"):::utility
        RESP("Resp (pkg/resp)"):::utility
        UTLS("Utils (pkg/utils)"):::utility
    end

    %% Business Entities
    subgraph "Business Entities"
        ENT("Entities (internal/entity)"):::entity
    end

    %% Infrastructure (Jobs, Migrations, CI/CD)
    subgraph "Infrastructure"
        JOB("Job Scheduler (job/schedule)"):::infra
        MIG("Migrations (migration)"):::infra
        DOCK("Dockerfile"):::infra
        MAKE("Makefile"):::infra
        WF("Workflows (.github/workflows)"):::infra
    end

    %% Main Flow
    EC -->|"requests"| R
    R -->|"validates"| P
    R -->|"routes"| C
    C -->|"invokes"| REP
    REP -->|"queries"| MYSQL
    REP -->|"caches"| REDIS
    REP -->|"sends OTP"| OTP
    REP -->|"maps data"| ENT

    %% Controllers using shared services
    C -->|"configures"| CONF
    C -->|"authenticates"| JWT
    C -->|"logs"| LOG
    C -->|"applies"| MID
    C -->|"verifies"| PWD
    C -->|"responds with"| RESP
    C -->|"utilizes"| UTLS

    %% Job Scheduler interaction
    JOB -->|"triggers tasks on"| MYSQL

    %% Styles
    classDef external fill:#FFEEAD,stroke:#333,stroke-width:2px;
    classDef router fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef controller fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef repository fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef data fill:#FFF9C4,stroke:#333,stroke-width:2px;
    classDef utility fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef entity fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef infra fill:#F8BBD0,stroke:#333,stroke-width:2px;

    %% Click Events
    click R "https://github.com/nvh0610/polyglothub-be/blob/main/internal/router/router.go"
    click P "https://github.com/nvh0610/polyglothub-be/tree/main/internal/router/payload"
    click C "https://github.com/nvh0610/polyglothub-be/tree/main/internal/controller"
    click REP "https://github.com/nvh0610/polyglothub-be/tree/main/internal/repository"
    click ENT "https://github.com/nvh0610/polyglothub-be/tree/main/internal/entity"

    click CONF "https://github.com/nvh0610/polyglothub-be/tree/main/pkg/config"
    click JWT "https://github.com/nvh0610/polyglothub-be/tree/main/pkg/jwt"
    click LOG "https://github.com/nvh0610/polyglothub-be/tree/main/pkg/logger"
    click MID "https://github.com/nvh0610/polyglothub-be/tree/main/pkg/middleware"
    click PWD "https://github.com/nvh0610/polyglothub-be/tree/main/pkg/password"
    click RESP "https://github.com/nvh0610/polyglothub-be/tree/main/pkg/resp"
    click UTLS "https://github.com/nvh0610/polyglothub-be/tree/main/pkg/utils"

    click MYSQL "https://github.com/nvh0610/polyglothub-be/tree/main/platform/mysqldb"
    click REDIS "https://github.com/nvh0610/polyglothub-be/tree/main/platform/redisdb"
    click OTP "https://github.com/nvh0610/polyglothub-be/tree/main/platform/send_otp"

    click JOB "https://github.com/nvh0610/polyglothub-be/tree/main/job/schedule"
    click MIG "https://github.com/nvh0610/polyglothub-be/tree/main/migration"
    click DOCK "https://github.com/nvh0610/polyglothub-be/tree/main/Dockerfile"
    click MAKE "https://github.com/nvh0610/polyglothub-be/tree/main/Makefile"
    click WF "https://github.com/nvh0610/polyglothub-be/tree/main/.github/workflows"
```
