# nurashi/auth_grpc architecture

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

- Interactive diagram: https://gitdiagram.com/nurashi/auth_grpc
- Repository: https://github.com/nurashi/auth_grpc

## Overview

##### Project type and purpose
- This is a standalone authentication microservice implemented in Go, exposing a gRPC API.
- It follows clean-architecture principles and integrates with PostgreSQL, Redis, and Apache Kafka for persistence, caching, and event-driven messaging.

##### File structure
- Top-level “client” folder holds a sample gRPC client.
- “cmd/” contains the main entrypoint for the service.
- “internal/” implements the core layers:
- cache (Redis adapter)
- config loader
- db (Postgres adapter)
- handler (repository abstractions)
- models (domain objects)
- server (gRPC server & interceptors)
- service (business logic: auth, JWT)
- “proto/” stores Protocol Buffer definitions and generated Go stubs.
- “kafka-local/” provides local Kafka producer/consumer runners for testing.
- “config/” holds YAML configuration.
- Shared utilities (logger, generic helpers) under “shared/”.
- Docker+Compose files orchestrate Postgres, Redis, Kafka, Zookeeper, and the microservice itself.

##### Extract architecture insights from README
- gRPC transport layer with three RPC methods: RegisterUser, LoginUser, GetUserByID.
- Business logic publishes user-created and user-login events to Kafka.
- A consumer listens to these topics, populating Redis cache.
- Read-through cache strategy: on GetUserByID, read Redis first, fall back to Postgres then repopulate cache.

##### Main components
a. Client (gRPC test client)
b. API Layer: gRPC Server + Interceptors
c. Application / Service Layer: auth service, JWT generator
d. Persistence:
- PostgreSQL database (persistent user store)
- Redis cache (high-speed user lookup by ID/email)
e. Messaging:
- Kafka Broker + Zookeeper
- Producer inside service for user-created & login events
- Consumer (background process) updating Redis
f. Configuration & Utilities: config loader, custom logger

##### Relationships & data flow
- Client → gRPC Server: calls RegisterUser/LoginUser/GetUserByID
- Server → Service Layer: validation, hashing or credential check
- Service → DB: Create or read User record
- Service → Kafka Producer: emit “user-created” or “user-login” events
- Kafka Broker → Consumer: subscribe & consume events
- Consumer → Redis: cache user data
- GetUserByID: 1) check Redis; 2) on miss, query Postgres; 3) update Redis

##### Architectural patterns
- Clean (hexagonal) architecture:
- Domain models (internal/models)
- Ports & adapters (internal/handler + internal/db/cache)
- Framework boundary (gRPC server in internal/server)
- Event-driven integration via Kafka topics
- Read-through caching with Redis

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["gRPC Test Client"]:::compute
    click Client "https://github.com/nurashi/auth_grpc/blob/main/client/main.go"

    %% Docker Compose Boundary
    subgraph "Auth gRPC Microservice"
        direction TB

        %% Configuration & Utilities
        Config["Config Loader"]:::config
        click Config "https://github.com/nurashi/auth_grpc/blob/main/internal/config/config.go"
        Logger["Logger & Helpers"]:::config
        click Logger "https://github.com/nurashi/auth_grpc/blob/main/shared/logger.go"
        click Logger "https://github.com/nurashi/auth_grpc/blob/main/shared/util.go"

        %% API Layer
        Server["gRPC Server"]:::compute
        click Server "https://github.com/nurashi/auth_grpc/blob/main/internal/server/grpc.go"
        Interceptor["gRPC Interceptors"]:::compute
        click Interceptor "https://github.com/nurashi/auth_grpc/blob/main/internal/server/interceptor.go"

        %% Service Layer
        AuthService["Auth Service & JWT"]:::compute
        click AuthService "https://github.com/nurashi/auth_grpc/blob/main/internal/service/auth.go"

        %% Persistence
        DB["PostgreSQL"]:::db
        click DB "https://github.com/nurashi/auth_grpc/blob/main/internal/db/postgres.go"
        RepoInterface["Repository Interface"]:::compute
        click RepoInterface "https://github.com/nurashi/auth_grpc/blob/main/internal/handler/repository/repository.go"
        RepoImpl["SQL Repository Impl"]:::compute
        click RepoImpl "https://github.com/nurashi/auth_grpc/blob/main/internal/handler/pg_repository.go"

        %% Caching
        Redis["Redis Cache"]:::cache
        click Redis "https://github.com/nurashi/auth_grpc/blob/main/internal/cache/redis.go"
        click Redis "https://github.com/nurashi/auth_grpc/blob/main/internal/cache/util.go"
        click Redis "https://github.com/nurashi/auth_grpc/blob/main/internal/cache/redis_cache.go"
        click Redis "https://github.com/nurashi/auth_grpc/blob/main/internal/cache/user_cache.go"

        %% Messaging (Producer)
        Producer["Kafka Producer"]:::messaging
        click Producer "https://github.com/nurashi/auth_grpc/blob/main/kafka-local/producer.go"
        click Producer "https://github.com/nurashi/auth_grpc/blob/main/kafka-local/runner.go"
    end

    %% Messaging Infrastructure
    Kafka["Kafka Broker + Zookeeper"]:::messaging
    click Kafka "https://github.com/nurashi/auth_grpc/blob/main/kafka-local/docker-compose.yml"

    %% Consumer
    Consumer["Kafka Consumer"]:::compute
    click Consumer "https://github.com/nurashi/auth_grpc/blob/main/kafka-local/consumer.go"

    %% Protocol Buffers
    subgraph "Protocol Buffers"
        AuthProto["auth.proto"]:::config
        click AuthProto "https://github.com/nurashi/auth_grpc/blob/main/proto/auth.proto"
        AuthPB["auth.pb.go"]:::config
        click AuthPB "https://github.com/nurashi/auth_grpc/blob/main/proto/auth.pb.go"
        AuthGRPC["auth_grpc.pb.go"]:::config
        click AuthGRPC "https://github.com/nurashi/auth_grpc/blob/main/proto/auth_grpc.pb.go"
    end

    %% Compose Files
    Compose["Docker Compose"]:::config
    click Compose "https://github.com/nurashi/auth_grpc/blob/main/docker-compose.yml"
    ComposeInfra["Service Dockerfile"]:::config
    click ComposeInfra "https://github.com/nurashi/auth_grpc/tree/main/Dockerfile"

    %% Domain Models
    subgraph "Domain Models"
        UserModel["user.go"]:::config
        click UserModel "https://github.com/nurashi/auth_grpc/blob/main/internal/models/user.go"
        EventModel["event.go"]:::config
        click EventModel "https://github.com/nurashi/auth_grpc/blob/main/internal/models/event.go"
    end

    %% Flows
    Client -->|"RegisterUser RPC\nLoginUser RPC\nGetUserByID RPC"| Server
    Server -->|"intercept RPC calls"| Interceptor
    Interceptor -->|"invoke methods"| AuthService

    AuthService -->|"CreateUser/ValidateCredentials"| RepoInterface
    RepoInterface -->|"SQL queries"| RepoImpl
    RepoImpl -->|"CRUD operations"| DB

    AuthService -->|"Publish events"| Producer
    Producer -->|"send messages"| Kafka

    Kafka -->|"user-created/user-login"| Consumer
    Consumer -->|"cache user data"| Redis

    AuthService -->|"GetUserByID"| Redis
    Redis -->|"cache miss"| DB
    DB -->|"user record"| Redis
    Redis -->|"return user"| AuthService

    %% Configuration injection
    Config --> Server
    Config --> Consumer
    Logger --> Server
    Logger --> Consumer

    %% Class Definitions
    classDef compute fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef db fill:#F4A460,stroke:#333,stroke-width:1px
    classDef cache fill:#90EE90,stroke:#333,stroke-width:1px
    classDef messaging fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
```
