# denvudd/plura architecture

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

- Interactive diagram: https://gitdiagram.com/denvudd/plura
- Repository: https://github.com/denvudd/plura

## Overview

##### Project type and purpose
- This is a full-stack, multi-tenant SaaS web application built with Next.js 14 (App Router), Bun, Prisma (MySQL), Tailwind CSS, and Stripe Connect.
- It provides an agency→sub-account hierarchy, a drag-and-drop website & funnel builder, project management (Kanban board), media storage, billing/subscriptions, and dashboards.

##### File structure and infer the layers
- src/app: Next.js App Router pages and layouts, split into two primary zones:
- (main): authenticated area under “/agency” and “/subaccount” with nested routing and domain-based routing.
- /[domain]/...: client-hosted funnels/websites.
- /api: serverless API routes for Stripe (checkout, customer, subscription, webhook) and file uploads (UploadThing).
- src/components: reusable UI (common, forms, modules, navigation, providers, ui) – purely client components.
- src/lib & src/queries: business logic, ORM (Prisma) wrappers, Stripe wrappers, validators, DB utilities.
- prisma/schema.prisma: data model for agencies, subaccounts, users, funnels, tickets, subscriptions, etc.
- Configuration: next.config.js, bun.lockb, tailwind.config.ts, tsconfig.json.

##### README for additional insights
- Multi-vendor B2B2B SaaS: agency vs. sub-account tenancy.
- Full website & funnel builder: editor module with drag-drop, layers, media upload.
- Stripe Connect for payment flows and subscription management.
- Kanban board for project management.
- Role-based access and custom dashboards.

##### Main components
a. Client / Browser (React × Next.js)
- Renders pages (SSR+CSR) and the drag-and-drop editor UI.
- Issues fetch()/Mutation requests to API routes.
b. Next.js Server (Bun runtime)
- App Router SSR/SSG handlers; serves static assets from /public.
- API routes under src/app/api/… handle:
- Stripe checkout, customer, subscription, webhook.
- UploadThing file upload.
c. Business Logic Layer
- src/lib, src/queries: Prisma ORM, validation, Stripe-client utilities.
d. Database (MySQL via Prisma)
- Stores tenants, users, funnels, tickets, media metadata, subscription records.
e. External Services
- Stripe Connect: payment flows, webhooks.
- UploadThing (or underlying S3/Cloud Storage): media file storage.
- (Optional): Email provider for invitations/notifications.
f. Static Assets / CDN
- Public folder assets, built JS/CSS served via Next.js or edge CDN.

##### Relationships and data flows
- Browser → Next.js Server: page requests (SSR/CSR) & API calls (fetch to /api/…).
- Next.js Server → Business Logic Layer: calls into src/queries & src/lib.
- Business Logic Layer → Database: Prisma queries & mutations on MySQL.
- Business Logic Layer → Stripe API: create checkout sessions, customers, subscriptions, handle webhooks.
- Business Logic Layer → UploadThing SDK: file upload initiation and completion.
- Stripe Webhook → Next.js Server: /api/stripe/webhook route to update DB.
- Browser ← Next.js Server: Push real-time updates (optional polling or subscription).

##### Architectural patterns and design principles
- Layered architecture:
- Presentation (Next.js pages + React components)
- API (Next.js serverless routes)
- Domain/Business Logic (lib, queries, validators)
- Data Persistence (Prisma + MySQL)
- Domain-driven modules: “agency,” “subaccount,” “funnels,” “pipelines,” “media,” etc.
- Multi-tenant design: tenant ID routing, role-based access.
- Component-based UI: atomic UI elements in src/components/ui, domain modules in src/components/modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["Browser (React/Next.js)"]:::frontend
        NextApp["Next.js App Router"]:::frontend
        Browser -->|"Page/API Requests"| NextApp
    end

    subgraph "UI Pages (src/app)" 
        direction TB
        signIn["Agency/Sub-Account Sign-In"]:::frontend
        signUp["Agency/Sub-Account Sign-Up"]:::frontend
        agDash["Agency Dashboard Pages"]:::frontend
        subDash["Sub-Account Dashboard Pages"]:::frontend
        domainSite["Client-Hosted Funnels/Websites"]:::frontend
        NextApp --> signIn
        NextApp --> signUp
        NextApp --> agDash
        NextApp --> subDash
        NextApp --> domainSite
    end

    %% API Layer
    subgraph "API Layer (src/app/api)" 
        direction TB
        stripeCO["Create Checkout Session"]:::api
        stripeCU["Create Customer"]:::api
        stripeCS["Create Subscription"]:::api
        stripeWH["Stripe Webhook"]:::api
        uploadRoute["UploadThing Route"]:::api
        uploadCore["UploadThing Core"]:::api

        NextApp -->|"fetch /api/stripe/create-checkout-session"| stripeCO
        NextApp -->|"fetch /api/stripe/create-customer"| stripeCU
        NextApp -->|"fetch /api/stripe/create-subscription"| stripeCS
        StripeSvc -->|"Webhook POST"| stripeWH
        NextApp -->|"fetch /api/uploadthing"| uploadRoute
        uploadRoute --> uploadCore
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer (src/lib & src/queries)" 
        direction TB
        dbUtil["DB Utilities"]:::logic
        stripeWrap["Stripe Wrappers"]:::logic
        validators["Validators"]:::logic
        editorUtil["Editor Utilities"]:::logic
        sharedUtil["Shared Utilities"]:::logic
        queries["Prisma Queries"]:::logic

        stripeCO -->|"calls stripe-actions"| stripeWrap
        stripeCU --> stripeWrap
        stripeCS --> stripeWrap
        stripeWH --> stripeWrap
        uploadRoute --> sharedUtil
        uploadCore --> sharedUtil
        NextApp --> validators
        NextApp --> editorUtil
        stripeWrap --> queries
        sharedUtil --> queries
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        DB["MySQL Database (Prisma)"]:::db
        queries -->|"Prisma Queries/Mutations"| DB
        dbUtil --> DB
    end

    %% External Services
    subgraph "External Services"
        direction TB
        StripeSvc["Stripe Connect"]:::external
        UploadSvc["UploadThing / S3"]:::external
        EmailSvc["Email Provider"]:::external
        stripeWrap -->|"API Calls"| StripeSvc
        uploadRoute -->|"Init Upload"| UploadSvc
        sharedUtil -->|"Notifications"| EmailSvc
    end

    %% Responses to Browser
    NextApp -->|"SSR/CSR Responses"| Browser

    %% Click Events
    click signIn "https://github.com/denvudd/plura/blob/main/src/app/(main)/agency/(auth)/sign-in/[[...sign-in]]/page.tsx"
    click signUp "https://github.com/denvudd/plura/blob/main/src/app/(main)/agency/(auth)/sign-up/[[...sign-up]]/page.tsx"
    click agDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/agency/[agencyId]/page.tsx"
    click agDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/agency/[agencyId]/billing/page.tsx"
    click agDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/agency/[agencyId]/all-subaccounts/page.tsx"
    click agDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/agency/[agencyId]/team/page.tsx"
    click agDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/agency/[agencyId]/settings/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/contacts/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/funnels/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/funnels/[funnelId]/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/funnels/[funnelId]/editor/[funnelPageId]/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/pipelines/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/media/page.tsx"
    click subDash "https://github.com/denvudd/plura/blob/main/src/app/(main)/subaccount/[subaccountId]/settings/page.tsx"
    click domainSite "https://github.com/denvudd/plura/blob/main/src/app/[domain]/page.tsx"
    click domainSite "https://github.com/denvudd/plura/blob/main/src/app/[domain]/[path]/page.tsx"
    click stripeCO "https://github.com/denvudd/plura/blob/main/src/app/api/stripe/create-checkout-session/route.ts"
    click stripeCU "https://github.com/denvudd/plura/blob/main/src/app/api/stripe/create-customer/route.ts"
    click stripeCS "https://github.com/denvudd/plura/blob/main/src/app/api/stripe/create-subscription/route.ts"
    click stripeWH "https://github.com/denvudd/plura/blob/main/src/app/api/stripe/webhook/route.ts"
    click uploadRoute "https://github.com/denvudd/plura/blob/main/src/app/api/uploadthing/route.ts"
    click uploadCore "https://github.com/denvudd/plura/blob/main/src/app/api/uploadthing/core.ts"
    click dbUtil "https://github.com/denvudd/plura/blob/main/src/lib/db.ts"
    click stripeWrap "https://github.com/denvudd/plura/blob/main/src/lib/stripe/stripe-actions.ts"
    click stripeWrap "https://github.com/denvudd/plura/blob/main/src/lib/stripe/stripe-client.ts"
    click validator "https://github.com/denvudd/plura/tree/main/src/lib/validators"
    click editorUtil "https://github.com/denvudd/plura/blob/main/src/lib/editor/utils.ts"
    click editorUtil "https://github.com/denvudd/plura/blob/main/src/lib/editor/add-verify-element.tsx"
    click sharedUtil "https://github.com/denvudd/plura/blob/main/src/lib/utils.ts"
    click queries "https://github.com/denvudd/plura/blob/main/src/queries/agency.ts"
    click DB "https://github.com/denvudd/plura/blob/main/prisma/schema.prisma"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#90CAF9
    classDef api fill:#E8F5E9,stroke:#66BB6A
    classDef logic fill:#FFFDE7,stroke:#FDD835
    classDef db fill:#FFE0B2,stroke:#FFB74D,stroke-width:2px
    classDef external fill:#F3E5F5,stroke:#AB47BC
```
