# nachoov/spl-access architecture

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

- Interactive diagram: https://gitdiagram.com/nachoov/spl-access
- Repository: https://github.com/nachoov/spl-access

## Overview

##### Project Type and Purpose
- This is a backend API service written in Go, exposing REST endpoints and a WebSocket endpoint for real-time access-control events.
- It uses the Fiber web framework, Ent for ORM, and PostgreSQL as the data store.
- The project follows a layered, monolithic architecture.

##### File Structure and Key Directories
- Top‐level orchestration:
- Dockerfile / docker-compose.yaml – container definitions for the Go app and Postgres.
- Makefile / .air.toml – build and hot-reload scripts.
- main.go – application entry point.
- Application code under src/:
- server/fiber.go – HTTP server bootstrap, route registration, WebSocket upgrade.
- middleware/auth.go – request authentication.
- controller/… – HTTP handlers (access.go, main.go).
- service/… – business logic (access.go).
- repository/… – data access interfaces and Postgres implementations using Ent (access_postgres.go, access_query.sql).
- db/postgres.go – raw DB initialization for Ent.
- dto/… – request/response payload definitions.
- model/… – domain models (if any custom beyond Ent).
- websocket/websocket.go – real-time event hub for connected clients.
- helpers/… – utility and error handling.

##### README for Additional Insights
- Confirms Go 1.19, PostgreSQL requirement, environment variables.
- Development flow uses Air for hot reload.

##### Main Components
a. Client Tier
- API Consumers (e.g., web/mobile clients)
- WebSocket Clients
b. Entry Point
- Load Balancer / Reverse Proxy (optional)
- Fiber HTTP Server
c. Cross-Cutting Concerns
- Middleware (Auth, Logging)
- DTOs for request/response shaping
d. Business Logic
- Controller Layer (HTTP handlers)
- Service Layer (use-case orchestration)
e. Data Access
- Repository Interface
- Ent ORM client
- Raw SQL module (for complex queries)
f. Persistence
- PostgreSQL Database
g. Dev/Infra
- Docker Compose (App container, Postgres container)
- Air (hot-reload in dev)
h. (Future) Batch Processor
- Cron Job → BigQuery

##### Relationships and Data Flows
- WebSocket Flow: Client ↔ Fiber WebSocket Route ↔ Websocket Hub ↔ Service → Repository → DB (and back)

##### Architectural Patterns and Principles
- Layered Architecture: clear separation of concerns (Presentation, Business, Data).
- Repository Pattern: abstracts DB operations behind interfaces.
- DTOs: isolate API contract from domain entities.
- ORM (Ent): code-first schema, type safety.
- Middleware chaining in Fiber.
- Dependency injection via constructor functions in main.go.
- Containerization with Docker, orchestration via docker-compose.

##### Technologies and Frameworks to Label
- Go 1.19+
- Fiber (github.com/gofiber/fiber)
- Ent ORM (entgo.io)
- PostgreSQL
- Docker / Docker Compose
- Air (dev hot reload)
- SQL (raw .sql files for intricate queries)
- WebSockets (real-time channel)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Development / Deployment" 
        direction TB
        infra_app["Go App Container"]:::infra
        infra_db["PostgreSQL Container"]:::infra
    end

    infra_app --> infra_db

    subgraph "Go App" 
        direction TB

        Entry["main.go"]:::infra
        Config["Config Loader\n(src/config/config.go)"]:::infra
        Make["Makefile /.air.toml"]:::infra

        subgraph "Presentation Layer" 
            direction TB
            HTTP["Fiber HTTP Server\n(src/server/fiber.go)"]:::presentation
            WS["WebSocket Hub\n(src/websocket/websocket.go)"]:::presentation
            HTTP --> WS
        end

        subgraph "Cross-Cutting" 
            direction TB
            Auth["Auth Middleware\n(src/middleware/auth.go)"]:::presentation
            DTOs["DTOs\n(src/dto/access.go, src/dto/user.go)"]:::presentation
            Helpers["Helpers\n(src/helpers/errors.go, src/helpers/utils.go)"]:::presentation
        end

        subgraph "Business Layer" 
            direction TB
            Controllers["Controllers\n(src/controller/main.go, src/controller/access.go)"]:::business
            Services["Services\n(src/service/access.go)"]:::business
        end

        subgraph "Data Layer" 
            direction TB
            RepoI["Repository Interface\n(src/repository/access_interface.go)"]:::data
            RepoPG["Postgres Impl\n(src/repository/access_postgres.go)"]:::data
            RawSQL["Raw SQL\n(src/repository/sql/access_query.sql)"]:::data
            UserRepo["User Repo\n(src/repository/user.go)"]:::data
            DBInit["DB Init\n(src/db/postgres.go)"]:::data
            ORM["Ent ORM\n(ent/)"]:::data
            RepoI --> RepoPG
            RepoPG --> RawSQL
            RepoPG --> ORM
            RepoPG --> DBInit
        end

        Controllers --> Services
        Services --> RepoI
        HTTP --> Auth --> Controllers
        Services --> RepoPG
        DBInit --> ORM
        ORM --> infra_db
        RawSQL --> infra_db

        Entry --> Config --> HTTP
        Entry --> Config --> DBInit
        Entry --> Make
    end

    subgraph "Future / Batch" 
        direction TB
        Cron["Batch Processor / Cron"]:::infra
        BigQ["BigQuery"]:::data
        Cron --> BigQ
    end

    classDef presentation fill:#C3D9FF,stroke:#004080
    classDef business fill:#DFFFD6,stroke:#008000
    classDef data fill:#FFE0B2,stroke:#FF8C00
    classDef infra fill:#E0E0E0,stroke:#666666

    click Entry "https://github.com/nachoov/spl-access/blob/main/main.go"
    click HTTP "https://github.com/nachoov/spl-access/blob/main/src/server/fiber.go"
    click Config "https://github.com/nachoov/spl-access/blob/main/src/config/config.go"
    click Auth "https://github.com/nachoov/spl-access/blob/main/src/middleware/auth.go"
    click Controllers "https://github.com/nachoov/spl-access/blob/main/src/controller/main.go"
    click Controllers "https://github.com/nachoov/spl-access/blob/main/src/controller/access.go"
    click Services "https://github.com/nachoov/spl-access/blob/main/src/service/access.go"
    click RepoI "https://github.com/nachoov/spl-access/blob/main/src/repository/access_interface.go"
    click RepoPG "https://github.com/nachoov/spl-access/blob/main/src/repository/access_postgres.go"
    click RawSQL "https://github.com/nachoov/spl-access/blob/main/src/repository/sql/access_query.sql"
    click UserRepo "https://github.com/nachoov/spl-access/blob/main/src/repository/user.go"
    click DTOs "https://github.com/nachoov/spl-access/blob/main/src/dto/access.go"
    click DTOs "https://github.com/nachoov/spl-access/blob/main/src/dto/user.go"
    click DBInit "https://github.com/nachoov/spl-access/blob/main/src/db/postgres.go"
    click ORM "https://github.com/nachoov/spl-access/tree/main/ent/"
    click WS "https://github.com/nachoov/spl-access/blob/main/src/websocket/websocket.go"
    click Helpers "https://github.com/nachoov/spl-access/blob/main/src/helpers/errors.go"
    click Helpers "https://github.com/nachoov/spl-access/blob/main/src/helpers/utils.go"
    click infra_app "https://github.com/nachoov/spl-access/tree/main/Dockerfile"
    click infra_app "https://github.com/nachoov/spl-access/blob/main/Dockerfile.local"
    click infra_app "https://github.com/nachoov/spl-access/blob/main/docker-compose.yaml"
    click Make "https://github.com/nachoov/spl-access/tree/main/Makefile"
    click Make "https://github.com/nachoov/spl-access/blob/main/.air.toml"
```
