# wanderer-moe/api architecture

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

- Interactive diagram: https://gitdiagram.com/wanderer-moe/api
- Repository: https://github.com/wanderer-moe/api

## Overview

##### Project Type and Purpose
- This is a serverless API built for Cloudflare Workers with an emphasis on servicing game data (and some Discord functionality). It leverages R2 for storage, meaning that part of the architecture involves object storage/CDN.
- The README clearly mentions usage instructions via Wrangler and automated deployments with GitHub Actions, so there is also a CI/CD pipeline component to the overall design.

##### Analyzing the File Structure
- The top-level includes configuration files (e.g., wrangler.toml, package.json, tsconfig.json) which tell us this is a TypeScript project configured for Cloudflare Workers.
- The “src” folder is the core of the application, with:
- “handler.ts” and “index.ts” likely representing the entry point for the worker.
- “routes” directory subdivided into “discord” and “games” – these directories encapsulate the API endpoints.
- “middleware” (e.g., errorHandler.ts) that handles error processing for the API endpoints.
- “lib” provides helper functions, type definitions, and possibly logic for integrating with external services (like Discord) or handling operations specific to the game data.
- The presence of GitHub Actions in the .github/workflows folder shows that there is an automated deployment pipeline that deploys to Cloudflare Workers on pushes to the main branch.

a. Main Components:
- Cloudflare Worker: Acts as the serverless compute layer hosting and running the API.
- API Endpoints: Split into two main groups – Games (routes like list-games, get-game-id, etc.) and Discord (routes like changelog, contributors, members).
- Cloudflare R2 Storage: Serves as the storage layer for CDN assets and possibly other asset management, as indicated by the README.
- Middleware Layer: Error handling and potential authentication or request preprocessing.
- CI/CD Pipeline: GitHub Actions for automatic deployment based on changes pushed to the repository.
- Supporting Libraries/Helpers: Utility functions for Discord integration, asset management, etc.

b. Relationships and Interactions:
- Incoming HTTP requests hit the Cloudflare Worker (possibly with an edge-optimized URL like api.wanderer.moe).
- The Worker’s routing layer, based on the “src/routes” structure, directs requests to the correct handler (Games or Discord).
- Middleware (e.g., error handler) processes requests and responses, ensuring errors are caught and dealt with.
- For certain endpoints that require stored assets or CDN responses, the worker interacts with the Cloudflare R2 Storage.
- Auxiliary helper libraries within “src/lib” provide functionality needed for processing requests (e.g., renaming assets, preparing proper response headers, or integrating with Discord).
- CI/CD components (via GitHub Actions in .github/workflows) automatically test and deploy changes to the live Cloudflare Worker environment.

c. Important Architectural Patterns/Design Principles:
- Modular Design: Separation of concerns is clear with distinct directories for routes, middleware, and libraries.
- Serverless Architecture: The use of Cloudflare Workers implies a stateless execution environment.
- Micro-routing: A directory-based routing system (with separate modules for games and discord) ensures that each endpoint’s logic is isolated.
- Automated Deployment: GitHub Actions and Wrangler configuration facilitate CI/CD best practices.

d. Relevant Technologies, Frameworks, or Libraries:
- Cloudflare Workers for serverless compute.
- Cloudflare R2 Storage for asset management/CDN purposes.
- TypeScript as the programming language.
- Wrangler as the CLI tool for Cloudflare deployments.
- GitHub Actions for continuous integration and deployment.
- ESLint and Prettier (as indicated by configuration files) ensure code quality and consistency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global HTTP nodes
    HTTP["HTTP Request"]:::external
    HTTPResponse["HTTP Response"]:::external

    %% Cloudflare Worker - Entry Point
    CFWorker["Cloudflare Worker"]:::worker

    %% Middleware
    Middleware["Middleware: Error Handling"]:::middleware

    %% API Endpoints Subgraphs
    subgraph "API Endpoints"
        subgraph "Games API"
            G1["Get Game Category"]:::api
            G2["Get Game ID"]:::api
            G3["List Games"]:::api
        end
        subgraph "Discord API"
            D1["Changelog"]:::api
            D2["Contributors"]:::api
            D3["Members"]:::api
        end
    end

    %% Cloudflare R2 Storage
    R2Storage["Cloudflare R2 Storage"]:::storage

    %% Helper Libraries / Utilities
    subgraph "Helper Libraries"
        GH["General Helpers"]:::helpers
        DI["Discord Integration"]:::helpers
        LB["List Bucket"]:::helpers
        RH["Response Headers"]:::helpers
        AT["Asset Type"]:::helpers
        DT["Discord Type"]:::helpers
        GT["Game Type"]:::helpers
    end

    %% CI/CD Pipeline
    CICD["CI/CD Pipeline (GitHub Actions)"]:::cicd

    %% Connections - Vertical Flow
    HTTP --> CFWorker
    CFWorker --> Middleware
    Middleware -->|"routes-to"| G1
    Middleware -->|"routes-to"| D1

    %% Chain games endpoints
    G1 -.->|"then"| G2
    G2 -.->|"then"| G3
    %% Chain discord endpoints
    D1 -.->|"then"| D2
    D2 -.->|"then"| D3

    %% Endpoints send response back to Worker
    G3 --> CFWorker
    D3 --> CFWorker

    %% Cloudflare Worker interacts with external storage and helpers
    CFWorker -->|"fetches assets"| R2Storage
    CFWorker -.-> GH

    %% Final response to client
    CFWorker --> HTTPResponse

    %% CI/CD deployment pipeline
    CICD -->|"deploys to"| CFWorker

    %% Styles
    classDef worker fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef middleware fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef api fill:#ffcdd2,stroke:#c62828,stroke-width:2px;
    classDef storage fill:#d1c4e9,stroke:#673ab7,stroke-width:2px;
    classDef cicd fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef helpers fill:#f0f4c3,stroke:#827717,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#424242,stroke-width:2px;

    %% Click Events for Cloudflare Worker
    click CFWorker "https://github.com/wanderer-moe/api/blob/main/src/handler.ts"
    click CFWorker "https://github.com/wanderer-moe/api/blob/main/src/index.ts"

    %% Click Events for Games API Endpoints
    click G1 "https://github.com/wanderer-moe/api/blob/main/src/routes/games/get-game-category.ts"
    click G2 "https://github.com/wanderer-moe/api/blob/main/src/routes/games/get-game-id.ts"
    click G3 "https://github.com/wanderer-moe/api/blob/main/src/routes/games/list-games.ts"

    %% Click Events for Discord API Endpoints
    click D1 "https://github.com/wanderer-moe/api/blob/main/src/routes/discord/changelog.ts"
    click D2 "https://github.com/wanderer-moe/api/blob/main/src/routes/discord/contributors.ts"
    click D3 "https://github.com/wanderer-moe/api/blob/main/src/routes/discord/members.ts"

    %% Click Event for Middleware
    click Middleware "https://github.com/wanderer-moe/api/blob/main/src/middleware/errorHandler.ts"

    %% Click Events for Helper Libraries
    click GH "https://github.com/wanderer-moe/api/blob/main/src/lib/helpers/rename.ts"
    click DI "https://github.com/wanderer-moe/api/blob/main/src/lib/discord.ts"
    click LB "https://github.com/wanderer-moe/api/blob/main/src/lib/listBucket.ts"
    click RH "https://github.com/wanderer-moe/api/blob/main/src/lib/responseHeaders.ts"
    click AT "https://github.com/wanderer-moe/api/blob/main/src/lib/types/asset.ts"
    click DT "https://github.com/wanderer-moe/api/blob/main/src/lib/types/discord.ts"
    click GT "https://github.com/wanderer-moe/api/blob/main/src/lib/types/game.ts"

    %% Click Events for CI/CD Pipeline
    click CICD "https://github.com/wanderer-moe/api/blob/main/.github/workflows/check.yml"
    click CICD "https://github.com/wanderer-moe/api/blob/main/.github/workflows/deploy.yml"
```
