# zsy619/yyhertz architecture

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

- Interactive diagram: https://gitdiagram.com/zsy619/yyhertz
- Repository: https://github.com/zsy619/yyhertz

## Overview

##### Project Type and Purpose
- This is an open-source Go Web framework (YYHertz) built on CloudWeGo-Hertz.
- It provides a Beego-style MVC layer, pluggable middleware, dual ORM (GORM + MyBatis) engine, configuration management, template engine, code-generation tools, and examples.

##### File Structure Analysis
- Top-level:
- `framework/` – core modules (mvc, orm, mybatis, config, util, testing, version, cache, scheduler, etc.)
- `example/` – sample applications demonstrating MVC, annotations, ORM, WebSocket, tools.
- `cmd/` – CLI for codegen tasks.
- `conf/` – YAML configuration files.
- `docs/` – user guides, optimization notes, algorithm references.
- `static/` – static assets for WebSocket tests.
- MVC subdirectories mirror the typical layering: context, controller, router, middleware, view, annotation, error handling, devtools, websocket.
- ORM (`framework/orm`) implements a manager + selector + engine plugins.
- MyBatis (`framework/mybatis`) implements XML parser, session/executor, plugin hooks.
- Configuration (`framework/config`) loads YAML via Viper, exposes typed configs (app, log, database, session, TLS, etc.).
- Build scripts and go.mod tie everything together.

##### README Insights
- Emphasizes MVC architecture, middleware pipeline (4 layers), Beego compatibility, auto-routing, health checks.
- Dual-engine ORM architecture: `ORMManager → SmartSelector → {GORM engine, MyBatis engine} → RDBMS`.
- High performance goals (Hertz HTTP server), production-ready features (error handling, graceful shutdown, metrics).
- Example usage of controllers, namespaces, middleware, ORM operations, and custom XML mappers.

##### Essential Details to Capture
- Distinct boundaries between **user code** and **framework internals**.
- The **middleware pipeline** order and how it composes.
- The **dual-engine ORM flow**, including the SmartSelector decision point.
- Configuration sources (`conf/*.yaml`) feeding into the Config Manager at startup.
- How **templates**, **static assets**, and **WebSocket utils** plug into the MVC core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Application
    subgraph "User Application Layer"
        Examples["User Application Layer\n(example/)"]:::external
    end

    %% Framework Core
    subgraph "Framework Core"
        HTTPServer["HTTP Server\n(CloudWeGo-Hertz)"]:::requestPath
        MiddlewarePipeline["Middleware Pipeline"]:::utilities
        Router["Router & Namespace"]:::requestPath
        Context["Context & Lifecycle"]:::requestPath
        Controller["Controller Dispatch & Core Logic"]:::requestPath
        View["View / Template Engine"]:::requestPath
        WebSocket["WebSocket Utilities"]:::requestPath
        ConfigManager["Configuration Manager\n(Viper, YAML)"]:::config
        DevTools["DevTools\n(Logging, Error Handling,\nHealth Check, Profiler)"]:::utilities
        Utilities["Utilities\n(ID, crypto, network,\nvalidation, etc.)"]:::utilities
        Version["Versioning"]:::utilities
    end

    %% ORM & Data
    subgraph "ORM Layer & Data Stores"
        ORMManager["ORM Manager & SmartSelector"]:::dataAccess
        GORM["GORM Engine Plugin"]:::dataAccess
        MyBatis["MyBatis Engine Plugin"]:::dataAccess
        Cache["Cache Subsystem"]:::dataAccess
    end

    %% Tools & Tasks
    subgraph "Tools"
        Scheduler["Scheduler"]:::utilities
        CodegenCLI["CodeGen CLI (cmd)"]:::utilities
        Examples
    end

    %% External Systems
    subgraph "External Systems"
        DB["Relational DBs\n(MySQL, PostgreSQL,\nSQLite, SQLServer, Oracle)"]:::external
        Redis["Redis"]:::external
        TLS["TLS"]:::external
        Static["Static Assets"]:::external
    end

    %% Request Flow
    Examples -->|"HTTP Request"| HTTPServer
    HTTPServer -->|"pass request"| MiddlewarePipeline
    MiddlewarePipeline -->|"route matching"| Router
    Router -->|"build context"| Context
    Context -->|"invoke"| Controller
    Controller -->|"render"| View
    Controller -->|"ws ops"| WebSocket
    Controller -->|"data access"| ORMManager
    HTTPServer -->|"serve static"| Static
    HTTPServer -->|"TLS termination"| TLS

    %% ORM Flow
    ORMManager -->|"select engine"| GORM
    ORMManager -->|"select engine"| MyBatis
    GORM -->|"SQL Query"| DB
    MyBatis -->|"SQL Query"| DB
    ORMManager -->|"cache read/write"| Cache
    Cache -->|"cache store"| Redis

    %% Configuration & Control Flow
    ConfigManager -.->|inject settings| HTTPServer
    ConfigManager -.->|inject settings| MiddlewarePipeline
    ConfigManager -.->|inject settings| ORMManager
    ConfigManager -.->|inject settings| DevTools

    DevTools -.->|hooks| HTTPServer
    Scheduler -.->|jobs| DevTools
    Utilities -.->|helpers| MiddlewarePipeline
    Utilities -.->|helpers| Controller
    Version -.->|metadata| HTTPServer

    %% Tools & Codegen
    CodegenCLI -.->|generate code| Examples

    %% Click Events
    click HTTPServer "https://github.com/zsy619/yyhertz/tree/main/framework/gin"
    click MVCCore "https://github.com/zsy619/yyhertz/tree/main/framework/mvc"
    click Router "https://github.com/zsy619/yyhertz/tree/main/framework/mvc/router"
    click Context "https://github.com/zsy619/yyhertz/tree/main/framework/mvc/context"
    click Controller "https://github.com/zsy619/yyhertz/blob/main/framework/mvc/controller.go"
    click View "https://github.com/zsy619/yyhertz/tree/main/framework/mvc/view"
    click WebSocket "https://github.com/zsy619/yyhertz/blob/main/framework/mvc/websocket_utils.go"
    click MiddlewarePipeline "https://github.com/zsy619/yyhertz/tree/main/framework/mvc/middleware"
    click ConfigManager "https://github.com/zsy619/yyhertz/tree/main/framework/config"
    click DevTools "https://github.com/zsy619/yyhertz/tree/main/framework/mvc/devtools"
    click Utilities "https://github.com/zsy619/yyhertz/tree/main/framework/util"
    click ORMManager "https://github.com/zsy619/yyhertz/tree/main/framework/orm"
    click MyBatis "https://github.com/zsy619/yyhertz/tree/main/framework/mybatis"
    click Cache "https://github.com/zsy619/yyhertz/tree/main/framework/cache"
    click Scheduler "https://github.com/zsy619/yyhertz/tree/main/framework/scheduler"
    click CodegenCLI "https://github.com/zsy619/yyhertz/tree/main/cmd/codegen"
    click Examples "https://github.com/zsy619/yyhertz/tree/main/example/"
    click Static "https://github.com/zsy619/yyhertz/tree/main/static/"
    click Version "https://github.com/zsy619/yyhertz/tree/main/framework/version"

    %% Styles
    classDef requestPath fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef dataAccess fill:#d4edda,stroke:#28a745,color:#000;
    classDef utilities fill:#fff3cd,stroke:#ffc107,color:#000;
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#000;
    classDef external fill:#f8d7da,stroke:#dc3545,color:#000;
```
