# niiqow/syltra-token-service architecture

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

- Interactive diagram: https://gitdiagram.com/niiqow/syltra-token-service
- Repository: https://github.com/niiqow/syltra-token-service

## Overview

##### Project type and purpose
- This is a standalone Go-based microservice (Syltra Token Service) responsible for JWT authentication, refresh-token rotation, session tracking, and secure token management.
- It exposes a REST API (login, refresh, logout, validate) built with the Gin framework, persisting refresh tokens and device info in PostgreSQL.

##### File structure
- cmd/main.go: application entrypoint, router & middleware setup.
- internal/config: environment/config loader.
- internal/handlers: HTTP controllers for auth endpoints.
- internal/middleware: rate limiting, auth-context injection.
- internal/services: business logic (token creation, rotation, validation).
- internal/repository: DB access (GORM) for users/refresh tokens.
- internal/models: domain models and DB migration scripts.
- internal/database: migration runner.
- docs/: Swagger JSON/YAML.
- Dockerfile: container build.

##### README for additional insights
- Core flows: login → issue JWT + refresh token; refresh → rotate token; logout(s) → revoke tokens; validation endpoint.
- External dependency: USERS_SERVICE_URL (to fetch or verify user info).
- Uses HMAC-SHA256 for JWT, GORM to talk to PostgreSQL, rate limiter to throttle abuse.

a. Main components
- API Gateway (or direct ingress): accepts HTTP(S) requests.
- Syltra Token Service:
- HTTP Layer (Gin router)
- Middleware Layer (rate limiter, auth context)
- Handler Layer (auth_handler.go)
- Service Layer (AuthService)
- Repository Layer (UserRepo, RefreshTokenRepo)
- Database: PostgreSQL (refresh_tokens table + migrations)
- External User Service: USERS_SERVICE_URL for user verification
- Swagger UI (docs served under /swagger)

b. Relationships & interactions
1. Client → API Gateway → Gin HTTP Layer.
2. Request passes through rate-limiter & auth middleware.
3. Handler invokes AuthService methods.
4. AuthService calls:
- UserRepo (or external Users Service) for credential check.
- RefreshTokenRepo to create, rotate, revoke tokens.
5. Repositories interact with PostgreSQL.
6. AuthService returns JWT & refresh token to handler → client.
7. Swagger UI served from docs/ endpoint.

c. Architectural patterns & design principles
- Layered (Clean) architecture: separation between handlers (API), services (business logic), repositories (data access), models.
- Hexagonal influences: external services (Users Service) and DB are adapters.
- Middleware pipeline: cross-cutting concerns (rate limiting, JWT validation).
- Migration-driven DB schema (internal/database + internal/models/migrations).

d. Key technologies
- Go 1.22, Gin framework
- GORM ORM for PostgreSQL 15
- JWT with HMAC-SHA256 via jwt-go
- Swagger for API docs
- Docker for containerization

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::external
    API["API Gateway"]:::process
    Config["Config Loader"]:::process
    DBConfig["DB Config Loader"]:::process
    MigrationRunner["Database Migration Runner"]:::process
    subgraph "Syltra Token Service"
        Router["Gin Router"]:::process
        subgraph "Middleware Layer"
            RL["Rate Limiter"]:::process
            AuthMW["Auth Context Injector"]:::process
        end
        subgraph "Handler Layer"
            Handler["Auth Handlers"]:::process
        end
        Service["AuthService"]:::process
        subgraph "Repository Layer"
            UserRepo["UserRepository"]:::process
            TokenRepo["RefreshTokenRepository"]:::process
        end
    end
    subgraph "Database & Migrations"
        DB["PostgreSQL"]:::database
    end
    UsersExt["Users Service"]:::external
    subgraph "API Documentation"
        SwaggerHandler["Swagger Handler"]:::process
        SwaggerJSON["docs/swagger.json"]:::docs
        SwaggerYAML["docs/swagger.yaml"]:::docs
    end
    Docker["Dockerfile"]:::process

    Client --> API
    API --> Router
    Config --> Router
    DBConfig --> MigrationRunner
    MigrationRunner --> DB
    Router --> RL
    Router --> AuthMW
    RL --> Handler
    AuthMW --> Handler
    Handler --> Service
    Service --> UserRepo
    Service --> TokenRepo
    Service --> UsersExt
    UserRepo --> DB
    TokenRepo --> DB
    Router --> SwaggerHandler
    SwaggerHandler --> SwaggerJSON
    SwaggerHandler --> SwaggerYAML
    Docker --> Router

    click Config "https://github.com/niiqow/syltra-token-service/blob/main/internal/config/config.go"
    click DBConfig "https://github.com/niiqow/syltra-token-service/blob/main/internal/config/database.go"
    click MigrationRunner "https://github.com/niiqow/syltra-token-service/blob/main/internal/database/database.go"
    click SwaggerHandler "https://github.com/niiqow/syltra-token-service/blob/main/docs/docs.go"
    click SwaggerJSON "https://github.com/niiqow/syltra-token-service/blob/main/docs/swagger.json"
    click SwaggerYAML "https://github.com/niiqow/syltra-token-service/blob/main/docs/swagger.yaml"
    click Router "https://github.com/niiqow/syltra-token-service/blob/main/cmd/main.go"
    click RL "https://github.com/niiqow/syltra-token-service/blob/main/internal/middleware/rate_limiter.go"
    click AuthMW "https://github.com/niiqow/syltra-token-service/blob/main/internal/middleware/middleware.go"
    click Handler "https://github.com/niiqow/syltra-token-service/blob/main/internal/handlers/auth_handler.go"
    click Handler "https://github.com/niiqow/syltra-token-service/blob/main/internal/handlers/auth.go"
    click Service "https://github.com/niiqow/syltra-token-service/blob/main/internal/services/auth_service.go"
    click UserRepo "https://github.com/niiqow/syltra-token-service/blob/main/internal/repository/user_repository.go"
    click TokenRepo "https://github.com/niiqow/syltra-token-service/blob/main/internal/repository/user_repository.go"
    click Docker "https://github.com/niiqow/syltra-token-service/tree/main/Dockerfile"
    click MigrationRunner "https://github.com/niiqow/syltra-token-service/blob/main/internal/database/migrations/001_create_refresh_tokens.go"
    click DB "https://github.com/niiqow/syltra-token-service/blob/main/internal/models/migrations/000001_create_refresh_tokens_table.up.sql"
    click DB "https://github.com/niiqow/syltra-token-service/blob/main/internal/models/migrations/000001_create_refresh_tokens_table.down.sql"
    
    classDef process fill:#B3CDE3,stroke:#03396C,color:#03396C
    classDef database fill:#C7E9C0,stroke:#2E8B57,color:#2E8B57
    classDef external fill:#FBB4AE,stroke:#B22222,color:#B22222
    classDef docs fill:#FDFD96,stroke:#FFD700,stroke-dasharray:5 5
```
