# eryajf/xirang architecture

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

- Interactive diagram: https://gitdiagram.com/eryajf/xirang
- Repository: https://github.com/eryajf/xirang

## Overview

##### Project type and purpose
- This is a Go-based backend web framework and reference implementation (“xirang”) built on Gin (HTTP server) and Gorm (ORM).
- It provides a template for building RESTful APIs with ready-made layers (config, middleware, routers, controllers, business logic, services, models) and common utilities.

##### File structure
- Top-level files:
- main.go (entry point)
- config.yml (runtime configuration)
- Dockerfile, Makefile (build & deployment)
- Directories:
- config: loads & parses config.yml
- public: shared utilities (logging, DB init, validators, crypto, HTTP tools)
- middleware: Gin middleware (auth, CORS, rate limiting, Casbin, operation logging)
- routes: maps HTTP paths to controllers
- controller: HTTP handlers that decode requests, call logic, return responses
- logic: orchestrates business rules, validation, calls services
- service: provides fine-grained operations (e.g., CRUD, transactions)
- model: data definitions (Gorm models, request/response DTOs)
- test: unit/integration tests

##### README for additional insights
- Emphasizes simplicity: change config.yml, spin up Gin+Gorm
- No external microservices; supports MySQL or SQLite
- Ready-made RBAC (Casbin), logging, operation log, request rate limiting

##### Main components & their relationships
a. Client (Frontend or API consumer)
b. HTTP Server Layer (Gin Engine)
- Loads config (config package)
- Initializes global components (DB connection via Gorm, logger, Casbin enforcer, rate limiter)
c. Middleware Chain
- Global middleware applied to Gin: CORS, Auth, Casbin, RateLimit, OperationLog
d. Router Layer
- Binds URL paths to controller methods
e. Controller Layer
- Parses HTTP requests into DTOs (model/*/request)
- Invokes corresponding Logic
- Returns responses (model/*/response)
f. Logic Layer
- Implements business workflows
- Calls Service layer for data persistence or external calls
g. Service Layer
- Encapsulates data access, transaction control, calls to Gorm models
h. Model Layer
- Gorm model structs, ORM mapping to DB tables
i. Database
- MySQL or SQLite (configured in config.yml)

##### Architectural patterns & design principles
- Layered architecture (Controller → Logic → Service → Model → DB)
- Separation of concerns: routing, request handling, business logic, persistence
- Use of Gin middleware for cross-cutting concerns (auth, logging, rate limiting, RBAC)
- DTOs for request/response to decouple API schema from ORM models
- Config-driven initialization for pluggable components (DB, logger, Casbin)
- Testability: clear boundaries allow unit/integration tests in test/

##### Essential elements
- Clear labels for each component (e.g., “AuthMiddleware”, “system_user_controller”)
- Database symbol for MySQL/SQLite

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Initialization Sequence
    subgraph "Configuration & Initialization"
        direction TB
        LoadConfig["Load config (Viper)"]:::util
        DBInit["Init DB Connection (Gorm)"]:::util
        LoggerInit["Init Logger"]:::util
        CasbinInit["Init Casbin Enforcer"]:::util
        MountMiddleware["Mount Middleware"]:::util
        MountRoutes["Mount Routes"]:::util
        StartServer["Start Gin Server"]:::util
    end

    %% Main Request Flow
    Client["Client (Browser/API)"]:::api
    Main["HTTP Server Entry Point (main.go)"]:::api
    GinEngine["Gin Engine"]:::api
    subgraph "Middleware Chain" 
        direction TB
        Auth["AuthMiddleware"]:::api
        CORS["CORSMiddleware"]:::api
        CasbinMW["CasbinMiddleware"]:::api
        RateLimit["RateLimitMiddleware"]:::api
        OpLog["OperationLogMiddleware"]:::api
    end
    Router["Router Layer"]:::api
    subgraph "Controller Layer"
        direction TB
        CtrlEnter["a_enter.go"]:::logic
        SysCtrl["System Controllers"]:::logic
        ExCtrl["Example Controller"]:::logic
    end
    subgraph "Logic Layer"
        direction TB
        LogicEnter["a_enter.go"]:::logic
        SysLogic["System Logic"]:::logic
        ExLogic["Example Logic"]:::logic
    end
    subgraph "Service Layer"
        direction TB
        ServiceEnter["a_enter.go"]:::logic
        SysService["System Services"]:::logic
        ExService["Example Service"]:::logic
    end
    subgraph "Model Layer"
        direction TB
        Models["ORM Models & DTOs"]:::data
    end
    DB["Database (MySQL/SQLite)"]:::data

    %% Shared Utilities
    subgraph "Shared Utilities" 
        direction TB
        DBUtil["database.go"]:::util
        LoggerUtil["logger.go"]:::util
        ValidatorUtil["validator.go"]:::util
        CasbinUtil["casbin.go"]:::util
        InitMySQLData["init_mysql_data.go"]:::util
    end

    subgraph "Tools"
        direction TB
        HTTPTool["http.go"]:::util
        HTTPDo["http_doreq.go"]:::util
        JSONTool["json.go"]:::util
        RSA["rsa.go"]:::util
        Bcrypt["bcrypt_passwd.go"]:::util
        WebTool["web.go"]:::util
    end

    %% Init Flow Connections
    LoadConfig --> DBInit --> LoggerInit --> CasbinInit --> MountMiddleware --> MountRoutes --> StartServer

    %% Request Flow Connections
    Client --> Main --> GinEngine --> Auth --> CORS --> CasbinMW --> RateLimit --> OpLog --> Router
    Router --> CtrlEnter --> SysCtrl --> ExCtrl
    ExCtrl --> LogicEnter --> SysLogic --> ExLogic
    ExLogic --> ServiceEnter --> SysService --> ExService
    ExService --> Models --> DB

    %% Click Events
    click Main "https://github.com/eryajf/xirang/blob/main/main.go"
    click LoadConfig "https://github.com/eryajf/xirang/blob/main/config/config.go"
    click DBUtil "https://github.com/eryajf/xirang/blob/main/public/common/database.go"
    click LoggerUtil "https://github.com/eryajf/xirang/blob/main/public/common/logger.go"
    click ValidatorUtil "https://github.com/eryajf/xirang/blob/main/public/common/validator.go"
    click CasbinUtil "https://github.com/eryajf/xirang/blob/main/public/common/casbin.go"
    click InitMySQLData "https://github.com/eryajf/xirang/blob/main/public/common/init_mysql_data.go"
    click HTTPTool "https://github.com/eryajf/xirang/blob/main/public/tools/http.go"
    click HTTPDo "https://github.com/eryajf/xirang/blob/main/public/tools/http_doreq.go"
    click JSONTool "https://github.com/eryajf/xirang/blob/main/public/tools/json.go"
    click RSA "https://github.com/eryajf/xirang/blob/main/public/tools/rsa.go"
    click Bcrypt "https://github.com/eryajf/xirang/blob/main/public/tools/bcrypt_passwd.go"
    click WebTool "https://github.com/eryajf/xirang/blob/main/public/tools/web.go"
    click Auth "https://github.com/eryajf/xirang/blob/main/middleware/AuthMiddleware.go"
    click CORS "https://github.com/eryajf/xirang/blob/main/middleware/CORSMiddleware.go"
    click CasbinMW "https://github.com/eryajf/xirang/blob/main/middleware/CasbinMiddleware.go"
    click RateLimit "https://github.com/eryajf/xirang/blob/main/middleware/RateLimitMiddleware.go"
    click OpLog "https://github.com/eryajf/xirang/blob/main/middleware/OperationLogMiddleware.go"
    click Router "https://github.com/eryajf/xirang/blob/main/routes/a_enter.go"
    click SysCtrl "https://github.com/eryajf/xirang/blob/main/controller/system/system_user_controller.go"
    click ExCtrl "https://github.com/eryajf/xirang/blob/main/controller/example/example_cloud_account_controller.go"
    click CtrlEnter "https://github.com/eryajf/xirang/blob/main/controller/a_enter.go"
    click LogicEnter "https://github.com/eryajf/xirang/blob/main/logic/a_enter.go"
    click SysLogic "https://github.com/eryajf/xirang/blob/main/logic/system/system_user_logic.go"
    click ExLogic "https://github.com/eryajf/xirang/blob/main/logic/example/example_cloud_account_logic.go"
    click ServiceEnter "https://github.com/eryajf/xirang/blob/main/service/a_enter.go"
    click SysService "https://github.com/eryajf/xirang/blob/main/service/system/system_user_service.go"
    click ExService "https://github.com/eryajf/xirang/blob/main/service/example/example_cloud_account_service.go.go"

    %% Styles
    classDef api fill:#cce5ff,stroke:#004085,color:#004085;
    classDef logic fill:#d4edda,stroke:#155724,color:#155724;
    classDef data fill:#ffe5b4,stroke:#e07a00,color:#e07a00;
    classDef util fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
