# techschool/simplebank architecture

> Architecture diagram of the GitHub repository techschool/simplebank, 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/techschool/simplebank
- Repository: https://github.com/techschool/simplebank

## Overview

##### Main Components
- Frontend: Represented by the “frontend” directory, using Vue.js. This portion handles the user interface and communicates with the backend (via RESTful APIs).
- API / HTTP Server: Sourced from the “api” directory (and its tests, middleware, server, etc.). This is the core of the backend service built using Gin.
- gRPC Service Layer: Indicated by the “gapi” directory along with “pb” and “proto” folders. This shows that the service also provides gRPC endpoints (with a gateway to serve HTTP requests concurrently).
- Database: Shown by the “db” directory and its subdirectories (migrations, query, sqlc). This component points to a PostgreSQL backend with migration scripts, SQLC-generated code and queries.
- Asynchronous Worker: Located in the “worker” directory. This is the background task processor (using Redis and Asynq) that takes care of tasks like sending verification emails.
- Auth and Token Management: The “token” folder handles the generation and validation of JWT/PASETO access tokens, supporting authentication for the API.
- Mail Service: The “mail” directory contains the email sender logic, which is integrated into either the API or the worker for sending out emails.
- Miscellaneous Utilities and Validators: Components like “util” and “val” provide application-wide utilities for configuration, password handling, and validation.

##### Relationships and Interactions
- The Frontend interacts directly with the API layer using HTTP (and possibly through gRPC gateway endpoints).
- The API server handles requests, performing actions like creating accounts, processing transfers, and authenticating users. It interfaces with the database for executing transactions and accessing persistent data.
- gRPC endpoints (documented in the gapi section) provide additional interfaces which could also be used internally or by external clients, and these relay requests to similar business logic as the REST endpoints.
- A background worker picks up asynchronous tasks (such as sending a verification email) from a message queue (Redis) and may further write to the database (for task status or updates).
- The Mail service is engaged by either the API or worker components, sending emails when a new verification is triggered.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Different directories represent clear layers (e.g., API layer, database access layer, business logic, and asynchronous processing).
- Layered Architecture: One layer handles HTTP/gRPC requests, another handles database interactions (via sqlc and migrations), and yet another handles async tasks.
- Microservice-like Components: Although it is a single repository, the service clearly separates concerns like authentication, email processing, and API endpoints, which can be drawn as loosely coupled modules.
- Security and Reliable Transaction Handling: Include notes on transaction management in the database (using sqlc and migration scripts) and security aspects in authentication (JWT/PASETO, middleware).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE["Vue Frontend"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        AP["Gin HTTP API"]:::api
        GR["gRPC Service"]:::grpc
        AT["Auth/Token Service"]:::auth
        UT["Utilities"]:::util
        VA["Validators"]:::validator
        AW["Async Worker"]:::worker
        MS["Mail Service"]:::mail
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["PostgreSQL Database"]:::database
    end

    %% Deployment & Infrastructure
    subgraph "Deployment & Infrastructure"
        INFRA["Infrastructure"]:::infrastructure
        DF["Dockerfile"]:::infrastructure
        DC["docker-compose"]:::infrastructure
        KE["Kubernetes EKS"]:::infrastructure
        CICD["CI/CD Workflows"]:::infrastructure
    end

    %% Relationships and Data Flow
    FE -->|"HTTP"| AP
    AP -->|"gRPC_call"| GR
    AP -->|"DB_Transaction"| DB
    GR -->|"DB_Access"| DB
    AP -->|"Dispatch_Task"| AW
    AW -->|"Email_Task"| MS
    AP -->|"Token_Auth"| AT
    AP -->|"uses"| UT
    AP -->|"validates"| VA

    %% Infrastructure Deployment Connections
    DF --> INFRA
    DC --> INFRA
    KE --> INFRA
    CICD --> INFRA
    INFRA --- FE
    INFRA --- AP
    INFRA --- GR
    INFRA --- AW

    %% Styles
    classDef frontend fill:#f9e79f,stroke:#f39c12,stroke-width:2px;
    classDef api fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef grpc fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
    classDef database fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef worker fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef auth fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;
    classDef util fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef validator fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef mail fill:#f8c471,stroke:#e67e22,stroke-width:2px;
    classDef infrastructure fill:#d6eaf8,stroke:#2980b9,stroke-width:2px;

    %% Click Events for Component Mapping
    click FE "https://github.com/techschool/simplebank/tree/master/frontend/"
    click AP "https://github.com/techschool/simplebank/tree/master/api/"
    click GR "https://github.com/techschool/simplebank/tree/master/gapi/"
    click DB "https://github.com/techschool/simplebank/tree/master/db/"
    click AW "https://github.com/techschool/simplebank/tree/master/worker/"
    click AT "https://github.com/techschool/simplebank/tree/master/token/"
    click MS "https://github.com/techschool/simplebank/tree/master/mail/"
    click UT "https://github.com/techschool/simplebank/tree/master/util/"
    click VA "https://github.com/techschool/simplebank/tree/master/val/"
    click DF "https://github.com/techschool/simplebank/tree/master/Dockerfile"
    click DC "https://github.com/techschool/simplebank/blob/master/docker-compose.yaml"
    click KE "https://github.com/techschool/simplebank/tree/master/eks/"
    click CICD "https://github.com/techschool/simplebank/tree/master/.github/workflows/"
```
