# sjtu-jcourse/jcourse_go architecture

> Architecture diagram of the GitHub repository sjtu-jcourse/jcourse_go, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sjtu-jcourse/jcourse_go
- Repository: https://github.com/sjtu-jcourse/jcourse_go

## Overview

##### Project Type and Purpose
- Project Type: Backend service for a course/community platform.
- Purpose: Provide RESTful APIs for course management, user authentication, course reviews, ratings, teacher information, and asynchronous tasks like statistics and distributed locking.
- It supports database migration and data import capabilities (as seen in the cmd subfolders like migrate and import_from_jwc) and is designed to run as a single backend binary.

##### File Structure
- Top-Level Directories:
- cmd: Contains multiple executable commands (e.g., code generation, migration, refreshing database, various importers). This indicates that the project uses a modular approach with different entry points for different tasks.
- constant: Houses constant definitions (configured for authentication, email, query handling, etc.), which centralizes configuration strings.
- dal: Database abstraction layer for interfacing with SQL and Redis.
- handler: HTTP request handlers that serve as the API endpoints. They call into business logic without containing the logic themselves.
- middleware: Contains components for HTTP middleware like authentication, CSRF, session management, and statistics collection.
- model: Organized into subdirectories for data transfer objects (dto), persistent objects (po), domain-specific models (if present), and converters. This separation hints an MVC/MV* style architecture for clean separation of concerns.
- repository: Implements the abstracted data access querying logic, isolating business logic from storage details.
- rpc: Provides modules for external communication (e.g., LLM and SMTP service invocation).
- service: Contains the actual business logic implementations that put together multiple domain operations.
- task: Implements asynchronous tasks. There is evidence of multiple submodules such as one using "asynq" for distributed task processing and another for business tasks such as ping and statistics. These tasks operate independently from the regular request handling.
- util: Houses helper and utility functions for various general-purpose tasks (e.g., conversion, environment parsing, error handling, time utilities, and even Selenium integration for data loading).
- Supporting Files:
- Configuration and build files (Makefile, Dockerfile, docker-compose.yml, .env instructions, etc.) indicate deployment and dependency management.
- .github/workflows suggest CI/CD integration for Golang builds and lint checks.

##### Key Elements
a. Main Components:
- API Layer: Handler components (handler/…) handling HTTP requests.
- Middleware: Components that manage security and session state (middleware/…).
- Business Logic Layer: Service modules (service/…) implementing core functions.
- Data Access Layer: Repository (repository/…), DAL (dal/…), and model definitions (model/).
- Asynchronous Task Processing: Task components (task/asynq, task/base, task/biz) managing background jobs.
- External Integrations: RPC modules (rpc/llm, rpc/smtp) to communicate with external services.
- Command-Line Utilities: Executables in cmd (e.g., migrate, importers) which are used for database initialization, data imports, and code generation.
- Infrastructure: Database systems (Postgres, Vector DB) and Redis as indicated by the configuration in the README.

b. Relationships and Interactions:
- Incoming HTTP requests hit the API layer (handled by the “handler” packages). They pass through a chain of middleware components (authentication, CSRF, session, statistics, etc.) before reaching the business logic.
- The service layer orchestrates business operations, relying on the repository layer to interact with the underlying databases.
- DAL provides abstraction over different types of databases (SQL and Redis) while models (dto, po, converter) define the data structures shared between layers.
- Asynchronous tasks are triggered by events in the service layer or via external scheduling. They run independently to perform background work like statistical computations or distributed locking.
- RPC modules allow communication with systems like language processing services (LLM) or sending emails (SMTP).
- Command-line executables serve as one-off utilities for migrations, imports, and refresh operations.

c. Architectural Patterns and Design Principles:
- Layered Architecture: Clear separation between presentation (handlers), business (services), and data access (dal/repository).
- Separation of Concerns: Task handling and command-line utilities are separated from the main API server logic.
- Modularity: Multiple “cmd” executables indicate a separation of responsibilities.
- Dependency Injection & Abstraction: Repository and service layers abstract underlying DB access, making the system more maintainable and testable.
- Asynchronous Task Processing: Use of “asynq” framework for handling distributed tasks.

d. Relevant Technologies and Frameworks:
- Golang (>=1.21) for its strong concurrency support.
- PostgreSQL (and a distinct VectorDB instance) as the primary data store.
- Redis for caching and possibly for session storage.
- Docker and docker-compose for containerized deployment.
- CI tools defined in the GitHub workflows (linting, Go testing, etc.).
- Asynq for distributed task processing.
- Selenium scripts (in util/selenium-get) for data imports or scraping operations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    Client["Client"]:::support

    %% Presentation Layer
    subgraph "Presentation Layer"
        API["HTTP Handlers"]:::presentation
        MW["Middleware (Auth,CSRF,Session,Statistic)"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        SV["Services (Business Logic)"]:::business
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        REP["Repository"]:::data
        DAL["DAL (SQL/Redis)"]:::data
        DM["Data Models"]:::data
    end

    %% Asynchronous Task Processor
    TASK["Asynchronous Tasks (Asynq)"]:::async

    %% External Integrations
    RPC["RPC Modules (LLM,SMTP)"]:::external

    %% Command-Line Utilities
    CMD["Command-Line Utilities"]:::cli

    %% Infrastructure
    subgraph "Infrastructure"
        DB["Database (PostgreSQL/VectorDB)"]:::database
        CACHE["Cache (Redis)"]:::cache
    end

    %% Support Components
    subgraph "Support Components"
        CONST["Constants"]:::support
        UTIL["Utilities"]:::support
    end

    %% Connections
    Client -->|"req"| API
    API -->|"passes"| MW
    MW -->|"calls"| SV
    SV -->|"queries"| REP
    SV -->|"uses"| DAL
    REP -->|"SQL queries"| DB
    DAL -->|"SQL ops"| DB
    DAL -->|"cache ops"| CACHE
    SV -->|"externalCall"| RPC
    SV -->|"triggersAsync"| TASK
    TASK -->|"callback"| SV
    CMD -->|"dbMigration"| DB
    CMD -->|"cacheRefresh"| CACHE
    CONST ---|"config support"| SV
    UTIL ---|"helper functions"| SV

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef business fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef data fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef async fill:#F5CBA7,stroke:#CB4335,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef cli fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef support fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef database fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef cache fill:#FDEDEC,stroke:#CB4335,stroke-width:2px;

    %% Click Events
    click API "https://github.com/sjtu-jcourse/jcourse_go/tree/main/handler/"
    click MW "https://github.com/sjtu-jcourse/jcourse_go/tree/main/middleware/"
    click CMD "https://github.com/sjtu-jcourse/jcourse_go/tree/main/cmd/"
    click SV "https://github.com/sjtu-jcourse/jcourse_go/tree/main/service/"
    click DAL "https://github.com/sjtu-jcourse/jcourse_go/tree/main/dal/"
    click REP "https://github.com/sjtu-jcourse/jcourse_go/tree/main/repository/"
    click DM "https://github.com/sjtu-jcourse/jcourse_go/tree/main/model/"
    click TASK "https://github.com/sjtu-jcourse/jcourse_go/tree/main/task/"
    click RPC "https://github.com/sjtu-jcourse/jcourse_go/tree/main/rpc/"
    click UTIL "https://github.com/sjtu-jcourse/jcourse_go/tree/main/util/"
    click CONST "https://github.com/sjtu-jcourse/jcourse_go/tree/main/constant/"
```
