# enclaverunner/api-server architecture

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

- Interactive diagram: https://gitdiagram.com/enclaverunner/api-server
- Repository: https://github.com/enclaverunner/api-server

## Overview

##### Project Type and Purpose
- This is a Go-based, OpenAPI-driven backend service (“API server”) for managing secure enclave resources.
- It generates both server stubs and client code from an OpenAPI spec (openapi.yml) and implements persistence via an internal ORM layer.

##### File Structure Analysis
- Top-level:
- main.go: application entry point
- api/: generated server interface (gen.go) + business logic implementations (impl.go, rbac.go, users.go)
- orm/: database abstraction (init, model definitions, auth, users, error handling)
- client/: generated Go client (client.gen.go)
- config/: runtime configuration loader
- openapi.yml + oapi-codegen-*.yml: OpenAPI spec + codegen configuration
- Dockerfile, docker-compose.test.yml: container and test orchestration
- .github/workflows: CI, image promotion, releases, OpenAPI sync
- The Makefile and tools.go orchestrate codegen, linting, testing, and build targets.
- Nix flake files indicate reproducible dev/test environments.

##### README Insights
- Very concise: “API server provides secure endpoints for managing enclave resources and operations.”
- Implies strict security, RBAC, user management.

##### Main Components
a. OpenAPI Spec & Codegen
- Input: openapi.yml
- Codegen tools: oapi-codegen (server + client)
- Outputs: api/gen.go (server interfaces), client/client.gen.go (client SDK)
b. API Layer (Handlers & RBAC)
- api/impl.go: concrete handler implementations
- api/rbac.go: access control rules
- api/users.go: user-related endpoints
c. ORM / Persistence
- orm/init.go: DB connection bootstrap
- orm/model.go: entity definitions
- orm/auth.go, orm/users.go: data access methods
d. Configuration & Startup
- config/config.go: reads env, files, flags
- main.go: wires config, DB, router, middleware, starts HTTP server
e. External Dependencies
- Relational database (e.g. Postgres)
- External services (if any) called by handlers
f. Dev/Ops Tooling (Auxiliary)
- Docker image build & Docker Compose for integration tests
- GitHub Actions workflows for CI/CD
- Nix flake for reproducible environment

##### Relationships & Data Flow
- Developers edit openapi.yml → run Makefile/tooling → regenerate API & client code
- main.go initializes config → connects to DB via orm/init.go → sets up HTTP router using generated API interfaces
- Incoming HTTP request → API handler (impl.go) → RBAC check (rbac.go) → ORM call (e.g. orm/users.go) → DB → return data → API layer serializes JSON → HTTP response
- Client code (client/client.gen.go) calls the same openapi-defined endpoints.

##### Architectural Patterns & Principles
- API-first design via OpenAPI
- Clear separation of concerns:
- Spec & codegen
- Handler layer (business logic + RBAC)
- Data access layer (ORM)
- Configuration & bootstrapping
- CI/CD pipelines enforce code generation, linting, tests, and release workflows.

##### Detailed Elements
- Spec & codegen workflow
- API interface vs implementation
- RBAC enforcement as middleware
- ORM’s role in persistence
- Configuration injection in main
- CI/CD (GitHub Actions) and containerization pipelines

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Spec & Codegen
    subgraph "Spec & Codegen"
        direction TB
        OpenAPI["openapi.yml"]:::speccolor
        CodegenServerCfg["oapi-codegen-server.yml"]:::speccolor
        CodegenClientCfg["oapi-codegen-client.yml"]:::speccolor
        OapiTargets["oapi.targets"]:::speccolor
        GenServer["api/gen.go"]:::speccolor
        GenClient["client/client.gen.go"]:::speccolor
    end

    %% Server Layer
    subgraph "Server (API Layer)"
        direction TB
        GenServer --> Impl["api/impl.go"]:::servercolor
        Impl --> RBAC["api/rbac.go"]:::servercolor
        Impl --> UsersAPI["api/users.go"]:::servercolor
    end

    %% Client SDK
    subgraph "Client SDK"
        direction TB
        GenClient
    end

    %% Configuration & Startup
    subgraph "Configuration & Startup"
        direction TB
        Config["config/config.go"]:::configcolor
        Main["main.go"]:::configcolor
        Main --> Config
    end

    %% ORM / Persistence
    subgraph "ORM / Persistence"
        direction TB
        ORMInit["orm/init.go"]:::ormcolor
        Model["orm/model.go"]:::ormcolor
        AuthDAO["orm/auth.go"]:::ormcolor
        UsersDAO["orm/users.go"]:::ormcolor
        ORMErr["orm/errors.go"]:::ormcolor
        ORMInit --> Model
        Model --> AuthDAO
        Model --> UsersDAO
        AuthDAO --> ORMErr
        UsersDAO --> ORMErr
    end

    %% Database
    DB[(Database)]:::dbcolor

    %% HTTP Flow
    ExternalClient{{"HTTP Client"}}:::externalcolor
    ExternalClient -->|HTTP request| Router["HTTP Router"]:::servercolor
    Router --> Impl
    Impl -->|"RBAC check"| RBAC
    RBAC --> AuthDAO
    RBAC --> UsersDAO
    AuthDAO --> DB
    UsersDAO --> DB
    DB -->|"data"| Impl
    Impl -->|"HTTP response"| ExternalClient

    %% Startup Flow
    Main -->|"init DB"| ORMInit
    Main -->|"setup router"| Router

    %% Spec & codegen flow
    OpenAPI -->|defines API| CodegenServerCfg
    OpenAPI -->|defines API| CodegenClientCfg
    CodegenServerCfg -->|generates| GenServer
    CodegenClientCfg -->|generates| GenClient
    OapiTargets -->|Makefile| GenServer
    OapiTargets -->|Makefile| GenClient

    %% Client usage
    DevApp["Client Application"]:::clientcolor
    DevApp -->|uses SDK| GenClient

    %% Dev/Ops Tooling
    subgraph "Dev/Ops Tooling"
        direction TB
        DockerfileNode["Dockerfile"]:::devopscolor
        Compose["docker-compose.test.yml"]:::devopscolor
        IntegrationTest["integration_test.go"]:::devopscolor
        MakefileNode["Makefile"]:::devopscolor
        Tools["tools.go"]:::devopscolor
        CI1[".github/workflows/ci.yml"]:::devopscolor
        CI2[".github/workflows/promote-image.yml"]:::devopscolor
        CI3[".github/workflows/release.yml"]:::devopscolor
        CI4[".github/workflows/sync-oapi.yml"]:::devopscolor
        CI5[".github/workflows/testing.yml"]:::devopscolor
        FlakeNix["flake.nix"]:::devopscolor
        FlakeLock["flake.lock"]:::devopscolor
    end

    %% Click Events
    click OpenAPI "https://github.com/enclaverunner/api-server/blob/main/openapi.yml"
    click CodegenServerCfg "https://github.com/enclaverunner/api-server/blob/main/oapi-codegen-server.yml"
    click CodegenClientCfg "https://github.com/enclaverunner/api-server/blob/main/oapi-codegen-client.yml"
    click OapiTargets "https://github.com/enclaverunner/api-server/blob/main/oapi.targets"
    click GenServer "https://github.com/enclaverunner/api-server/blob/main/api/gen.go"
    click GenClient "https://github.com/enclaverunner/api-server/blob/main/client/client.gen.go"
    click Impl "https://github.com/enclaverunner/api-server/blob/main/api/impl.go"
    click RBAC "https://github.com/enclaverunner/api-server/blob/main/api/rbac.go"
    click UsersAPI "https://github.com/enclaverunner/api-server/blob/main/api/users.go"
    click ORMInit "https://github.com/enclaverunner/api-server/blob/main/orm/init.go"
    click Model "https://github.com/enclaverunner/api-server/blob/main/orm/model.go"
    click AuthDAO "https://github.com/enclaverunner/api-server/blob/main/orm/auth.go"
    click UsersDAO "https://github.com/enclaverunner/api-server/blob/main/orm/users.go"
    click ORMErr "https://github.com/enclaverunner/api-server/blob/main/orm/errors.go"
    click Config "https://github.com/enclaverunner/api-server/blob/main/config/config.go"
    click Main "https://github.com/enclaverunner/api-server/blob/main/main.go"
    click DockerfileNode "https://github.com/enclaverunner/api-server/tree/main/Dockerfile"
    click Compose "https://github.com/enclaverunner/api-server/blob/main/docker-compose.test.yml"
    click IntegrationTest "https://github.com/enclaverunner/api-server/blob/main/integration_test.go"
    click MakefileNode "https://github.com/enclaverunner/api-server/tree/main/Makefile"
    click Tools "https://github.com/enclaverunner/api-server/blob/main/tools.go"
    click CI1 "https://github.com/enclaverunner/api-server/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/enclaverunner/api-server/blob/main/.github/workflows/promote-image.yml"
    click CI3 "https://github.com/enclaverunner/api-server/blob/main/.github/workflows/release.yml"
    click CI4 "https://github.com/enclaverunner/api-server/blob/main/.github/workflows/sync-oapi.yml"
    click CI5 "https://github.com/enclaverunner/api-server/blob/main/.github/workflows/testing.yml"
    click FlakeNix "https://github.com/enclaverunner/api-server/blob/main/flake.nix"
    click FlakeLock "https://github.com/enclaverunner/api-server/blob/main/flake.lock"

    %% Styles
    classDef speccolor fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef servercolor fill:#E6FFFA,stroke:#2C7A7B,color:#2C7A7B
    classDef clientcolor fill:#FFF5E6,stroke:#DD6B20,color:#DD6B20
    classDef configcolor fill:#EBF4FF,stroke:#3182CE,color:#3182CE
    classDef ormcolor fill:#FEFCBF,stroke:#D69E2E,color:#D69E2E
    classDef dbcolor fill:#F7FAFC,stroke:#4A5568,color:#4A5568
    classDef devopscolor fill:#F5E6FF,stroke:#805AD5,color:#805AD5
    classDef externalcolor fill:#EDF2F7,stroke:#4A5568,color:#4A5568
```
