# gregorykogan/jwt-microservice architecture

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

- Interactive diagram: https://gitdiagram.com/gregorykogan/jwt-microservice
- Repository: https://github.com/gregorykogan/jwt-microservice

## Overview

##### Main Components
- Client: Represents any external consumer (browser, mobile app, etc.) making API requests.
- NGINX Reverse Proxy: Handles incoming requests and forwards them to the backend using Docker DNS-based load balancing.
- Docker DNS / Load Balancer: Registers multiple instances of the JWT service (illustrated as JWT Service 1, JWT Service 2, …, JWT Service n).
- JWT Authentication Service: The core service running the Go application (found in cmd/jwt-microservice and its supporting packages under pkg/). This component contains:
- Authentication logic (pkg/auth)
- Cache handling (pkg/cache)
- Logging (pkg/logging)
- Configuration (pkg/config)
- Secrets management (pkg/secrets)
- Health-checks (pkg/ping)
- Redis: Acts as a shared state repository for caching (used for efficient token validation, rotation, and auto-logout support).
- Optional: Load Testing Components – The load-tests directory indicates usage of Grafana K6 for performance evaluation.

##### File Structure for Architectural Clues
- The top-level directories (cmd, pkg, load-tests) indicate separation of concerns:
- “cmd” holds the entry point (main.go) for the JWT microservice.
- “pkg” contains the various internal libraries/modules such as authentication logic, caching, logging, etc.
- “load-tests” holds Docker and test-scripts for performance testing.
- Configuration files (config.yml, docker-compose.yml, nginx.conf) signal that the architecture is not only containerized but also geared for horizontal scalability through Docker’s orchestration.

##### Architectural Patterns
- The project follows a microservice pattern focused on authentication.
- There is a separation between core business logic (authentication, caching, repos) and infrastructure (NGINX, Docker, Redis).
- The usage of token rotation, auto-logout, and structured logging implies strong security and observability design principles.
- Horizontal scaling is built-in with Docker, where multiple instances are managed using DNS-based load balancing.

- Expand on it by incorporating additional components (such as configuration management and logging) that are present in the file structure.
- That every major module (client, reverse proxy, load balancer, multiple service instances, Redis, and load testing components) is represented and clearly connected.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    subgraph "External"
        CLIENT["Client"]:::client
    end

    %% Web Layer with NGINX Reverse Proxy
    subgraph "Web Layer"
        NGINX["NGINX Reverse Proxy"]:::nginx
    end

    %% Orchestration Layer: Docker Compose & Load Balancing
    subgraph "Orchestration Layer"
        DC["Docker Compose & Containerization"]:::dockerCompose
        LB["Docker DNS & Load Balancer"]:::dockerLB
    end

    %% JWT Authentication Service with supporting modules
    subgraph "JWT Authentication Service"
        JWS["JWT Service Instance (Go)"]:::jwtService
        JENTRY["Entry Point"]:::jwtModule
        JAUTH["Authentication Logic"]:::jwtModule
        JCACHE["Cache Handling"]:::jwtModule
        JLOG["Logging"]:::jwtModule
        JCONFIG["Configuration"]:::jwtModule
        JSECRETS["Secrets Management"]:::jwtModule
        JPING["Health-checks"]:::jwtModule
    end

    %% Shared State with Redis
    subgraph "Shared State"
        REDIS["Redis (Cache)"]:::redis
    end

    %% Load Testing Components
    subgraph "Load Testing"
        LT_TEST["Test Script"]:::loadTest
        LT_DOCKER["K6 Dockerfile"]:::loadTest
    end

    %% Connections
    CLIENT -->|"API_Request"| NGINX
    NGINX -->|"Forward_Request"| LB
    DC --> LB
    LB -->|"Route_Traffic"| JWS
    JWS -->|"Initialize"| JENTRY
    JENTRY -->|"Uses"| JAUTH
    JENTRY -->|"Uses"| JCACHE
    JENTRY -->|"Uses"| JLOG
    JENTRY -->|"Uses"| JCONFIG
    JENTRY -->|"Uses"| JSECRETS
    JENTRY -->|"Uses"| JPING
    JWS -->|"Cache/State"| REDIS
    REDIS -->|"State_Update"| JWS
    LT_TEST -->|"Simulate_Load"| NGINX
    LT_DOCKER -->|"Containerized_Test"| LT_TEST

    %% Click Events
    click NGINX "https://github.com/gregorykogan/jwt-microservice/blob/main/nginx.conf"
    click DC "https://github.com/gregorykogan/jwt-microservice/blob/main/docker-compose.yml"
    click JENTRY "https://github.com/gregorykogan/jwt-microservice/blob/main/cmd/jwt-microservice/main.go"
    click JAUTH "https://github.com/gregorykogan/jwt-microservice/tree/main/pkg/auth"
    click JCACHE "https://github.com/gregorykogan/jwt-microservice/tree/main/pkg/cache"
    click JLOG "https://github.com/gregorykogan/jwt-microservice/tree/main/pkg/logging"
    click JCONFIG "https://github.com/gregorykogan/jwt-microservice/tree/main/pkg/config"
    click JSECRETS "https://github.com/gregorykogan/jwt-microservice/tree/main/pkg/secrets"
    click JPING "https://github.com/gregorykogan/jwt-microservice/tree/main/pkg/ping"
    click LT_TEST "https://github.com/gregorykogan/jwt-microservice/blob/main/load-tests/test.js"
    click LT_DOCKER "https://github.com/gregorykogan/jwt-microservice/blob/main/load-tests/Dockerfile.k6"

    %% Styles
    classDef client fill:#a1c4fd,stroke:#1f78b4,stroke-width:2px;
    classDef nginx fill:#baf7a1,stroke:#4caf50,stroke-width:2px;
    classDef dockerLB fill:#ffeb99,stroke:#f39c12,stroke-width:2px;
    classDef dockerCompose fill:#fadadd,stroke:#e74c3c,stroke-width:2px;
    classDef jwtService fill:#fff79a,stroke:#f1c40f,stroke-width:2px;
    classDef jwtModule fill:#d6a4a4,stroke:#c0392b,stroke-width:2px;
    classDef redis fill:#ffcccc,stroke:#e74c3c,stroke-width:2px;
    classDef loadTest fill:#d1c4e9,stroke:#8e44ad,stroke-width:2px;
```
