# alejandro-albiol/athenai architecture

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

- Interactive diagram: https://gitdiagram.com/alejandro-albiol/athenai
- Repository: https://github.com/alejandro-albiol/athenai

## Overview

##### Project Type and Purpose
- AthenAI is a monolithic, Go‐based full-stack application that serves a static frontend and provides RESTful API endpoints for gym management (users, gyms, admin functions) with subdomain-based multi-tenancy and JWT authentication.
- Key indicators:
- `cmd/` contains server entrypoint and DB setup utilities
- `frontend/` holds static HTML/CSS/JS
- `internal/` modules (auth, user, gym, admin) implement layered business logic
- README describes monolith, modules, OpenAPI, multi-tenant auth

##### File Structure Analysis
- Top-level directories:
- cmd – entrypoints (`main.go`, setup scripts)
- api – API router and Swagger setup
- frontend – static assets served by Go’s FileServer
- internal – private modules (auth, user, gym, admin, database)
- pkg – shared reusable code (middleware, error handling, response helpers, utils)
- config, docs, scripts – configuration, documentation, automation scripts
- Layering pattern:
- HTTP layer (routers/handlers) → Service layer (business rules) → Repository layer (DB access)
- Interfaces for each layer support loose coupling and testability
- Deployment / build artifacts:
- Air config (`.air.toml`) for live reload
- `go.mod`, `go.sum`, Dockerfile (if any) / scripts for DB and tenant cleanup

##### README Insights
- Monolithic frontend + backend, served from same Go binary
- JWT-based auth with middleware extracting subdomain and routing to correct schema
- Modules: auth, user, gym, admin each with DTOs, interfaces, handlers, services, repositories
- OpenAPI 3 specification split into components and paths under `docs/openapi/`

a. Main Components
- Clients: Web Browser (static UI)
- HTTP Server (Go binary)
- API Router (api/api.go + versioned routes `/api/v1/...`)
- Static File Server (serving `frontend/`)
- Modules:
– Auth Module (middleware, handlers, services, repo)
– User Module
– Gym Module
– Admin Module
- Shared Packages: Middleware (`pkg/middleware`), Error Handling (`pkg/apierror`), Response (`pkg/response`), Utils
- Database: PostgreSQL with public schema (platform admin) + tenant schemas per gym
- External Docs: Swagger UI (`/swagger-ui/`) serving OpenAPI spec
b. Relationships & Interactions
- Browser → HTTP Server
– `/` → Static files
– `/api/v1/...` → API Router
- API Router → Module Routers (auth, user, gym, admin)
- Module Router → Handler → Service → Repository
- Repository → Database
- Middleware runs before handlers to:
– authenticate JWT
– extract subdomain (tenant) and select DB schema
- Swagger UI fetches `/docs/openapi/openapi.yaml`
c. Architectural Patterns
- Layered (Controller → Service → Repository)
- Modular Monolith (domain modules under `internal/`)
- Dependency Injection via Interfaces
- Subdomain-based Multi-Tenancy
- Static File Serving in same process
d. Technologies & Frameworks
- Go 1.19+ standard library (net/http)
- Air for live reload (`.air.toml`)
- PostgreSQL (multi-schema tenancy)
- OpenAPI 3.0 + Swagger (`api/swagger.go`, `docs/openapi/`)
- PowerShell scripts for Windows automation (in `scripts/`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Browser["Web Browser"]:::external
    SwaggerUI["Swagger UI"]:::external

    %% Go Application
    subgraph "Go Application" 
        direction TB
        subgraph "Entrypoints" 
            direction TB
            Main["HTTP Server Entrypoint\n(cmd/main.go)"]:::infra
            SetupDB["Setup DB\n(cmd/setup-db/main.go)"]:::infra
            MigrateRT["Migrate Refresh Tokens\n(cmd/migrate-refresh-tokens/main.go)"]:::infra
            SetupSA["Setup Superadmin\n(cmd/setup-superadmin/main.go)"]:::infra
            CleanupTenant["Cleanup Tenant\n(cmd/cleanup-tenant/main.go)"]:::infra
        end

        subgraph "Static File Server" 
            direction TB
            StaticFS["Serve Static Files\n(frontend/)"]:::frontend
        end

        subgraph "API Layer"
            direction TB
            SwaggerSetup["Swagger Setup\n(api/swagger.go)"]:::api
            APIRouter["API Router\n(api/api.go)"]:::api

            subgraph "Middleware"
                direction TB
                JWTAuth["JWT Auth\n(pkg/middleware/auth.go)"]:::shared
                TenantExt["Tenant Extraction\n(pkg/middleware/gym.go)"]:::shared
            end

            subgraph "Modules"
                direction TB
                subgraph "Auth Module"
                    direction TB
                    AuthRouter["Auth Router\n(internal/auth/router/auth_router.go)"]:::logic
                    AuthHandler["Auth Handler\n(internal/auth/handler/auth_handler.go)"]:::logic
                    AuthService["Auth Service\n(internal/auth/service/auth_service.go)"]:::logic
                    AuthRepo["Auth Repository\n(internal/auth/repository/auth_repository.go)"]:::data
                end
                subgraph "User Module"
                    direction TB
                    UserRouter["User Router\n(internal/user/router/user_router.go)"]:::logic
                    UserHandler["User Handler\n(internal/user/handler/user_handler.go)"]:::logic
                    UserService["User Service\n(internal/user/service/users_service.go)"]:::logic
                    UserRepo["User Repository\n(internal/user/repository/user_repository.go)"]:::data
                end
                subgraph "Gym Module"
                    direction TB
                    GymRouter["Gym Router\n(internal/gym/router/gym_router.go)"]:::logic
                    GymHandler["Gym Handler\n(internal/gym/handler/gym_handler.go)"]:::logic
                    GymService["Gym Service\n(internal/gym/service/gym_service.go)"]:::logic
                    GymRepo["Gym Repository\n(internal/gym/repository/gym_repository.go)"]:::data
                end
                subgraph "Admin Module"
                    direction TB
                    AdminInterface["Admin Repo Interface\n(internal/admin/interfaces/admin_repository.interface.go)"]:::logic
                    AdminRepoImpl["Admin Repo Impl\n(internal/admin/repository/admin_repository.go)"]:::data
                end
            end
        end

        subgraph "Shared Libraries"
            direction TB
            APIError["Error Handling\n(pkg/apierror/api_error.go)"]:::shared
            APIResp["Response Helpers\n(pkg/response/api_response.go)"]:::shared
            Utils["Utilities\n(pkg/utils/nullable_string.go)"]:::shared
        end

        subgraph "Database Layer"
            direction TB
            DBConn["PostgreSQL Conn\n(internal/database/psql_connection.go)"]:::data
            PublicSchema["Public Schema Logic\n(internal/database/public.go)"]:::data
            Tenancy["Tenant Schema Middleware\n(internal/database/tenancy.go)"]:::data
        end
    end

    subgraph "Documentation"
        direction TB
        OpenAPI["OpenAPI Spec\n(docs/openapi/openapi.yaml)"]:::infra
        Components["Components\n(docs/openapi/components/)"]:::infra
        Paths["Paths\n(docs/openapi/paths/)"]:::infra
    end

    %% Flows
    Browser -->|"/"| StaticFS
    Browser -->|"GET /swagger-ui/"| SwaggerUI
    Browser -->|"GET /api/v1/*"| APIRouter

    SwaggerUI -->|fetch openapi.yaml| OpenAPI

    APIRouter -->|uses| SwaggerSetup
    APIRouter -->|routes to| AuthRouter
    APIRouter -->|routes to| UserRouter
    APIRouter -->|routes to| GymRouter
    APIRouter -->|routes to| AdminInterface

    AuthRouter --> JWTAuth --> TenantExt --> AuthHandler --> AuthService --> AuthRepo --> DBConn
    UserRouter --> JWTAuth --> TenantExt --> UserHandler --> UserService --> UserRepo --> DBConn
    GymRouter --> JWTAuth --> TenantExt --> GymHandler --> GymService --> GymRepo --> DBConn
    AdminInterface --> JWTAuth --> TenantExt --> AdminRepoImpl --> DBConn

    Main --> StaticFS
    Main --> APIRouter
    Main --> DBConn

    DBConn --> PublicSchema
    DBConn --> Tenancy

    APIError --> AuthHandler
    APIError --> UserHandler
    APIError --> GymHandler
    APIError --> AdminRepoImpl

    APIResp --> AuthHandler
    APIResp --> UserHandler
    APIResp --> GymHandler
    APIResp --> AdminRepoImpl

    Utils --> AuthService
    Utils --> UserService
    Utils --> GymService

    SetupDB --> DBConn
    MigrateRT --> DBConn
    SetupSA --> DBConn
    CleanupTenant --> DBConn

    %% Click Events
    click Main "https://github.com/alejandro-albiol/athenai/blob/main/cmd/main.go"
    click SetupDB "https://github.com/alejandro-albiol/athenai/blob/main/cmd/setup-db/main.go"
    click MigrateRT "https://github.com/alejandro-albiol/athenai/blob/main/cmd/migrate-refresh-tokens/main.go"
    click SetupSA "https://github.com/alejandro-albiol/athenai/blob/main/cmd/setup-superadmin/main.go"
    click CleanupTenant "https://github.com/alejandro-albiol/athenai/blob/main/cmd/cleanup-tenant/main.go"
    click APIRouter "https://github.com/alejandro-albiol/athenai/blob/main/api/api.go"
    click SwaggerSetup "https://github.com/alejandro-albiol/athenai/blob/main/api/swagger.go"
    click StaticFS "https://github.com/alejandro-albiol/athenai/tree/main/frontend/"
    click AuthRouter "https://github.com/alejandro-albiol/athenai/blob/main/internal/auth/router/auth_router.go"
    click AuthHandler "https://github.com/alejandro-albiol/athenai/blob/main/internal/auth/handler/auth_handler.go"
    click AuthService "https://github.com/alejandro-albiol/athenai/blob/main/internal/auth/service/auth_service.go"
    click AuthRepo "https://github.com/alejandro-albiol/athenai/blob/main/internal/auth/repository/auth_repository.go"
    click UserRouter "https://github.com/alejandro-albiol/athenai/blob/main/internal/user/router/user_router.go"
    click UserHandler "https://github.com/alejandro-albiol/athenai/blob/main/internal/user/handler/user_handler.go"
    click UserService "https://github.com/alejandro-albiol/athenai/blob/main/internal/user/service/users_service.go"
    click UserRepo "https://github.com/alejandro-albiol/athenai/blob/main/internal/user/repository/user_repository.go"
    click GymRouter "https://github.com/alejandro-albiol/athenai/blob/main/internal/gym/router/gym_router.go"
    click GymHandler "https://github.com/alejandro-albiol/athenai/blob/main/internal/gym/handler/gym_handler.go"
    click GymService "https://github.com/alejandro-albiol/athenai/blob/main/internal/gym/service/gym_service.go"
    click GymRepo "https://github.com/alejandro-albiol/athenai/blob/main/internal/gym/repository/gym_repository.go"
    click AdminInterface "https://github.com/alejandro-albiol/athenai/blob/main/internal/admin/interfaces/admin_repository.interface.go"
    click AdminRepoImpl "https://github.com/alejandro-albiol/athenai/blob/main/internal/admin/repository/admin_repository.go"
    click JWTAuth "https://github.com/alejandro-albiol/athenai/blob/main/pkg/middleware/auth.go"
    click TenantExt "https://github.com/alejandro-albiol/athenai/blob/main/pkg/middleware/gym.go"
    click APIError "https://github.com/alejandro-albiol/athenai/blob/main/pkg/apierror/api_error.go"
    click APIResp "https://github.com/alejandro-albiol/athenai/blob/main/pkg/response/api_response.go"
    click Utils "https://github.com/alejandro-albiol/athenai/blob/main/pkg/utils/nullable_string.go"
    click DBConn "https://github.com/alejandro-albiol/athenai/blob/main/internal/database/psql_connection.go"
    click PublicSchema "https://github.com/alejandro-albiol/athenai/blob/main/internal/database/public.go"
    click Tenancy "https://github.com/alejandro-albiol/athenai/blob/main/internal/database/tenancy.go"
    click OpenAPI "https://github.com/alejandro-albiol/athenai/blob/main/docs/openapi/openapi.yaml"
    click Components "https://github.com/alejandro-albiol/athenai/tree/main/docs/openapi/components/"
    click Paths "https://github.com/alejandro-albiol/athenai/tree/main/docs/openapi/paths/"

    %% Styles
    classDef external fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef infra fill:#d7ccc8,stroke:#4e342e,color:#4e342e
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef api fill:#ffe0b2,stroke:#e65100,color:#e65100
    classDef shared fill:#ffccbc,stroke:#bf360c,color:#bf360c
    classDef logic fill:#e1bee7,stroke:#4a148c,color:#4a148c
    classDef data fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
```
