How lc-tut/club-portal works
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.