# raahii/golang-grpc-realworld-example architecture

> Architecture diagram of the GitHub repository raahii/golang-grpc-realworld-example, 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/raahii/golang-grpc-realworld-example
- Repository: https://github.com/raahii/golang-grpc-realworld-example

## Overview

##### Project Type and Purpose
- The project is a full-stack backend application written in Go that uses GRPC for internal communication and a grpc-gateway as a reverse proxy to translate RESTful requests to GRPC.
- It implements the RealWorld spec with CRUD operations, user authentication (via JWT), and typical content management features (articles, profiles, comments, favorites).

##### Break Down the File Structure into Main Components
- API Gateway:
- Directory: “gateway”
- File: gateway/gateway.go
- Function: Acts as a reverse proxy, translating RESTful JSON API calls into gRPC requests.
- GRPC Server:
- File: server.go
- Core business logic and gRPC service implementation.
- Request Handlers:
- Directory: “handler”
- Files: handler/*.go (article, comment, profile, user, etc.)
- Role: Layer to interpret incoming requests (from GRPC or REST gateway) and route them to service logic.
- Authentication:
- Directory: “auth”
- File: auth/auth.go
- Provides JWT-based authentication.
- Database and Storage:
- Directories: “db” (with subdirectories for data and seed) and “store”
- Files: db/db.go, db/seed/seed.go, and store files (article.go, user.go)
- Role: Manages database connectivity, ORM (using GORM) for persistence into MySQL.
- Business Models:
- Directory: “model”
- Files: model/*.go (article, comment, user)
- Represents data objects that the system manipulates.
- Protobuf Definitions:
- Directory: “proto”
- Files: *.proto and their generated Go files.
- Role: Defines the gRPC contracts and message formats used for inter-service communication.
- Auxiliary Components:
- Dockerfile, docker-compose.yml, Makefile, and environment files under “env”
- Provide containerization, build, testing, and deployment scripts.

##### Architectural Patterns and Design Principles
- Clearly denote the separation of concerns:
- API Layer (REST gateway) vs. Business Logic (gRPC server and handlers)
- Data access (store and database modules)
- Domain Models (model objects)
- From external client → API Gateway (REST request) → Internal GRPC request → gRPC handlers → Database operations.
- Document which components interact directly and note any asynchronous interactions if applicable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["External Clients"] 
    G["API Gateway (grpc-gateway)"]
    S["gRPC Server (server.go)"]
    AUTH["Authentication (JWT)"]
    HAND["Request Handlers (handler)"]
    BM["Business Models (model)"]
    DS["Data Storage (store/)"]
    P["Protobuf Definitions (proto)"]

    subgraph "Database / Persistence"
        DB["DB Connections (db/db.go)"]
        SEED["Seed Data (db/seed/seed.go)"]
    end

    subgraph "Auxiliary Components"
        DFILE["Dockerfile"]
        DCOMP["docker-compose.yml"]
        MFILE["Makefile"]
        ENV["Environment Config (env)"]
    end

    A -->|"REST_request"| G
    G -->|"gRPC_call"| S
    S -->|"VerifyToken"| AUTH
    AUTH -->|"ForwardRequest"| HAND
    HAND -->|"BusinessLogic"| BM
    BM -->|"Persists"| DS
    DS -->|"ORM_Operations"| DB
    DB -->|"SeedData"| SEED
    S -->|"Uses"| P

    click G "https://github.com/raahii/golang-grpc-realworld-example/blob/master/gateway/gateway.go"
    click S "https://github.com/raahii/golang-grpc-realworld-example/blob/master/server.go"
    click HAND "https://github.com/raahii/golang-grpc-realworld-example/tree/master/handler/"
    click AUTH "https://github.com/raahii/golang-grpc-realworld-example/blob/master/auth/auth.go"
    click DS "https://github.com/raahii/golang-grpc-realworld-example/tree/master/store/"
    click BM "https://github.com/raahii/golang-grpc-realworld-example/tree/master/model/"
    click P "https://github.com/raahii/golang-grpc-realworld-example/tree/master/proto/"
    click DB "https://github.com/raahii/golang-grpc-realworld-example/blob/master/db/db.go"
    click SEED "https://github.com/raahii/golang-grpc-realworld-example/blob/master/db/seed/seed.go"
    click DFILE "https://github.com/raahii/golang-grpc-realworld-example/tree/master/Dockerfile"
    click DCOMP "https://github.com/raahii/golang-grpc-realworld-example/blob/master/docker-compose.yml"
    click MFILE "https://github.com/raahii/golang-grpc-realworld-example/tree/master/Makefile"
    click ENV "https://github.com/raahii/golang-grpc-realworld-example/tree/master/env/"

    class A external
    class G gateway
    class S server
    class AUTH module
    class HAND module
    class BM module
    class DS module
    class P module
    class DB db
    class SEED db
    class DFILE auxiliary
    class DCOMP auxiliary
    class MFILE auxiliary
    class ENV auxiliary

    classDef external fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef gateway fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef server fill:#FAD7A0,stroke:#9C640C,stroke-width:2px;
    classDef module fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef db fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef auxiliary fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
```
