# wangyi1310/occrq-disk architecture

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

- Interactive diagram: https://gitdiagram.com/wangyi1310/occrq-disk
- Repository: https://github.com/wangyi1310/occrq-disk

## Overview

##### Main Components
- Client Interface: Represented by the static files (HTML, CSS, JS) under the static directory. This is the front-end side that interacts with users.
- Application Initialization: The bootstrap module (files in the bootstrap/ directory) that handles the app startup and update checking.
- Configuration Management: The conf/ directory holds configuration logic (parsing, default values, versioning).
- Models/Database Layer: Found in the models/ directory. It contains definitions for files, folders, users, migrations, and includes methods to initialize the database (supporting SQLite and MySQL).
- Middleware: Contains common logic for things like authentication (middleware/ folder) that wraps route handlers.
- Routing & Controllers: The routers/ directory (with controllers subdirectory) organizes the HTTP routes and links them with business logic.
- Business Services: For example, services/user.go contains core business logic related to user operations.
- Utility Packages: In the pkg/ directory there are modules for authentication, caching, emailing, logging, request handling, session management, and utility functions. These are cross-cutting concerns that support the main application.
- Serialization: The serializer/ directory handles transforming responses and errors into a structured format for client consumption.
- External Services: There are integrations for emailing (connects to an SMTP server), caching (redis support in pkg/cache), and GitHub for update checking (in bootstrap).

##### Component Relationships
- The User's browser requests static content (from the static/ directory) and API calls.
- HTTP requests go into the router (routers/router.go), which in turn delegates to specific controllers (in routers/controllers/).
- Controllers may:
- Validate requests using middleware (middleware/auth.go and middleware/common.go).
- Leverage services (e.g., services/user.go) for business logic.
- Utilize serializers to build responses.
- Controllers and services interact with the models (models/) to perform database operations. The models incorporate connection logic (choosing between SQLite and MySQL) as configured in conf/.
- Bootstrap sets the stage by initializing the application and invoking configuration checks, including update and version management.
- Utility packages (pkg/) provide support functionalities like:
- pkg/log – for logging.
- pkg/auth – to validate user sessions.
- pkg/cache – to manage in-memory or Redis-based caching.
- pkg/email – to send notifications.
- pkg/request and pkg/session – for handling HTTP request details and session storage.
- Dockerfile and CI/CD configuration (.github/workflows files) indicate that the project can be containerized and is built with continuous integration practices.

##### Architectural Patterns and Design Principles
- Separation of concerns: Each directory (bootstrap, conf, models, routers, middleware, pkg, serializer) encapsulates distinct responsibilities such as configuration, business logic, or utilities.
- Modular design: Use of Go modules and subpackages in pkg/ to promote code reuse.
- MVC-like structure: Routers and controllers handle incoming requests, models interact with the database, and serializers format data for the client.
- Extensibility: The design supports multiple database types and includes pluggable components (cache drivers, email configurations, etc.).
- Integration with external services (such as GitHub for version checking and emailing systems) is clearly delineated.

##### Final Suggestions
- Be as detailed as possible—don’t hesitate to break down complex components into sub-components, such as splitting utility services individually.
- Clearly demarcate layers (Presentation, Business, Data, Infrastructure) to illustrate separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Client["Client (Web Browser)"]:::frontend
        LB["Load Balancer/Router"]:::backend
        Static["Static Content Server"]:::frontend
    end

    Client -->|"HTTP_Requests"| LB
    LB -->|"Static_Files"| Static
    LB -->|"API_Calls"| BootstrapApp

    %% Application Layer
    subgraph "Application Layer"
        %% Initialization Subgraph
        subgraph "Initialization"
            BootstrapApp["Bootstrap: App Initialization"]:::backend
            BootstrapInit["Bootstrap: Init Routine"]:::backend
        end

        %% Configuration Subgraph
        subgraph "Configuration"
            ConfigParsing["Config Parsing (conf/conf.go)"]:::backend
            ConfigDefaults["Default Config (conf/defaults.go)"]:::backend
            ConfigVersion["Versioning (conf/version.go)"]:::backend
        end

        %% Middleware Subgraph
        subgraph "Middleware"
            MiddlewareAuth["Auth Middleware (middleware/auth.go)"]:::backend
            MiddlewareCommon["Common Middleware (middleware/common.go)"]:::backend
        end

        %% Routing & Controllers Subgraph
        subgraph "Routing & Controllers"
            Router["Router (routers/router.go)"]:::backend
            ControllerBase["Base Controller (routers/controllers/base.go)"]:::backend
            ControllerSite["Site Controller (routers/controllers/site.go)"]:::backend
            ControllerUser["User Controller (routers/controllers/user.go)"]:::backend
        end

        BusinessService["User Service (services/user.go)"]:::backend

        %% Serialization Subgraph
        subgraph "Serialization"
            SerializerAuth["Auth Serializer (serializer/auth.go)"]:::backend
            SerializerError["Error Serializer (serializer/error.go)"]:::backend
            SerializerResponse["Response Serializer (serializer/response.go)"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        subgraph "Models"
            FileModel["File Model (models/file.go)"]:::data
            FolderModel["Folder Model (models/folder.go)"]:::data
            UserModel["User Model (models/user.go)"]:::data
            DBInit["DB Initializer (models/init.go)"]:::data
            Migration["Migration (models/migration.go)"]:::data
        end
        Database["Database (SQLite/MySQL)"]:::database
    end

    %% Utility Packages
    subgraph "Utility Packages"
        UtilityAuth["pkg/auth"]:::utility
        UtilityCache["pkg/cache"]:::utility
        UtilityEmail["pkg/email"]:::utility
        UtilityLog["pkg/log"]:::utility
        UtilityRequest["pkg/request"]:::utility
        UtilitySession["pkg/session"]:::utility
        UtilityUtil["pkg/util"]:::utility
    end

    %% External Services
    subgraph "External Services"
        GitHub["GitHub Update Checker"]:::external
        EmailService["External Email Service (SMTP)"]:::external
    end

    Deployment["Deployment (Docker & CI/CD)"]:::external

    %% Connections within Application Layer
    BootstrapApp -->|"init_config"| ConfigParsing
    BootstrapInit -->|"init_config"| ConfigParsing
    ConfigParsing -->|"set_defaults"| ConfigDefaults
    ConfigDefaults -->|"load_version"| ConfigVersion
    ConfigVersion -->|"init_middleware"| MiddlewareAuth
    MiddlewareAuth -->|"chain"| MiddlewareCommon
    MiddlewareCommon -->|"route_requests"| Router
    Router -->|"to_base"| ControllerBase
    Router -->|"to_site"| ControllerSite
    Router -->|"to_user"| ControllerUser
    ControllerUser -->|"business_logic"| BusinessService
    BusinessService -->|"serialize_auth"| SerializerAuth
    BusinessService -->|"serialize_error"| SerializerError
    BusinessService -->|"serialize_response"| SerializerResponse

    %% Connections between Controllers and Models
    ControllerUser -->|"file_op"| FileModel
    ControllerUser -->|"folder_op"| FolderModel
    ControllerUser -->|"user_op"| UserModel

    FileModel -->|"init_db"| DBInit
    FolderModel -->|"init_db"| DBInit
    UserModel -->|"init_db"| DBInit
    DBInit -->|"migration"| Migration
    Migration -->|"connect_db"| Database

    %% Utility Package Connections
    BusinessService -->|"util_log"| UtilityLog
    BusinessService -->|"util_cache"| UtilityCache
    BusinessService -->|"util_email"| UtilityEmail
    BusinessService -->|"util_session"| UtilitySession
    BusinessService -->|"util_util"| UtilityUtil
    MiddlewareAuth -->|"util_auth"| UtilityAuth
    Router -->|"util_request"| UtilityRequest
    UtilityEmail -->|"smtp_connect"| EmailService

    %% External and Deployment Connections
    BootstrapApp -->|"check_updates"| GitHub
    Deployment -->|"deployed_as"| LB

    %% Click Events
    click Client "https://github.com/wangyi1310/occrq-disk/tree/main/static/"
    click BootstrapApp "https://github.com/wangyi1310/occrq-disk/blob/main/bootstrap/app.go"
    click BootstrapInit "https://github.com/wangyi1310/occrq-disk/blob/main/bootstrap/init.go"
    click ConfigParsing "https://github.com/wangyi1310/occrq-disk/blob/main/conf/conf.go"
    click ConfigDefaults "https://github.com/wangyi1310/occrq-disk/blob/main/conf/defaults.go"
    click ConfigVersion "https://github.com/wangyi1310/occrq-disk/blob/main/conf/version.go"
    click MiddlewareAuth "https://github.com/wangyi1310/occrq-disk/blob/main/middleware/auth.go"
    click MiddlewareCommon "https://github.com/wangyi1310/occrq-disk/blob/main/middleware/common.go"
    click Router "https://github.com/wangyi1310/occrq-disk/blob/main/routers/router.go"
    click ControllerBase "https://github.com/wangyi1310/occrq-disk/blob/main/routers/controllers/base.go"
    click ControllerSite "https://github.com/wangyi1310/occrq-disk/blob/main/routers/controllers/site.go"
    click ControllerUser "https://github.com/wangyi1310/occrq-disk/blob/main/routers/controllers/user.go"
    click BusinessService "https://github.com/wangyi1310/occrq-disk/blob/main/services/user.go"
    click FileModel "https://github.com/wangyi1310/occrq-disk/blob/main/models/file.go"
    click FolderModel "https://github.com/wangyi1310/occrq-disk/blob/main/models/folder.go"
    click UserModel "https://github.com/wangyi1310/occrq-disk/blob/main/models/user.go"
    click DBInit "https://github.com/wangyi1310/occrq-disk/blob/main/models/init.go"
    click Migration "https://github.com/wangyi1310/occrq-disk/blob/main/models/migration.go"
    click UtilityAuth "https://github.com/wangyi1310/occrq-disk/tree/main/pkg/auth/"
    click UtilityCache "https://github.com/wangyi1310/occrq-disk/tree/main/pkg/cache/"
    click UtilityEmail "https://github.com/wangyi1310/occrq-disk/tree/main/pkg/email/"
    click UtilityLog "https://github.com/wangyi1310/occrq-disk/tree/main/pkg/log/"
    click UtilityRequest "https://github.com/wangyi1310/occrq-disk/tree/main/pkg/request/"
    click UtilitySession "https://github.com/wangyi1310/occrq-disk/tree/main/pkg/session/"
    click UtilityUtil "https://github.com/wangyi1310/occrq-disk/tree/main/pkg/util/"
    click SerializerAuth "https://github.com/wangyi1310/occrq-disk/blob/main/serializer/auth.go"
    click SerializerError "https://github.com/wangyi1310/occrq-disk/blob/main/serializer/error.go"
    click SerializerResponse "https://github.com/wangyi1310/occrq-disk/blob/main/serializer/response.go"

    %% Styles
    classDef frontend fill:#f9f,stroke:#333,stroke-width:2px;
    classDef backend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef data fill:#cfc,stroke:#333,stroke-width:2px;
    classDef utility fill:#ffc,stroke:#333,stroke-width:2px;
    classDef external fill:#fc9,stroke:#333,stroke-width:2px;
    classDef database fill:#cff,stroke:#333,stroke-width:2px;
```
