# voteagora/agora-next architecture

> Architecture diagram of the GitHub repository voteagora/agora-next, 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/voteagora/agora-next
- Repository: https://github.com/voteagora/agora-next

## Overview

##### Main Components
- Frontend Application (Next.js): Represented by the “src/app” folder (which holds pages, layouts, and server/client components) and “components” directories (for UI bits, shared components, dialogs, headers, etc). Also note the “apps” and “packages/ui” directories that may contain supplementary or shared frontend logic.
- API Endpoints and Backend Logic: All server-side functions live under “src/app/api” (and its various nested directories for proposals, delegates, analytics, retrofunding, etc.). These endpoints fetch and cache data (using Next.js data fetching features and React.cache) based on a defined set of server endpoints.
- Database & Data Access Layer: The data-model resides in a Postgres database managed via Prisma (“prisma/schema.prisma”). Besides this, the “packages/database” module and various “lib/prisma.ts” and “lib/prismaUtils.ts” files indicate that all data communication is abstracted using ORM and/or direct queries.
- External Services and Tools: There’s integration with Vercel for deployment, OpenTelemetry (OTel) for instrumentation (see instrumentation.ts and OpenTelemetry documentation in README), and developer tools like ESLint, Prettier, and TailwindCSS.
- Shared Libraries & Utility Modules: Multiple “src/lib” directories, hooks (“src/hooks”), and tenant configurations (under “src/lib/tenant”) are used to manage reusable logic (such as authentication, contract interactions, and voting utilities).

##### Relationships & Data Flow
- The Frontend sends requests to API routes (via fetch or internally via caching). These API endpoints retrieve data from the Postgres database (and sometimes from other datastore or smart contract calls) using Prisma.
- Data referenced in components (e.g., proposals, delegate information, votes, etc.) is fetched server-side in Next.js pages to optimize performance and caching, then passed down to client components for interactivity.
- UI libraries and shared components are developed as part of a multipackage/multi-module structure, assisting both admins and general users, while interconnecting with the overall Next.js routing and API infrastructure.
- Instrumentation components (OpenTelemetry) are integrated within the frontend and backend to capture distributed traces and metrics, hooking into services like Vercel deployment.
- Configuration files (e.g., next.config.js, tailwind.config.js) and multiple style solutions (SCSS, Tailwind, and Emotion) ensure visual consistency and theming across the application.

##### Architectural Patterns & Design Principles
- Server Components with Client Components: Illustrate the separation of concerns where primary data-fetching is done in server components (pages or layout) and then interactivity is added via client components.
- Modular & Layered Architecture: With packages for database and UI, use a layered approach to indicate separation of concerns (UI, Server/Business Logic, and Data Access).
- Caching & Data Reuse: The README emphasizes wrapping data access in React.cache to minimize redundant fetching.
- Multi-tenancy and Data Schema Separation: The database is organized into different schemas (center, config, agora, DAO namespaces) which should be noted in the data layer portion.

##### Technologies/Frameworks
- Next.js (Frontend & Server-side rendering)
- React (Client components)
- Prisma (ORM connecting to Postgres)
- Postgres (Database, with multiple schemas)
- TailwindCSS, SCSS, and Emotion (Styling)
- OpenTelemetry (Instrumentation)
- Vercel (Deployment)

##### Final Touches
- You capture the nuances of Next.js’s SSR/data fetching vs. client-side interactivity.
- Separation between the modular API (with multiple endpoints under “src/app/api/…”) and the comprehensive UI built using various components and hooks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Section
    subgraph "Frontend"
        Fpages["Next.js Pages (src/app)"]
        Fcomponents["UI Components (components)"]
        Fpackages["Shared UI (packages/ui)"]
        Fapp["Supplementary App (apps/nouns)"]
    end

    %% API & Backend Section
    subgraph "API & Backend"
        API["API Endpoints (src/app/api)"]
    end

    %% Data Access Layer
    subgraph "Data Access"
        Dschema["Prisma Schema (prisma/schema.prisma)"]
        Dmodule["Database Module (packages/database)"]
        Dclient["Prisma Client (src/app/lib/prisma.ts)"]
        Dutils["Prisma Utils (src/app/lib/prismaUtils.ts)"]
        DB["Postgres Database"]
    end

    %% Shared Libraries & Utilities
    subgraph "Shared Libs & Utilities"
        Llogic["Shared Logic (src/lib)"]
        Lhooks["Hooks (src/hooks)"]
        Ltenant["Tenant Config (src/lib/tenant)"]
    end

    %% External Services & Tools
    subgraph "External Services"
        ExITel["Instrumentation (src/instrumentation.ts)"]
        ExITelNode["Instrumentation Node (src/instrumentation.node.ts)"]
        ExVercel["Vercel Deployment (.github/workflows/vercel-preview-maker.yml)"]
        ExNextConfig["Next Config (next.config.js)"]
    end

    %% Connections from Frontend to API
    Fpages -->|"callsAPI"| API
    Fcomponents -->|"renders"| Fpages
    Fpackages -->|"sharedUI"| Fpages
    Fapp -->|"integrates"| Fpages

    %% Connections from Frontend to Shared Libs
    Fpages -->|"auth/hooks"| Llogic
    Fpages -->|"utilizes"| Lhooks
    Fpages -->|"tenantSetup"| Ltenant

    %% API interactions with Data Access Layer
    API -->|"queries"| Dclient
    API -->|"usesORM"| Dmodule
    Dclient -->|"executesQueries"| DB
    Dmodule -->|"abstractsDB"| DB
    Dutils --> Dclient

    %% Instrumentation connections
    Fpages ---|"trace"| ExITel
    API ---|"trace"| ExITel
    ExITel ---|"nodeIntegration"| ExITelNode

    %% Deployment and Config integrations
    ExVercel ---|"deploys"| Fpages
    ExVercel ---|"deploys"| API
    ExNextConfig ---|"configures"| Fpages

    %% Styling classes
    class Fpages,Fcomponents,Fpackages,Fapp,ExNextConfig,ExVercel internalFrontend
    class API internalAPI
    class Dschema,Dmodule,Dclient,Dutils,DB internalData
    class Llogic,Lhooks,Ltenant internalShared
    class ExITel,ExITelNode external

    %% Class Definitions with Colors
    classDef internalFrontend fill:#FFDDCC,stroke:#333,stroke-width:2px;
    classDef internalAPI fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef internalData fill:#CCCCFF,stroke:#333,stroke-width:2px;
    classDef external fill:#FFFFCC,stroke:#333,stroke-width:2px;
    classDef internalShared fill:#FFCCFF,stroke:#333,stroke-width:2px;
    classDef dbStyle fill:#99CCFF,stroke:#333,stroke-width:2px;
    %% Specifically style the Postgres DB as a cylinder-like shape (using round edges as approximation)
    class DB dbStyle

    %% Click Events for Frontend Components
    click Fpages "https://github.com/voteagora/agora-next/tree/main/src/app"
    click Fcomponents "https://github.com/voteagora/agora-next/tree/main/components"
    click Fpackages "https://github.com/voteagora/agora-next/tree/main/packages/ui"
    click Fapp "https://github.com/voteagora/agora-next/tree/main/apps/nouns"

    %% Click Events for API Endpoint
    click API "https://github.com/voteagora/agora-next/tree/main/src/app/api"

    %% Click Events for Data Access Layer
    click Dschema "https://github.com/voteagora/agora-next/blob/main/prisma/schema.prisma"
    click Dmodule "https://github.com/voteagora/agora-next/tree/main/packages/database"
    click Dclient "https://github.com/voteagora/agora-next/blob/main/src/app/lib/prisma.ts"
    click Dutils "https://github.com/voteagora/agora-next/blob/main/src/app/lib/prismaUtils.ts"

    %% Click Events for Shared Libs & Utilities
    click Llogic "https://github.com/voteagora/agora-next/tree/main/src/lib"
    click Lhooks "https://github.com/voteagora/agora-next/tree/main/src/hooks"
    click Ltenant "https://github.com/voteagora/agora-next/tree/main/src/lib/tenant"

    %% Click Events for External Services & Tools
    click ExITel "https://github.com/voteagora/agora-next/blob/main/src/instrumentation.ts"
    click ExITelNode "https://github.com/voteagora/agora-next/blob/main/src/instrumentation.node.ts"
    click ExVercel "https://github.com/voteagora/agora-next/blob/main/.github/workflows/vercel-preview-maker.yml"
    click ExNextConfig "https://github.com/voteagora/agora-next/blob/main/next.config.js"
```
