# ungdev/ua-api architecture

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

- Interactive diagram: https://gitdiagram.com/ungdev/ua-api
- Repository: https://github.com/ungdev/ua-api

## Overview

Based on our analysis of both the file tree and the README, this project is a backend API designed to serve the UTTArena services. It is a Node.js application written in TypeScript that leverages Prisma as its ORM to interact with a MySQL/MariaDB database. The code is organized following layered design principles and loosely follows an MVC structure through its controllers, middleware, and services, with additional operational logic housed in a dedicated “operations” layer.

##### Main Components
a. API Layer (Controllers):
- Numerous endpoints found in the “src/controllers” folder. Notice that there are separate subdirectories for “admin”, “auth”, “discord”, “teams”, “stripe”, etc. Each group handles a specific part of the overall API (e.g., user authentication, admin tasks, third-party integrations).
b. Middleware Layer:
- In “src/middlewares”, various middlewares (authentication, error handling, rate limiting, etc.) process incoming requests before they reach the controllers.
c. Service Layer:
- Under “src/services”, services abstract external communications and core functionalities (e.g., database access via Prisma in “database.ts”, email handling in “services/email”, Discord interaction in “services/discord”, Slack integration).
d. Operations Layer:
- The “src/operations” folder encapsulates business logic that ties multiple components together (for example, operations for carts, items, and tournaments).
e. Database and ORM:
- The presence of “schema.prisma” and seed SQL files indicates that Prisma is used to manage a MySQL/MariaDB database. Show this as a distinct storage component.
f. Utilities:
- “src/utils” contains helper functions (logging, network requests, validators, etc.) which support multiple layers.
g. External Services:
- The controllers and services reference third-party APIs (Discord, Stripe, Slack, Email providers). Mark these as external integrations.
h. Client / API Consumers:
- Although not part of the code per se, illustrate that the API interacts with various clients (web apps, mobile apps, or other services) through HTTP requests.

##### Relationships and Data Flows
- Out how client requests enter through an API gateway (or directly to the Node.js server as represented by “src/server.ts” and “src/app.ts”).
- From the middleware layer, show routing of requests to the appropriate controllers (for example, “admin/auth”, “auth”, “teams”).

##### Architectural Patterns/Design Principles
- Many controllers include “openapi.yml” files which imply a contract-based design for APIs. You might annotate that the system adheres to API documentation standards.
- Separation of concerns by clearly demarcating components like admin functionality versus public user functionality.

##### Relevant Technologies/Frameworks
- Node.js and TypeScript form the backend runtime and language.
- Prisma serves as the ORM for database interactions.
- External APIs include Discord, Stripe, and Slack integrations.
- Testing is supported via a robust test structure found in the “tests” folder (using Mocha, as hinted by the “.mocharc.yml”).
- Docker and GitHub workflows are configured for containerization and CI/CD.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Client["Client / API Consumer"]:::external
    NodeServer["Node.js Server (src/server.ts/app.ts)"]:::server

    %% Layers
    subgraph "Presentation Layer"
        Controllers["API Controllers (src/controllers)"]:::controller
    end

    subgraph "Business Logic Layer"
        Middleware["Middleware (src/middlewares)"]:::middleware
        Operations["Operations (src/operations)"]:::operations
    end

    subgraph "Data Access & Integration Layer"
        subgraph "Service Layer (src/services)"
            DBService["Database Service (src/services/database.ts)"]:::service
            EmailService["Email Service (src/services/email)"]:::service
            EmailTemplates["Email Templates (src/services/email/templates)"]:::service
            DiscordService["Discord Service (src/services/discord.ts)"]:::service
            SlackService["Slack Service (src/services/slack.ts)"]:::service
        end
        Database["Database (MySQL with Prisma)"]:::database
    end

    Utilities["Utilities (src/utils)"]:::utils

    %% External Integrations
    ExternalDiscord["Discord API"]:::external
    ExternalStripe["Stripe API"]:::external
    ExternalSlack["Slack API"]:::external

    %% Data Flow
    Client -->|"HTTP Request"| NodeServer
    NodeServer -->|"Initial Processing"| Middleware
    Middleware -->|"Route Request"| Controllers
    Controllers -->|"Invoke Business Logic"| Operations
    Operations -->|"Call Services"| DBService
    Operations -->|"Call Services"| EmailService
    Operations -->|"Call Services"| DiscordService
    Operations -->|"Call Services"| SlackService

    %% Services relationships
    EmailService -->|"Uses"| EmailTemplates
    DBService -->|"Persists Data"| Database

    %% External Calls from Services
    DiscordService -->|"Integrates with"| ExternalDiscord
    SlackService -->|"Integrates with"| ExternalSlack
    Controllers -->|"Handles Billing"| ExternalStripe

    %% Utilities support all layers (dotted connection)
    Utilities --- NodeServer
    Utilities --- Middleware
    Utilities --- Controllers
    Utilities --- Operations
    Utilities --- DBService
    Utilities --- EmailService
    Utilities --- DiscordService
    Utilities --- SlackService

    %% Click Events
    click Controllers "https://github.com/ungdev/ua-api/tree/dev/src/controllers"
    click Middleware "https://github.com/ungdev/ua-api/tree/dev/src/middlewares"
    click DBService "https://github.com/ungdev/ua-api/blob/dev/src/services/database.ts"
    click EmailService "https://github.com/ungdev/ua-api/tree/dev/src/services/email"
    click EmailTemplates "https://github.com/ungdev/ua-api/tree/dev/src/services/email/templates"
    click DiscordService "https://github.com/ungdev/ua-api/blob/dev/src/services/discord.ts"
    click SlackService "https://github.com/ungdev/ua-api/blob/dev/src/services/slack.ts"
    click Operations "https://github.com/ungdev/ua-api/tree/dev/src/operations"
    click Database "https://github.com/ungdev/ua-api/blob/dev/schema.prisma"
    click Database "https://github.com/ungdev/ua-api/blob/dev/seed.sql"
    click Database "https://github.com/ungdev/ua-api/blob/dev/seed.test.sql"
    click Utilities "https://github.com/ungdev/ua-api/tree/dev/src/utils"

    %% Styles
    classDef controller fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef middleware fill:#B3E5FC,stroke:#333,stroke-width:2px;
    classDef operations fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef service fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef database fill:#FFAB91,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#E1BEE7,stroke:#333,stroke-width:2px,stroke-dasharray: 3 3;
    classDef server fill:#FFE082,stroke:#333,stroke-width:2px;
    classDef utils fill:#DCEDC8,stroke:#333,stroke-width:2px;
```
