# akhil-naidu/dflow architecture

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

- Interactive diagram: https://gitdiagram.com/akhil-naidu/dflow
- Repository: https://github.com/akhil-naidu/dflow

## Overview

##### Project type and purpose
- This is a full-stack, self-hosted PaaS/web platform (“dFlow”) built with Next.js (React/TypeScript) for the frontend, Payload CMS for admin/content and Node.js for backend logic and background processing.
- Purpose: allow users to deploy/manage apps (via Dokku, Docker, AWS, etc.), with automated workflows and monitoring.

##### High-level components
a. Users & Browser – end users access the web UI
b. Next.js Frontend – renders pages (SSR/SSG), serves static assets, hosts React components and API routes
c. Payload CMS – embedded admin UI + authenticated content/API layer on `/payload`
d. API / Business-Logic Layer – Next.js API routes invoke “actions” modules and enqueue jobs
e. Job Queue & Workers – BullMQ via Redis: background tasks process deployments, backups, plugin operations, monitoring, etc.
f. Data Stores – MongoDB (Payload collections for projects, servers, services, users, etc.) and Redis (queues, pub/sub)
g. External Services – AWS/dFlow cloud, Docker registries, Git providers, Dokku servers, Netdata, SSH, Railpack

##### Relationships and interactions
- Browser → Next.js Frontend (page requests, client-side fetch)
- Frontend → Next.js API Routes (e.g., `/api/deploy`, `/api/webhook`)
- API layer → “actions/*” modules (validation + orchestration)
- Actions → enqueue jobs to Redis queues
- Workers → dequeue jobs, call “lib/*” connectors to interact with external systems (Docker, Dokku, AWS, Netdata)
- API layer + Workers → read/write MongoDB via Payload CMS models
- Real-time updates → Redis pub/sub pushes status back to front end

##### Architectural patterns & design principles
- Modular separations:
- Presentation (Next.js pages & components)
- API/Orchestration (actions + validators)
- Asynchronous Processing (queues & workers)
- Data Persistence (Payload/MongoDB, Redis)
- Event-driven, queue-based background processing for reliability and scalability
- Single codebase monolith but logically layered
- Use of Payload CMS for built-in RBAC, hooks, and REST endpoints

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend/UI Zone
    subgraph "Frontend/UI"
        direction TB
        Browser["Users & Browser"]:::frontend
        NextFrontend["Next.js Frontend"]:::frontend
        PayloadCMS["Payload CMS Admin/UI"]:::frontend
    end

    %% API & Business Logic Zone
    subgraph "API & Business Logic"
        direction TB
        NextAPI["Next.js API Routes"]:::logic
        Actions["Actions Modules"]:::logic
    end

    %% Queues & Workers Zone
    subgraph "Queues & Workers"
        direction TB
        Queue["BullMQ Queues"]:::queue
        Worker["BullMQ Worker"]:::queue
    end

    %% Data Stores Zone
    subgraph "Data Stores"
        direction TB
        MongoDB["MongoDB (Payload Collections)"]:::datastore
        Redis["Redis (Queues & Pub/Sub)"]:::datastore
    end

    %% External Integrations Zone
    subgraph "External Integrations"
        direction TB
        Dokku["Dokku Connector"]:::external
        Docker["Docker Connector"]:::external
        AWS["AWS Connector"]:::external
        Netdata["Netdata Connector"]:::external
        Railpack["Railpack Connector"]:::external
    end

    %% Connections
    Browser -->|"HTTP/HTTPS"| NextFrontend
    NextFrontend -->|"SSG/SSR & Fetch"| NextAPI
    NextFrontend -->|"Admin UI Requests"| PayloadCMS
    NextAPI -->|"Invoke"| Actions
    Actions -.-|"Enqueue Job"| Queue
    Queue -->|"Dequeue"| Worker
    Worker -.-|"Async Calls"| Dokku
    Worker -.-|"Async Calls"| Docker
    Worker -.-|"Async Calls"| AWS
    Worker -.-|"Async Calls"| Netdata
    Worker -.-|"Async Calls"| Railpack
    NextAPI -->|"Read/Write"| MongoDB
    Worker -->|"Read/Write"| MongoDB
    NextAPI -->|"Publish"| Redis
    Worker -->|"Subscribe"| Redis
    Redis -->|"Real-time Updates"| NextFrontend

    %% Click Events
    click NextFrontend "https://github.com/akhil-naidu/dflow/tree/main/src/app/(frontend)"
    click NextFrontend "https://github.com/akhil-naidu/dflow/tree/main/src/components"
    click PayloadCMS "https://github.com/akhil-naidu/dflow/tree/main/src/app/(payload)"
    click PayloadCMS "https://github.com/akhil-naidu/dflow/blob/main/src/payload.config.ts"
    click PayloadCMS "https://github.com/akhil-naidu/dflow/blob/main/src/payload-types.ts"
    click PayloadCMS "https://github.com/akhil-naidu/dflow/tree/main/src/payload/collections"
    click PayloadCMS "https://github.com/akhil-naidu/dflow/tree/main/src/payload/endpoints"
    click NextAPI "https://github.com/akhil-naidu/dflow/tree/main/src/app/(frontend)/api"
    click Actions "https://github.com/akhil-naidu/dflow/tree/main/src/actions"
    click Queue "https://github.com/akhil-naidu/dflow/tree/main/src/queues"
    click Queue "https://github.com/akhil-naidu/dflow/blob/main/src/lib/bullmq.ts"
    click MongoDB "https://github.com/akhil-naidu/dflow/tree/main/src/payload/collections"
    click Redis "https://github.com/akhil-naidu/dflow/blob/main/src/lib/redis/index.ts"
    click Dokku "https://github.com/akhil-naidu/dflow/tree/main/src/lib/dokku"
    click Docker "https://github.com/akhil-naidu/dflow/tree/main/src/lib/server/docker"
    click Docker "https://github.com/akhil-naidu/dflow/tree/main/src/actions/dockerRegistry"
    click AWS "https://github.com/akhil-naidu/dflow/tree/main/src/actions/cloud/aws"
    click Netdata "https://github.com/akhil-naidu/dflow/tree/main/src/actions/netdata"
    click Railpack "https://github.com/akhil-naidu/dflow/tree/main/src/lib/server/railpack"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef logic fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef queue fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef datastore fill:#E6E0FF,stroke:#6F42C1,color:#6F42C1
    classDef external fill:#F0F0F0,stroke:#999999,color:#333333

    %% Legend
    subgraph Legend
        direction LR
        F["Frontend/UI"]:::frontend
        L["API & Logic"]:::logic
        Q["Queues & Workers"]:::queue
        D["Data Stores"]:::datastore
        E["External"]:::external
    end

    %% Footer
    classDef footer fill:none,stroke:none,color:#666;font-size:10px
    Footer["Title: dFlow Architecture | Version: 1.0 | Date: 2024-06-18"]:::footer
```
