# kma-score/kma_score_api architecture

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

- Interactive diagram: https://gitdiagram.com/kma-score/kma_score_api
- Repository: https://github.com/kma-score/kma_score_api

## Overview

##### Main Components
- Client/Consumer: Represent external clients (web/mobile applications) that send HTTP requests.
- API Gateway/Entry Point: The main.go file acts as the entry point to the Go application. Represent this as the “API Server.”
- Business Logic / Models: Include the “models” (Student, Score, Subject, ApiKey, etc) that encapsulate the domain entities.
- Database Access: Add a block for the “database” package, which contains the database connection logic (database.go) that connects to MariaDB/MySQL.
- Cron Jobs & Integration Tasks: Represent the “cron” component (with files like init.go and update_meilisearch.go) which schedule and execute tasks (such as updating Meilisearch indices).
- Configuration & Utilities: Create a section for “config” (for Meilisearch configuration) and “utils”, where functionalities like JWT management, AES encryption, file handling, and Meilisearch integration are implemented.
- External Services:
- Database Server: MariaDB/MySQL as the persistent store.
- Meilisearch: Represent this external search service which the API interacts with.
- Deployment/Containerization:
- Docker & Docker Compose: Indicate that the system is containerized. This can be represented by a container symbol around the API and its related components, with additional references to deployment automation (GitHub workflows).

##### Relationships and Interactions
- That requests pass through the Middlewares (API checker, CORS, rate limiter, logging) before reaching the Handlers.
- The Database component (showing CRUD operations).
- The Meilisearch service (for search functionality, via utilities and cron tasks).

##### Architectural Patterns and Design Principles
- Modularity: Emphasize separation of concerns, with distinct packages for handlers, middlewares, models, utilities, database access, and cron jobs.
- Layered Architecture: Illustrate layers from presentation (HTTP handlers) to business logic (models and utils) and data access (database).
- Containerization: Indicate Docker-based deployment as a separate layer for operational management.
- Integration with External Services: Clearly separate external dependencies such as the database and external search service, noting that while the API service is monolithic, it relies on clearly defined external services.

##### Relevant Technologies
- Mention Docker in the deployment section along with docker-compose orchestration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    A["Client/External Consumers"]:::external

    %% API Server Layer
    B["API Gateway (main.go)"]:::server

    %% Middleware Layer
    C["Middlewares"]:::middleware

    %% HTTP Handlers Layer
    D["HTTP Handlers"]:::handlers

    %% Business Logic Layer
    E["Business Logic/Models"]:::models

    %% Configuration Layer
    F1["Configuration (.env, Meilisearch config)"]:::config

    %% Utilities Layer
    F2["Utilities"]:::utils

    %% Database Access Layer
    G["Database Access"]:::database

    %% Cron Jobs Layer
    H["Cron Jobs & Integration Tasks"]:::cron

    %% Deployment/Containerization
    I["Deployment/Containerization"]:::deployment

    %% External Services Layer
    J["MariaDB/MySQL Database"]:::externalDB
    K["Meilisearch Service"]:::external

    %% Flow Connections
    A -->|"HTTPRequest"| B
    B -->|"passes"| C
    C -->|"routes"| D
    D -->|"executes"| E
    E -->|"CRUD Operations"| G
    E -->|"triggers search"| K
    D -->|"utilizes"| F2
    B -->|"loads"| F1
    B -->|"schedules"| H
    H -->|"updates index"| K
    I -->|"hosts"| B
    I -->|"contains"| D
    I -->|"packs"| E
    I -->|"bundles"| F1
    I -->|"bundles"| F2

    %% External connections
    G ---|"connects"| J

    %% Click Events for Component Mapping
    click B "https://github.com/kma-score/kma_score_api/blob/main/main.go"
    click D "https://github.com/kma-score/kma_score_api/tree/main/handlers/"
    click C "https://github.com/kma-score/kma_score_api/tree/main/middlewares/"
    click E "https://github.com/kma-score/kma_score_api/tree/main/models/"
    click G "https://github.com/kma-score/kma_score_api/blob/main/database/database.go"
    click H "https://github.com/kma-score/kma_score_api/tree/main/cron/"
    click F1 "https://github.com/kma-score/kma_score_api/tree/main/config/"
    click F2 "https://github.com/kma-score/kma_score_api/tree/main/utils/"
    click I "https://github.com/kma-score/kma_score_api/blob/main/docker-compose.yml"

    %% Styles
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef server fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef middleware fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef handlers fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef models fill:#A9DFBF,stroke:#117864,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef utils fill:#A2D9CE,stroke:#117864,stroke-width:2px;
    classDef database fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef cron fill:#E5E7E9,stroke:#7B7D7D,stroke-width:2px;
    classDef deployment fill:#F0B27A,stroke:#D35400,stroke-width:2px;
    classDef externalDB fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef external fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
```
