# juanmgualteros/droker-agentic-hub architecture

> Architecture diagram of the GitHub repository juanmgualteros/droker-agentic-hub, 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/juanmgualteros/droker-agentic-hub
- Repository: https://github.com/juanmgualteros/droker-agentic-hub

## Overview

##### Main Components
- Frontend (Client/UI):
- Built with Next.js 14 and TypeScript.
- Uses folder-based routing (see directories under src/app, e.g., locale-specific folders for admin, login, superadmin, etc.).
- Contains comprehensive UI components (src/components) like layout components (AppLayout, PortalLayout, etc.), navigation, forms, and specialized admin/superadmin components.
- Implements internationalization (i18n) using next-intl (see src/i18n and localization files).

- API / Backend Endpoints:
- API routes are defined under src/app/api (e.g., admin-users, organizations, products, and superadmin endpoints).
- These endpoints coordinate business logic and interact with the data layer.

- Database & ORM:
- PostgreSQL is used along with Prisma ORM.
- The prisma folder holds the schema, migrations, and seed scripts.
- The lib directory contains database connection implementations (e.g., src/lib/db/prisma.ts) and helper functions.

- External Services / Integration:
- Supabase is used for storage and additional services (see src/lib/supabase and Supabase-related SQL files).
- Environment variables include all links necessary to connect to the Supabase project alongside a secret key for cookie-based authentication.

- Middleware & Configuration:
- Global middlewares (middleware.ts at the root and in src/) are used for processes like cookie validation and edge runtime adaptations.
- Configuration files such as next.config.js, tailwind.config.js, and vercel.json provide environment- and deployment-related settings.

##### Relationships and Interactions
- The Client/UI layer (rendered by Next.js) sends requests (often via fetch or dedicated fetch/use client hooks) to the API endpoints.
- API endpoints process requests, validate authentication (using cookie-based mechanisms likely implemented in middleware.ts), and interact with the database through Prisma.
- The database (PostgreSQL) is accessed via the Prisma ORM to perform CRUD operations.
- Frontend and API layers also incorporate internationalization, wherein locale-specific pages and content are served to users.

##### Architectural Patterns and Design Principles
- The project follows Next.js best practices with a clear separation of concerns: the presentation layer (pages/components), an API layer (serverless functions/routed API endpoints), and a persistence layer (Prisma & PostgreSQL).
- It leverages a modular file structure (separated directories for admin, superadmin, and user functionalities) which improves maintainability.
- Middleware usage ensures security (authentication and edge runtime support) at the request handling level.
- The design is component-driven, with reusable UI components (organized in src/components) and style tokens and themes (under src/styles/design-system).

##### Relevant Technologies and Their Roles
- Next.js 14: Provides the App Router, SSR, and client-side routing.
- TypeScript: Ensures type safety across both frontend and backend.
- Tailwind CSS: Used for consistent design and responsive styling.
- Prisma ORM & PostgreSQL: Manage data modeling and persistence.
- Supabase: Provides storage and additional cloud functions.
- next-intl: Handles internationalization for a multi-locale experience.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FR1["Page Routing (src/app)"]
        FR2["UI Components (src/components)"]
        FR3["Internationalization (src/i18n)"]
        FE_AGG["Frontend Aggregator"]
    end
    FR1 --> FE_AGG
    FR2 --> FE_AGG
    FR3 --> FE_AGG

    %% Middleware & Configuration Layer
    subgraph "Middleware & Config"
        MW1["Middleware (Root)"]
        MW2["Middleware (Project)"]
        CFG1["Next Config"]
        CFG2["Tailwind Config (JS)"]
        CFG3["Tailwind Config (TS)"]
        CFG4["Vercel Config"]
        MC_AGG["Middleware & Config Aggregator"]
    end
    MW1 --> MC_AGG
    MW2 --> MC_AGG
    CFG1 --> MC_AGG
    CFG2 --> MC_AGG
    CFG3 --> MC_AGG
    CFG4 --> MC_AGG

    %% API Layer
    subgraph "API Layer"
        API["API Endpoints (src/app/api)"]
    end

    %% Data Persistence Layer
    subgraph "Data Persistence"
        DB1["Prisma Schema (prisma)"]
        DB2["Prisma Client (src/lib/db/prisma.ts)"]
        DB_AGG["Database (PostgreSQL/Prisma)"]
    end
    DB1 --> DB_AGG
    DB2 --> DB_AGG

    %% External Services Layer
    subgraph "External Services"
        SUPA["Supabase Storage (src/lib/supabase)"]
    end

    %% Connections
    FE_AGG -->|"HTTP_Request"| MC_AGG
    MC_AGG -->|"Validated_Request"| API
    API -->|"DB_Query"| DB_AGG
    API -->|"Storage_Request"| SUPA

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef middleware fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef database fill:#F0E68C,stroke:#000,stroke-width:2px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:2px;

    class FR1,FR2,FR3,FE_AGG frontend;
    class MW1,MW2,CFG1,CFG2,CFG3,CFG4,MC_AGG middleware;
    class API backend;
    class DB1,DB2,DB_AGG database;
    class SUPA external;

    %% Click Events
    click FR1 "https://github.com/juanmgualteros/droker-agentic-hub/tree/main/src/app"
    click FR2 "https://github.com/juanmgualteros/droker-agentic-hub/tree/main/src/components"
    click FR3 "https://github.com/juanmgualteros/droker-agentic-hub/tree/main/src/i18n"
    click MW1 "https://github.com/juanmgualteros/droker-agentic-hub/blob/main/middleware.ts"
    click MW2 "https://github.com/juanmgualteros/droker-agentic-hub/blob/main/src/middleware.ts"
    click CFG1 "https://github.com/juanmgualteros/droker-agentic-hub/blob/main/next.config.js"
    click CFG2 "https://github.com/juanmgualteros/droker-agentic-hub/blob/main/tailwind.config.js"
    click CFG3 "https://github.com/juanmgualteros/droker-agentic-hub/blob/main/tailwind.config.ts"
    click CFG4 "https://github.com/juanmgualteros/droker-agentic-hub/blob/main/vercel.json"
    click API "https://github.com/juanmgualteros/droker-agentic-hub/tree/main/src/app/api"
    click DB1 "https://github.com/juanmgualteros/droker-agentic-hub/tree/main/prisma"
    click DB2 "https://github.com/juanmgualteros/droker-agentic-hub/blob/main/src/lib/db/prisma.ts"
    click SUPA "https://github.com/juanmgualteros/droker-agentic-hub/tree/main/src/lib/supabase"
```
