# tensorplex-labs/dojo-worker-api architecture

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

- Interactive diagram: https://gitdiagram.com/tensorplex-labs/dojo-worker-api
- Repository: https://github.com/tensorplex-labs/dojo-worker-api

## Overview

##### Main Components
- Microservices: The repository contains multiple microservices such as:
– The main API server (located at cmd/server): This service likely acts as the central API endpoint.
– AWS integration service (cmd/aws) for cloud-specific operations.
– SIWS service (cmd/siws) for blockchain or smart contract related operations.
– Seeder service (cmd/seed) for data initialization (evidenced by fixture files and JSON seed data).
- Core Functionality Modules: Under pkg, you have several modular components including:
– API components (pkg/api) that involve controllers, middleware, routing, and rate limiting.
– Authentication (pkg/auth) and blockchain integrations (pkg/blockchain) which include SIWS logic.
– ORM packages (pkg/orm) managing database interactions (aligned with the Prisma schema and migrations).
– Additional helper services for caching, emailing, events, metrics, sandboxing, task processing, and worker management.
- Database: A PostgreSQL instance is expected (as indicated by the docker-compose and instructions for setting up a local Postgres instance).
- External Tools & Libraries:
– Swagger for API documentation (see gin-swagger annotations and usage).
– Docker & Docker Compose for containerizing local environments and running the database.
– Prisma (schema.prisma, Dockerfile.prisma, migrations) for data modeling and database operations.

##### Relationships and Interactions
- Clients (e.g., REST client, browser, or automated clients) send HTTP requests to the main API service (cmd/server).
- The API service relies on internal controllers, middleware, and routes defined in pkg/api to process these requests.
- Depending on the request, the API service interacts with underlying modules like authentication (pkg/auth), blockchain (pkg/blockchain), and task management (pkg/task).
- These business logic components in turn use ORM (pkg/orm) for database operations which communicate with the PostgreSQL instance.
- Other supporting functionalities include caching, emailing, and event services, which may interact with external systems (like an email service provider or cloud services via the AWS microservice).
- The SIWS component (under both cmd/siws and pkg/blockchain/siws) handles blockchain identity aspects.
- The Swagger documentation is generated and served through the API (as part of cmd/server), allowing interactive API testing and reference.

##### Architectural Patterns and Design Principles
- Microservice Structure: The use of multiple “cmd” directories suggests that each service is standalone yet shares common libraries (found under pkg) ensuring code reuse.
- Separation of Concerns: By dividing authentication, blockchain, ORM, and various utility functions into distinct packages, the design is modular and easier to maintain.
- API Documentation Integration: Use of swagger annotations and generated documentation reinforces good practices in API clarity and consistency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client("Client"):::client

    %% Microservices Layer
    subgraph "Microservices"
        API_Gateway["API Gateway / Main Server<br/>(cmd/server)"]:::microservices
        AWS["AWS Integration Service<br/>(cmd/aws)"]:::microservices
        Seeder["Seeder Service<br/>(cmd/seed)"]:::microservices
        SIWS["SIWS Service<br/>(cmd/siws)"]:::microservices
    end

    %% Seeder Service Details
    subgraph "Seeder Details"
        Seeder_Main["main.go"]:::details
        Seeder_Fixtures["Fixtures Directory"]:::details
        Seeder_Task["Task Data (JSON)"]:::details
    end

    %% Core Modules Layer
    subgraph "Core Modules"
        API_Components["API Components<br/>(pkg/api)"]:::core
        Auth["Authentication<br/>(pkg/auth)"]:::core
        Blockchain["Blockchain Integration<br/>(pkg/blockchain)"]:::core
        ORM["ORM/Data Access<br/>(pkg/orm)"]:::core
        Cache["Caching Service<br/>(pkg/cache)"]:::core
        Email["Email Service<br/>(pkg/email)"]:::core
        Event["Event Service<br/>(pkg/event)"]:::core
        Metric["Metrics Service<br/>(pkg/metric)"]:::core
        Task["Task Management<br/>(pkg/task)"]:::core
        Worker["Worker Management<br/>(pkg/worker)"]:::core
        Sandbox["Sandboxing Utility<br/>(pkg/sandbox)"]:::core
        SIWS_Core["SIWS Module<br/>(pkg/blockchain/siws)"]:::core
    end

    %% Infrastructure & External Tools Layer
    subgraph "Infrastructure & External Tools"
        Database[(Database: PostgreSQL)]:::infra
        Prisma["Prisma & Migrations"]:::infra
        Swagger["API Documentation<br/>(Swagger)"]:::infra
        Docker["Docker & Docker Compose"]:::infra
    end

    %% Data Flow Connections
    Client -->|"HTTPRequest"| API_Gateway
    API_Gateway -->|"Uses"| API_Components
    API_Gateway -->|"Calls"| AWS
    API_Gateway -->|"Triggers"| SIWS
    API_Gateway -->|"Initiates"| Seeder
    API_Gateway -->|"ServesDocs"| Swagger

    API_Components -->|"AuthCheck"| Auth
    API_Components -->|"BlockchainCall"| Blockchain
    API_Components -->|"ManageTask"| Task
    API_Components -->|"DBOps"| ORM

    Auth --> ORM
    Blockchain --> ORM
    SIWS --> SIWS_Core
    Task --> ORM
    Email -->|"Notifies"| Database
    Cache --> ORM
    Event --> ORM
    Metric --> ORM
    Worker --> ORM
    Sandbox --> ORM

    ORM -->|"CRUD"| Database

    %% Infrastructure and Environment Provisioning
    Docker --> Prisma
    Prisma --> Database

    %% Seeder Details Connections
    Seeder --> Seeder_Main
    Seeder --> Seeder_Fixtures
    Seeder --> Seeder_Task

    %% Additional Interactions
    AWS -->|"CloudOps"| Database

    %% Click Events
    click API_Gateway "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/cmd/server/main.go"
    click AWS "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/cmd/aws/main.go"
    click Seeder_Main "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/cmd/seed/main.go"
    click Seeder_Fixtures "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/cmd/seed/fixtures"
    click Seeder_Task "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/cmd/seed/task_data.json"
    click SIWS "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/cmd/siws/main.go"
    click SIWS_Core "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/blockchain/siws"
    click API_Components "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/api"
    click Auth "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/auth"
    click Blockchain "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/blockchain"
    click ORM "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/orm"
    click Cache "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/pkg/cache/cache.go"
    click Email "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/pkg/email/send_email.go"
    click Event "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/event"
    click Metric "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/metric"
    click Task "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/pkg/task"
    click Worker "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/pkg/worker/model.go"
    click Sandbox "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/pkg/sandbox/selfhostedsandbox_func.go"
    click Database "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/docker-compose.yml"
    click Prisma "https://github.com/tensorplex-labs/dojo-worker-api/blob/main/schema.prisma"
    click Swagger "https://github.com/tensorplex-labs/dojo-worker-api/tree/main/docs"

    %% Styles
    classDef microservices fill:#bbdefb,stroke:#1565c0,stroke-width:2px;
    classDef core fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef infra fill:#ffcdd2,stroke:#c62828,stroke-width:2px;
    classDef details fill:#e1bee7,stroke:#6a1b9a,stroke-width:2px;
    classDef client fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
```
