# moolair/simplebank-golang-backend architecture

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

- Interactive diagram: https://gitdiagram.com/moolair/simplebank-golang-backend
- Repository: https://github.com/moolair/simplebank-golang-backend

## Overview

Based on our analysis of the complete file structure and the README, the project is a full-stack banking service built in Golang. It exposes RESTful APIs (using the Gin framework), provides gRPC endpoints, manages database interactions (with PostgreSQL via migrations and SQLC), and incorporates asynchronous processing (using background workers and email sending). It also includes a CI/CD pipeline (with GitHub Actions), containerization (Docker), and deployment manifests for Kubernetes (AWS).

##### Main Components
- API Service: Represented by the “api” directory, this component contains the main HTTP server, middleware, account, user, transfer, and token handling.
- gRPC Service: In the “gapi” folder, which handles gRPC calls and RPC logic. The related protobuf definitions in the “proto” and “pb” directories should be noted.
- Database: The “db” folder holds the migration scripts (SQL), mocks, SQL query files, and SQLC autogenerated code. Indicate PostgreSQL as the primary persistent store.
- Asynchronous Worker: The “worker” directory includes distributors and processors to handle tasks like sending verification emails.
- Authentication & Token Management: The “token” directory contains code for JWT and PASETO token creation and tests.
- Email Service: The “mail” directory handles email sending logic which connects with the asynchronous workers.
- Utility & Validation: The “util” and “val” directories provide essential helper functions like configuration, password hashing, currency management, and role management.
- Deployment & Infrastructure: Include elements from “Dockerfile”, “docker-compose.yaml”, and Kubernetes manifests in the “eks” directory showing AWS-specific deployment, as well as GitHub Actions workflows (.github/workflows) used in CI/CD.
- Documentation: The “doc” directory includes the DBML, SQL schema, and Swagger UI, which help showcase the API definitions and database schema.

##### Relationships and Interactions
- The API Service interacts with the Authentication component (token creation/validation) for managing secure access, as indicated by the “api/token.go” and “token” directories.
- The Asynchronous Worker processes background jobs (like email verification tasks) which are triggered by events in the API layer. Indicate data flows such as “queue” or “message passing” to denote async processing.
- The Email Service (mail) gets invoked by the worker process. Clearly mark this linkage.
- External Systems: Denote external integrations, including Docker containers, Kubernetes clusters for deployment, and potential external services (e.g., Redis for caching/session management, Let's Encrypt for HTTPS).
- CI/CD: Represent GitHub Actions for testing and deployment pipelines (workflow files) that integrate into the process.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different components are split by their function – API layer, gRPC services, background workers, and database access.
- Microservices/MVC-like Flow: Although the entire service is part of a single repository, the separation between API endpoints, authentication, and background processing reflects a decoupled architecture.
- Transactional Database Interactions: Highlight proper usage of migrations, SQLC for safe type-checked database interactions, and structured SQL query management.
- Containerization & Orchestration: Emphasize that the project uses Docker and Kubernetes for deployment.
- Testing & CI/CD: Capture that extensive unit tests and CI pipelines (GitHub Actions) support continuous development.

- Drill down into each major component, showing sub-components when necessary (for example, inside the API Service, you might detail endpoints for account creation, transfers, etc.).
- Significant interactions with notes on key technologies like Gin, SQLC, Docker, Kubernetes, JWT/PASETO, and gRPC.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client"]:::external

    %% Service Layer
    subgraph "Service Layer"
        API["API Service (Gin Framework)"]:::service
        GRPC["gRPC Service"]:::service
        Auth["Authentication & Token Management"]:::service
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Database (PostgreSQL)"]:::db
    end

    %% Asynchronous Processing
    subgraph "Async Processing"
        Worker["Asynchronous Worker (Email,Task Processing)"]:::async
        Mail["Email Service"]:::async
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        Utility["Utility"]:::support
        Validation["Validation"]:::support
        Doc["Documentation"]:::support
    end

    %% Deployment & CI/CD
    subgraph "Deployment & CI/CD"
        CICD["CI/CD Pipeline (GitHub Actions)"]:::infra
        Docker["Docker & Compose"]:::infra
        K8s["Kubernetes (AWS EKS)"]:::infra
    end

    %% Relationships
    Client -->|"requests"| API
    Client -->|"requests"| GRPC

    API -->|"transactions"| DB
    GRPC -->|"queries"| DB

    API -->|"auth"| Auth

    API -->|"triggers"| Worker
    Worker -->|"calls"| Mail

    %% Supporting utilities connected (dashed lines)
    Utility ---|"supports"| API
    Utility ---|"supports"| GRPC
    Utility ---|"supports"| Auth
    Utility ---|"supports"| Worker

    Validation ---|"validates"| API
    Validation ---|"validates"| GRPC
    Validation ---|"validates"| Auth
    Validation ---|"validates"| Worker

    Doc ---|"documents"| API
    Doc ---|"documents"| DB

    %% CI/CD and Deployment flows
    CICD -->|"builds"| Docker
    CICD -->|"deploys"| K8s

    %% Styles
    classDef service fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef db fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef async fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef support fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
    
    %% Click Events
    click API "https://github.com/moolair/simplebank-golang-backend/tree/main/api/"
    click GRPC "https://github.com/moolair/simplebank-golang-backend/tree/main/gapi/"
    click DB "https://github.com/moolair/simplebank-golang-backend/tree/main/db/"
    click Worker "https://github.com/moolair/simplebank-golang-backend/tree/main/worker/"
    click Auth "https://github.com/moolair/simplebank-golang-backend/tree/main/token/"
    click Mail "https://github.com/moolair/simplebank-golang-backend/tree/main/mail/"
    click Utility "https://github.com/moolair/simplebank-golang-backend/tree/main/util/"
    click Validation "https://github.com/moolair/simplebank-golang-backend/tree/main/val/"
    click CICD "https://github.com/moolair/simplebank-golang-backend/tree/main/.github/workflows/"
    click Docker "https://github.com/moolair/simplebank-golang-backend/blob/main/docker-compose.yaml"
    click K8s "https://github.com/moolair/simplebank-golang-backend/tree/main/eks/"
    click Doc "https://github.com/moolair/simplebank-golang-backend/tree/main/doc/"
```
