# lc-tut/club-portal architecture

> Architecture diagram of the GitHub repository lc-tut/club-portal, 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/lc-tut/club-portal
- Repository: https://github.com/lc-tut/club-portal

## Overview

##### Project Overview
- The project is a backend service implemented in Golang using the Gin framework. It powers the Tokyo Tech University “Club Portal” by managing club-related data. It interacts with a MariaDB database and uses Redis (likely for caching or session management). It is containerized using Docker (with additional orchestration via docker-compose) and has CI/CD workflows defined in GitHub Actions.

##### Main Components
a. API Layer:
- Represented by the router directory, this layer handles incoming HTTP requests.
- Contains submodules:
- router/auth: handles various authentication endpoints (signin, callback, signout).
- router/v1: provides versioned API endpoints for club operations (achievements, content, images, etc.) and user operations.
- router/middlewares: handles cross-cutting concerns like logging, sessions, permissions, cookie management, and parameter validation.

b. Business/Domain Layer:
- models: Contains the domain models for clubs and users (and their associated entities like pages, schedules, and multimedia assets). Models represent the structure of data used across the application.
- repos: Implements the repository pattern that abstracts away the database operations for models. It is split into separate subdirectories for admins, clubs, and users, ensuring a clear separation of concerns in data access.

c. Persistence / Database:
- MariaDB: SQL scripts in cfg/mariadb/sql show initialization of the database (with base setup, users, clubs, defaults). This is your primary persistent data storage.
- Redis: Although not explicitly present in the file tree, the README indicates Redis is used. Represent Redis as a separate component that may be used for caching or session management.

d. Configuration and Utilities:
- cfg: Contains configuration files and initial SQL setup.
- consts: Contains global constants, error definitions, and variable definitions that are used across the project.
- utils: Provides helper functions (like environment variables and validation) that support other components.
- testutil: Contains utilities for testing configurations.

e. Infrastructure & Deployment:
- Dockerfile, docker-compose.yml, and the related scripts (dev_db_setup.sh and dev_db_setup.ps1) indicate containerization and local development setup.
- GitHub workflows (in .github/workflows) handle continuous integration processes like testing, Docker image building, and documentation (using Redoc for the OpenAPI spec).
- OpenAPI spec (openapi.yaml) documents the API endpoints which can be integrated into the design.

##### Relationships and Data Flow
- Requests from external clients enter the system through the API Gateway (represented by the router layer). The requests traverse through the middlewares (authentication, logging, session handling) before reaching their respective endpoint handlers.
- Endpoint handlers coordinate with repository services (in repos) which abstract interactions with the MariaDB database.
- Business logic integrated with models ensures that data validation, transformation, and processing occurs.
- Redis is leveraged (as indicated in the README) for caching or possibly session management which sits alongside the MariaDB component.
- Docker-compose manages the orchestration of these containers (the Golang service, MariaDB, and Redis) in deployment.

##### Architectural Patterns & Design Principles
- MVC/Modular Architecture: Though not using a strict MVC framework, the separation between router (controllers), models (data representations), and repositories (data access layers) reflects clean separation of concerns.
- Repository Pattern: The use of repos to abstract data persistence.
- Containerization: Docker and docker-compose are used to facilitate environment isolation and deployment.
- CI/CD integration: GitHub workflows ensure continuous integration and automated testing.

##### Final Recommendations
- Including critical files/configurations (like openapi.yaml) in a note to reflect how the API is documented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("External Client"):::client

    subgraph "API Layer"
        APIAuth("Auth Endpoints"):::api
        APIV1("Versioned Endpoints"):::api
        APIMiddleware("Middleware Handlers"):::api
    end

    subgraph "Business/Domain Layer"
        DomainModels("Domain Models"):::business
        ModelsClubs("Models/Clubs"):::business_sub
        ModelsUsers("Models/Users"):::business_sub
        Repositories("Repositories"):::business
        ReposAdmins("Repos/Admins"):::business_sub
        ReposClubs("Repos/Clubs"):::business_sub
        ReposUsers("Repos/Users"):::business_sub
    end

    subgraph "Persistence Layer"
        MariaDB("MariaDB (SQL Scripts)"):::db
        Redis("Redis Cache"):::db
    end

    subgraph "Configuration & Utilities"
        Config("Configuration Files"):::config
        Consts("Constants & Globals"):::config
        Utils("Helper Functions & Validators"):::config
        TestUtil("Testing Utilities"):::config
    end

    subgraph "Infrastructure & Deployment"
        Docker("Docker & Containerization"):::infra
        DockerFile("Dockerfile"):::infra
        Compose("docker-compose.yml"):::infra
        SetupSh("dev_db_setup.sh"):::infra
        SetupPS("dev_db_setup.ps1"):::infra
        CICD("CI/CD Pipelines"):::infra
        GitWorkflows("GitHub Workflows"):::infra
        APIDoc("API Documentation (OpenAPI Spec)"):::infra
    end

    %% Relationships
    Client -->|"HTTP_request"| APIAuth
    Client -->|"HTTP_request"| APIV1

    APIAuth -->|"passes_to"| APIMiddleware
    APIV1 -->|"passes_to"| APIMiddleware

    APIMiddleware -->|"handles"| DomainModels

    DomainModels -->|"contains"| ModelsClubs
    DomainModels -->|"contains"| ModelsUsers

    DomainModels -->|"uses_pattern"| Repositories
    Repositories -->|"implements"| ReposAdmins
    Repositories -->|"implements"| ReposClubs
    Repositories -->|"implements"| ReposUsers

    Repositories -->|"persists_to"| MariaDB
    DomainModels -->|"caches_with"| Redis

    CICD -->|"triggers_deploy"| Docker
    Docker -->|"builds_from"| DockerFile
    Docker -->|"orchestrated_by"| Compose
    Docker -->|"setup_with"| SetupSh
    Docker -->|"setup_with"| SetupPS
    CICD -->|"runs"| GitWorkflows
    APIDoc -->|"documents"| APIAuth
    APIDoc -->|"documents"| APIV1

    %% Click Events for API Layer
    click APIAuth "https://github.com/lc-tut/club-portal/tree/dev/router/auth"
    click APIV1 "https://github.com/lc-tut/club-portal/tree/dev/router/v1"
    click APIMiddleware "https://github.com/lc-tut/club-portal/tree/dev/router/middlewares"

    %% Click Events for Business/Domain Layer
    click DomainModels "https://github.com/lc-tut/club-portal/tree/dev/models"
    click ModelsClubs "https://github.com/lc-tut/club-portal/tree/dev/models/clubs"
    click ModelsUsers "https://github.com/lc-tut/club-portal/tree/dev/models/users"
    click Repositories "https://github.com/lc-tut/club-portal/tree/dev/repos"
    click ReposAdmins "https://github.com/lc-tut/club-portal/tree/dev/repos/admins"
    click ReposClubs "https://github.com/lc-tut/club-portal/tree/dev/repos/clubs"
    click ReposUsers "https://github.com/lc-tut/club-portal/tree/dev/repos/users"

    %% Click Event for Persistence Layer
    click MariaDB "https://github.com/lc-tut/club-portal/tree/dev/cfg/mariadb/sql"

    %% Click Events for Configuration & Utilities
    click Config "https://github.com/lc-tut/club-portal/tree/dev/cfg"
    click Consts "https://github.com/lc-tut/club-portal/tree/dev/consts"
    click Utils "https://github.com/lc-tut/club-portal/tree/dev/utils"
    click TestUtil "https://github.com/lc-tut/club-portal/tree/dev/testutil"

    %% Click Events for Infrastructure & Deployment
    click DockerFile "https://github.com/lc-tut/club-portal/tree/dev/Dockerfile"
    click Compose "https://github.com/lc-tut/club-portal/blob/dev/docker-compose.yml"
    click SetupSh "https://github.com/lc-tut/club-portal/blob/dev/dev_db_setup.sh"
    click SetupPS "https://github.com/lc-tut/club-portal/blob/dev/dev_db_setup.ps1"
    click GitWorkflows "https://github.com/lc-tut/club-portal/tree/dev/.github/workflows"
    click APIDoc "https://github.com/lc-tut/club-portal/blob/dev/openapi.yaml"

    %% Styles
    classDef client fill:#FFEEAD,stroke:#000,stroke-width:2px;
    classDef api fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef business fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef business_sub fill:#E8F5E9,stroke:#1B5E20,stroke-width:1px;
    classDef db fill:#FFE0B2,stroke:#E65100,stroke-width:2px;
    classDef config fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
    classDef infra fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
```
