# onexstack/miniblog architecture

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

- Interactive diagram: https://gitdiagram.com/onexstack/miniblog
- Repository: https://github.com/onexstack/miniblog

## Overview

##### Main Components
- Client Interfaces – Represent both REST/HTTP and gRPC clients (as reflected by the “examples/client” folder, which demonstrates how to interact with endpoints for health, user, and post operations).
- API Gateway / Reverse Proxy – Although not a separate microservice, note that configuration files (e.g., the nginx reverse and load balancing configs under “configs/nginx.reverse.conf” and “configs/nginx.loadbalance.conf”) indicate that a reverse proxy or API gateway might be involved.
- The Backend Server (mb-apiserver) – This is the core executable (located under “cmd/mb-apiserver”) that handles incoming API requests. It is built with high quality; supporting both gRPC and HTTP endpoints.
- Application Layers inside the Server:
- Handlers & Controllers: Separate packages in “internal/apiserver/handler” for HTTP and gRPC that map API requests to business logic.
- Business Logic (Biz): In “internal/apiserver/biz”; includes distinct versions (v1 and v2) and contains the core application rules.
- Data Models: In “internal/apiserver/model”, which define the schema (e.g., for posts, users, casbin rules, etc.).
- Persistence / Store: The “internal/apiserver/store” package manages database interactions. The project supports both an in-memory database and MySQL (as detailed in the README and configuration files).
- Middleware & Utilities: Several internal packages (e.g., “internal/pkg/log”, “internal/pkg/errno”, “internal/pkg/middleware”, “internal/pkg/rid”) offer cross-cutting concerns such as logging, error handling, request IDs, authentication (JWT), and authorization (Casbin).

##### Relationships and Data Flows
- Clients issue API requests via either HTTP or gRPC.
- Requests are received at the mb-apiserver. Within the server, the entry point (main.go) sets up servers for both HTTP and gRPC.
- For each incoming request, the corresponding handler (HTTP or gRPC) routes the call and applies necessary middleware (for authentication, authorization, logging, etc.).
- The handler calls the appropriate business logic (biz layer) which processes the request.
- When data persistence is needed, the biz layer interacts with the store (data access layer) which uses either an in-memory data store or a configured MySQL database (with configuration specified in “configs/mb-apiserver.yaml”).
- The response is then passed back through the handler to the client.

##### Architectural Patterns & Design Principles
- Separation of Concerns: The project clearly separates concerns between API specification (OpenAPI and Swagger definitions in “api/openapi”), business logic (internal/apiserver/biz), request handling (internal/apiserver/handler), and data persistence (internal/apiserver/store).
- Layered Architecture: The distinct layers (Controller/Handler, Business Logic, Persistence) allow independent development and testing.
- Extensibility & Code Quality: Utilization of common Go packages (gorm, casbin, jwt-go, viper, zap, etc.) and code generation (evidenced by the “gen-gorm-model” command) indicate adherence to enterprise coding standards.
- Multiple Server Types: The project sets up both a gRPC server and an HTTP server (plus a possible reverse proxy) to handle different data exchange formats (Protobuf and JSON).

##### Relevant Technologies and Frameworks
- Go standard packages and project layout (conforming to the project-layout specification).
- Frameworks/Libraries: gin (for HTTP middleware and routing), grpc, gorm, casbin, jwt-go, viper, cobra, pflag, and zap.
- API Documentation: OpenAPI/Swagger definitions for API endpoint specifications.

##### Elements
- Clear Labels: Give each component a specific label (e.g., “HTTP Handler”, “gRPC Handler”, “Business Logic (Biz)”, “Data Store”).
- External components (clients, API gateway)
- Core server components (handlers, business logic, persistence)
- Utility/internal support (middleware, logging, error handling)
- Technology stacks where relevant (for instance, grouping the gRPC-related components together since they handle Protobuf transport, and likewise grouping HTTP/JSON related components).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Clients"
        CI["Client Interfaces"]:::external
    end

    subgraph "API Gateway"
        APIG["API Gateway / Reverse Proxy"]:::external
    end

    subgraph "Backend Service"
        MS["mb-apiserver"]:::server
        subgraph "Request Handlers"
            HTTP["HTTP Handlers"]:::handler
            GRPC["gRPC Handlers"]:::handler
        end
        subgraph "Middleware & Utilities"
            Mdw["Middleware (middleware)"]:::utility
            Log["Logging (log)"]:::utility
            Err["Error Handling (errno)"]:::utility
            Rid["Request ID (rid)"]:::utility
        end
        Biz["Business Logic (Biz)"]:::biz
        Model["Data Models"]:::model
        Store["Persistence / Store"]:::store
    end

    CI -->|"sendsRequest"| APIG
    APIG -->|"routesRequest"| MS
    MS -->|"HTTPRoute"| HTTP
    MS -->|"gRPCRoute"| GRPC
    HTTP -->|"usesMiddleware"| Mdw
    GRPC -->|"usesMiddleware"| Mdw
    Mdw -->|"callsBiz"| Biz
    Biz -->|"usesModel"| Model
    Biz -->|"accessesStore"| Store

    click CI "https://github.com/onexstack/miniblog/tree/master/examples/client"
    click APIG "https://github.com/onexstack/miniblog/blob/master/configs/nginx.reverse.conf"
    click APIG "https://github.com/onexstack/miniblog/blob/master/configs/nginx.loadbalance.conf"
    click MS "https://github.com/onexstack/miniblog/tree/master/cmd/mb-apiserver"
    click HTTP "https://github.com/onexstack/miniblog/tree/master/internal/apiserver/handler/http"
    click GRPC "https://github.com/onexstack/miniblog/tree/master/internal/apiserver/handler/grpc"
    click Biz "https://github.com/onexstack/miniblog/tree/master/internal/apiserver/biz"
    click Model "https://github.com/onexstack/miniblog/tree/master/internal/apiserver/model"
    click Store "https://github.com/onexstack/miniblog/tree/master/internal/apiserver/store"
    click Mdw "https://github.com/onexstack/miniblog/tree/master/internal/pkg/middleware"
    click Log "https://github.com/onexstack/miniblog/tree/master/internal/pkg/log"
    click Err "https://github.com/onexstack/miniblog/tree/master/internal/pkg/errno"
    click Rid "https://github.com/onexstack/miniblog/tree/master/internal/pkg/rid"

    classDef external fill:#bbf,stroke:#f66,stroke-width:2px;
    classDef server fill:#fdd,stroke:#d55,stroke-width:2px;
    classDef handler fill:#dfd,stroke:#393,stroke-width:2px;
    classDef biz fill:#ffd,stroke:#aa0,stroke-width:2px;
    classDef model fill:#f9f,stroke:#596,stroke-width:2px;
    classDef store fill:#fee,stroke:#e83,stroke-width:2px;
    classDef utility fill:#cee,stroke:#3a3,stroke-width:2px;
```
