# ava-labs/builders-hub architecture

> Architecture diagram of the GitHub repository ava-labs/builders-hub, 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/ava-labs/builders-hub
- Repository: https://github.com/ava-labs/builders-hub

## Overview

##### Main System Components
- Frontend – The Next.js “app” directory defines pages, layouts, and components that render different sections (Docs, Academy, hackathons, integrations). This is the UI layer interacting directly with end users.
- API Layer – The “app/api” folder contains multiple API endpoints (auth, certificate generation, hackathons, open graph image generation, etc.) that are invoked from the client-side code.
- Server/Business Logic – In addition to API routes, there is a “server/services” folder that provides business logic (authentication, hackathon management, registration forms, etc.). This abstracts and centralizes backend services.
- Persistence / Database – The “prisma” directory (with migrations and schema.prisma) indicates that the project uses Prisma to manage its database, with tables corresponding to users, hackathons, register forms, and more.
- Content Management – The “content” directory (with sub-folders for academy, docs, integrations, guides, etc.) holds Markdown/MDX files which serve as static content that is rendered dynamically through the Next.js pages.
- External/Blockchain Integrations – Through “components/tools” and the “toolbox” folder, the project provides interfaces for chain creation, validator management, smart-contract deployments, and other blockchain utilities. This is where the project integrates with Avalanche-related external services.
- Infrastructure & CI/CD – The presence of GitHub workflows (in ".github/workflows") plus configuration files (next.config.mjs, tsconfig.json, etc.) indicate that continuous integration and deployment systems are in place.

##### Relationships and Data Flow
- Users interact with the Frontend (Next.js pages) in the browser. The UI is built with React components (in “app”, “components”, “hooks”, etc.) where different sections are clearly separated (academy, docs, integrations, hackathons).
- The content stored under “content” is fetched or compiled at build-time (or on-demand) to generate static pages; mark a content pipeline flow from the content directory to the Frontend.
- Continuous integration and deployment (via GitHub workflows and Vercel deployment as mentioned in the README) should be noted as enabling infrastructure around the code repository.

##### Architectural Patterns and Design Principles
- The system follows a modular and layered architecture where the UI, API, business logic, and database are clearly separated.
- The use of MDX content facilitates a content–driven architecture that can integrate static markdown pages with dynamic React components.
- There is a clear separation between documentation (static content) and interactive features (API, authentication, hackathon management).
- The project also supports blockchain integration and developer tools (toolbox) using micro-frontends/components that are isolated from the main content but integrated through common services.

## Diagram (Mermaid)

```mermaid
graph TD
    User["User"]:::user

    subgraph "Frontend Layer"
        FE["Next.js Frontend"]:::frontend
        FEComp["UI Components"]:::frontend
    end

    subgraph "API Layer"
        API["API Endpoints"]:::api
    end

    subgraph "Backend Services"
        BS["Backend Services"]:::backend
    end

    subgraph "Database"
        DB(("Prisma Database")):::database
    end

    subgraph "Content Management"
        CM["Content MDX Pipeline"]:::content
    end

    subgraph "External Blockchain Services"
        EB1["Blockchain Tools"]:::external
        EB2["Toolbox Utilities"]:::external
    end

    subgraph "CI/CD & Infrastructure"
        CI["CI/CD Pipeline"]:::infra
    end

    User -->|"interacts"| FE
    FE -->|"renders"| FEComp
    FE -->|"callsAPI"| API
    API -->|"processes"| BS
    BS -->|"queries"| DB
    FE -->|"fetchesContent"| CM
    API -->|"blockchainCall"| EB1
    FE -->|"invokesBlockchain"| EB1
    EB1 -->|"integratesWith"| EB2
    CI -->|"deploysTo"| FE
    CI -->|"deploysTo"| API
    CI -->|"deploysTo"| BS

    click FE "https://github.com/ava-labs/builders-hub/tree/master/app"
    click FEComp "https://github.com/ava-labs/builders-hub/tree/master/components"
    click API "https://github.com/ava-labs/builders-hub/tree/master/app/api"
    click BS "https://github.com/ava-labs/builders-hub/tree/master/server/services"
    click DB "https://github.com/ava-labs/builders-hub/tree/master/prisma"
    click CM "https://github.com/ava-labs/builders-hub/tree/master/content"
    click EB1 "https://github.com/ava-labs/builders-hub/tree/master/components/tools"
    click EB2 "https://github.com/ava-labs/builders-hub/tree/master/toolbox"
    click CI "https://github.com/ava-labs/builders-hub/blob/master/.github"

    classDef frontend fill:#DDEEFF,stroke:#000,stroke-width:2px;
    classDef api fill:#FFEEDD,stroke:#000,stroke-width:2px;
    classDef backend fill:#DFFFD7,stroke:#000,stroke-width:2px;
    classDef database fill:#FFF2CC,stroke:#000,stroke-width:2px;
    classDef content fill:#F0D9FF,stroke:#000,stroke-width:2px;
    classDef external fill:#FFD7D7,stroke:#000,stroke-width:2px;
    classDef infra fill:#E0E0E0,stroke:#000,stroke-width:2px;
    classDef user fill:#C0E0FF,stroke:#000,stroke-width:2px;
```
