# asguizar/microservices architecture

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

- Interactive diagram: https://gitdiagram.com/asguizar/microservices
- Repository: https://github.com/asguizar/microservices

## Overview

##### Project type and purpose
- This is a Go‐based Microservices API System (monolithic binary simulating three services) providing User, File and Audit APIs.
- It’s designed to be stateless, JWT‐secured, horizontally scalable (Docker/Compose + Nginx LB), high performance (Go, goroutines) and production ready (graceful shutdown, timeouts, CORS, rate limiting).

##### File structure
- Top-level files:
- `main.go` – single entrypoint registering all HTTP routes (User API, File API, Audit API, Security Controller, health and metrics endpoints)
- `.env.example` – sample environment variables for PORT, JWT_SECRET, STORAGE_PATH
- `storage/` – local disk folder for file persistence (could be replaced with S3)
- `go.mod`/`go.sum` – Go module definitions
- `readme.md`/`testing.md` – documentation and test instructions
- There’s no separate “services” folder— all services live in code under `main.go` (or imported packages). The architecture is realized via routing groups and handlers rather than separate repos.

##### README for architectural insights
- ASCII art showing:
Client → Load Balancer (Nginx) → Node Instances → APIs → Database
├ User API
├ File API
└ Audit API → Security Controller
- Detailed feature list: security (JWT + bcrypt), audit logging pipeline (buffered channel), pluggable storage and database abstractions, Docker Compose scaling, Prometheus metrics.

##### Key callouts
- Security Controller sits in front of all APIs to enforce authentication & authorization.
- Buffered channel in Audit API for non-blocking log ingestion.
- Pluggable database interface with in-memory default and thread-safety.
- Docker Compose file snippet illustrating multiple service instances and Nginx load balancing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    subgraph "Clients"
        direction TB
        Browser["Browser"]:::external
        curl["cURL"]:::external
        Mobile["Mobile App"]:::external
    end

    %% Load Balancer
    LB["Nginx Load Balancer"]:::loadbalancer

    %% Application Cluster
    subgraph "Application Cluster (Go App Instances)"
        direction TB
        Router["HTTP Router"]:::app
        Security["Security Controller\n(JWT, bcrypt, RBAC)"]:::app
        UserAPI["User API Handler"]:::app
        FileAPI["File API Handler"]:::app
        AuditAPI["Audit API Handler"]:::app
        AuditWorker["Audit Logger Worker\n(buffered channel + goroutine)"]:::app
        Metrics["Health & Metrics Endpoints\n(/metrics)"]:::app
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DB["Database Abstraction\n(in-memory, PostgreSQL, DynamoDB)"]:::storage
        FileStorage["File Storage\n(local disk or S3)"]:::storage
        SampleFile["Sample Stored File\n(502e1456-2eb0-403d-9ec6-d516e9222bd8_test.txt)"]:::storage
    end

    %% Monitoring
    Prometheus["Prometheus"]:::external

    %% Documentation & Config
    Env["Configuration\n(.env.example)"]:::docs
    Docs1["Project Documentation\n(readme.md)"]:::docs
    Docs2["Test Instructions\n(testing.md)"]:::docs
    Modules["Go Modules\n(go.mod, go.sum)"]:::docs

    %% Connections
    Browser -->|HTTP/JSON| LB
    curl -->|HTTP/JSON| LB
    Mobile -->|HTTP/JSON| LB

    LB -->|HTTP/JSON| Router
    Router -->|JWT Validation| Security
    Security -->|authorized| UserAPI
    Security -->|authorized| FileAPI
    Security -->|authorized| AuditAPI

    UserAPI -->|CRUD| DB
    FileAPI -->|read/write| FileStorage
    AuditAPI -->|enqueue| AuditWorker
    AuditWorker -.->|async write| DB

    Router -->|scrape| Metrics
    Metrics -->|Prometheus scrape| Prometheus

    %% Click Events
    click Router "https://github.com/asguizar/microservices/blob/main/main.go"
    click Security "https://github.com/asguizar/microservices/blob/main/main.go"
    click UserAPI "https://github.com/asguizar/microservices/blob/main/main.go"
    click FileAPI "https://github.com/asguizar/microservices/blob/main/main.go"
    click AuditAPI "https://github.com/asguizar/microservices/blob/main/main.go"
    click AuditWorker "https://github.com/asguizar/microservices/blob/main/main.go"
    click Env "https://github.com/asguizar/microservices/blob/main/.env.example"
    click FileStorage "https://github.com/asguizar/microservices/tree/main/storage/"
    click SampleFile "https://github.com/asguizar/microservices/blob/main/storage/502e1456-2eb0-403d-9ec6-d516e9222bd8_test.txt"
    click Docs1 "https://github.com/asguizar/microservices/blob/main/readme.md"
    click Docs2 "https://github.com/asguizar/microservices/blob/main/testing.md"
    click Modules "https://github.com/asguizar/microservices/blob/main/go.mod"
    click Modules "https://github.com/asguizar/microservices/blob/main/go.sum"

    %% Styles
    classDef app fill:#cce5ff,stroke:#3399ff,color:#000
    classDef storage fill:#d4edda,stroke:#28a745,color:#000
    classDef loadbalancer fill:#ffe5b4,stroke:#ff8c00,color:#000
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef docs fill:#f8d7da,stroke:#dc3545,color:#000
```
