# gelerum/artpaper architecture

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

- Interactive diagram: https://gitdiagram.com/gelerum/artpaper
- Repository: https://github.com/gelerum/artpaper

## Overview

##### Project type and purpose
- Artpaper is a backend service: a Go (Gin)-based REST API for managing articles, users, and authentication, backed by PostgreSQL and Redis, packaged with Docker.

##### File structure
- cmd/api/main.go: application entry point; boots the Gin server.
- pkg/server: server initialization and router setup.
- pkg/handler: HTTP handlers (article/user/auth endpoints) + middleware.
- pkg/service: business-logic layer (articles, users, auth, cache, token storage).
- pkg/repository: persistence layer for Postgres (articles, users) + tests.
- pkg/storage: generic abstraction for storage backends.
- docs: Swagger/OpenAPI definitions for autogenerated API docs.
- docker-related: Dockerfiles (api.Dockerfile, db.Dockerfile), docker-compose.yml, .env, init.sql.

##### Out main components
a. API Container
- Gin HTTP Server (cmd/api + pkg/server)
- Handler Layer (pkg/handler)
- Service Layer (pkg/service)
- Repository & Storage Interfaces (pkg/repository, pkg/storage)
- Swagger Docs Endpoint
b. Database Container
- PostgreSQL (initialized via init.sql)
c. Cache & Token Storage Containers
- Redis for general cache (CACHE_*)
- Redis (TOKEN_STORAGE_*) for JWT blacklisting or session tokens
d. External Clients
- Web/mobile UI or other API consumers

##### Relationships and data flows
1) Client → HTTP request → API Container (Gin router)
2) Router → Middleware (auth, logging) → Handler (e.g., ArticleHandler)
3) Handler → Service: apply business rules (e.g., validate JWT, enforce permissions)
4a) Service → Cache Storage (Redis) for read/write of cached data
4b) Service → Token Storage (Redis) for blacklisted or active tokens
4c) Service → Repository → Database (PostgreSQL) for CRUD
5) Repository → Database Container → returns rows → Service → Handler → HTTP response

##### Architectural patterns
- Layered/Clean architecture: separation of concerns between HTTP handlers, business logic, persistence, storage.
- Dependency Injection: handlers and services depend on interfaces (repository.Storage) for testability.
- Containerized microservice style: one container per component, networked via docker-compose.
- Documentation via Swagger (OpenAPI spec in docs/swagger.yaml → served by API).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["External Client"]:::external

    %% API Container grouping
    subgraph "API Container" 
        direction TB
        %% Presentation Layer
        subgraph "Presentation Layer"
            direction TB
            GinServer["Gin HTTP Server"]:::api
            Middleware["Middleware"]:::api
            ArticleHandler["ArticleHandler"]:::api
            UserHandler["UserHandler"]:::api
            AuthHandler["AuthHandler"]:::api
        end

        %% Business Layer
        subgraph "Business Layer"
            direction TB
            ArticleService["ArticleService"]:::api
            UserService["UserService"]:::api
            AuthService["AuthService"]:::api
            CacheStorage["CacheStorage (Redis)"]:::cache
            TokenStorage["TokenStorage (Redis)"]:::cache
        end

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            StorageAbstraction["Storage Abstraction"]:::api
            ArticleRepo["ArticleRepository"]:::api
            UserRepo["UserRepository"]:::api
        end

        %% Swagger Docs
        Swagger["Swagger Docs Endpoint"]:::api
    end

    %% External Storage Containers
    subgraph "Docker Compose Network"
        direction TB
        Postgres["PostgreSQL"]:::db
        RedisCache["Redis (Cache)"]:::cache
        RedisToken["Redis (TokenStorage)"]:::cache
    end

    %% Flows
    Client -->|"HTTP Request"| GinServer
    GinServer -->|"route request"| Middleware
    Middleware --> ArticleHandler
    Middleware --> UserHandler
    Middleware --> AuthHandler

    ArticleHandler -->|"calls"| ArticleService
    UserHandler -->|"calls"| UserService
    AuthHandler -->|"calls"| AuthService

    ArticleService -->|"Get/Set cache"| CacheStorage
    UserService -->|"Get/Set cache"| CacheStorage
    AuthService -->|"Validate/Blacklist JWT"| TokenStorage

    ArticleService --> ArticleRepo
    UserService --> UserRepo

    ArticleRepo -->|"SQL queries"| Postgres
    UserRepo -->|"SQL queries"| Postgres

    StorageAbstraction --> ArticleRepo
    StorageAbstraction --> UserRepo

    GinServer --> Swagger
    Swagger -->|"serves docs"| Client

    %% Click Events
    click GinServer "https://github.com/gelerum/artpaper/blob/main/cmd/api/main.go"
    click GinServer "https://github.com/gelerum/artpaper/blob/main/pkg/server/server.go"
    click Middleware "https://github.com/gelerum/artpaper/blob/main/pkg/handler/middleware.go"
    click ArticleHandler "https://github.com/gelerum/artpaper/blob/main/pkg/handler/article.go"
    click UserHandler "https://github.com/gelerum/artpaper/blob/main/pkg/handler/user.go"
    click AuthHandler "https://github.com/gelerum/artpaper/blob/main/pkg/handler/auth.go"
    click ArticleService "https://github.com/gelerum/artpaper/blob/main/pkg/service/article.go"
    click UserService "https://github.com/gelerum/artpaper/blob/main/pkg/service/user.go"
    click AuthService "https://github.com/gelerum/artpaper/blob/main/pkg/service/auth.go"
    click CacheStorage "https://github.com/gelerum/artpaper/blob/main/pkg/service/cache_storage.go"
    click TokenStorage "https://github.com/gelerum/artpaper/blob/main/pkg/service/token_storage.go"
    click StorageAbstraction "https://github.com/gelerum/artpaper/blob/main/pkg/storage/storage.go"
    click ArticleRepo "https://github.com/gelerum/artpaper/blob/main/pkg/repository/article.go"
    click UserRepo "https://github.com/gelerum/artpaper/blob/main/pkg/repository/user.go"
    click Postgres "https://github.com/gelerum/artpaper/blob/main/docker-compose.yml"
    click RedisCache "https://github.com/gelerum/artpaper/blob/main/docker-compose.yml"
    click RedisToken "https://github.com/gelerum/artpaper/blob/main/docker-compose.yml"
    click Swagger "https://github.com/gelerum/artpaper/blob/main/docs/swagger.yaml"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef db fill:#DFF0D8,stroke:#3C763D,color:#3C763D
    classDef cache fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B
    classDef external fill:#F2F2F2,stroke:#AAAAAA,color:#333333
```
