# mayank-dotcom/flow architecture

> Architecture diagram of the GitHub repository mayank-dotcom/flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mayank-dotcom/flow
- Repository: https://github.com/mayank-dotcom/flow

## Overview

##### What this project is (type + purpose)
**FLOW.** is a **full-stack Next.js (App Router) web application** that lets users **compose and run multi-stage AI text workflows** (Cleanse/Summarize/Translate/Refine, etc.). It includes:
- A **UI builder** for assembling workflow stages
- An **execution engine** that runs workflows via **LangChain + OpenAI**
- **Persistence** of workflows and run history in **MongoDB via Mongoose**
- A small internal API surface implemented as **Next.js route handlers** under `app/api/*`

##### User-facing UI routes (pages)
- `app/page.tsx` → Landing
- `app/builder/page.tsx` → Workflow builder UI
- `app/dashboard/page.tsx` → Overview
- `app/history/page.tsx` → Run history listing
- `app/run/[id]/page.tsx` → Run detail
- `app/status/page.tsx` → System/status page

Shared layout/UI:
- `app/layout.tsx`, `app/globals.css`
- `components/*` → Sidebar, backgrounds, layout wrapper, etc.

##### Server/API endpoints (Next.js route handlers)
- `app/api/health/route.ts` → health check
- `app/api/workflows/route.ts` → CRUD-ish for workflows (likely list/create)
- `app/api/runs/route.ts` → run records (list/create)
- `app/api/execute/route.ts` → **execution entrypoint** (trigger workflow run)

##### Core server-side modules (execution + persistence)
These are important internal components to show (even if they’re not separate deployables):
- `lib/langchain.ts` → LangChain setup / chain execution orchestration
- `lib/db.ts`, `lib/mongoose.ts` → Mongo connection lifecycle
- `models/Workflow.ts`, `models/Run.ts` → Mongoose schemas/models
- `lib/types.ts` → shared types/contracts

From README + env requirements:
- **OpenAI API** (via LangChain)
- **MongoDB** (MONGODB_URI)

System as users experience it:
- **User (Browser)**
→ **Next.js App (FLOW.)**
→ **MongoDB**
→ **OpenAI API (via LangChain)**

This is the fastest way to communicate boundaries and external integrations.

Decompose the Next.js app into:
##### Persistence Layer (Mongoose models + DB connector)

- Builder → Save workflow → MongoDB
- Execute → LangChain/OpenAI → Save Run → MongoDB
- History/Run detail → Fetch runs → MongoDB

**Client (Browser)**
- Builder Page (`/builder`)
- Dashboard (`/dashboard`)
- History (`/history`)
- Run Detail (`/run/[id]`)
- Landing (`/`)

**Server (Next.js route handlers)**
- `POST/GET /api/workflows` (from `app/api/workflows/route.ts`)
- `POST/GET /api/runs` (from `app/api/runs/route.ts`)
- `POST /api/execute` (from `app/api/execute/route.ts`)
- `GET /api/health` (from `app/api/health/route.ts`)

**Domain / Core**
- Workflow Model (`models/Workflow.ts`)
- Run Model (`models/Run.ts`)
- Execution Orchestrator (`lib/langchain.ts`)
- DB Connection (`lib/mongoose.ts` / `lib/db.ts`)

**External**
- MongoDB
- OpenAI API

##### Workflow authoring
- Browser `/builder` → `/api/workflows` → `Workflow` model → MongoDB

##### Workflow execution
- Browser (builder/run action) → `/api/execute`
→ loads workflow from MongoDB (`Workflow` model)
→ executes stages via `lib/langchain.ts`
→ calls **OpenAI API**
→ persists output + metadata via `Run` model → MongoDB
→ returns run id/status to Browser

##### History and run inspection
- Browser `/history` or `/run/[id]` → `/api/runs` → `Run` model → MongoDB

##### Health/status
- Browser `/status` → `/api/health` (optionally checks DB connectivity)

##### Architectural patterns/design principles to call out
- **“Full-stack-in-one” Next.js architecture**: UI + backend endpoints in the same repo/runtime.
- **Route-handler API layer**: `app/api/*` acts as the internal service boundary.
- **Domain models via Mongoose**: `models/*` define persistence contracts for workflows and runs.
- **Execution pipeline**: `lib/langchain.ts` is the “workflow engine,” orchestrating multi-step LLM calls.
- **Separation of concerns**:
- UI in `app/*` and `components/*`
- API in `app/api/*`
- Infra + domain in `lib/*` + `models/*`

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% View A: Context / Container
  %% =========================
  subgraph "Context (Container View)"
    direction TB

    U["User (Browser)"]:::external

    subgraph "FLOW. (Single Next.js App Router Application)"
      direction TB
      NX["Next.js App (UI + Route Handlers)"]:::app
    end

    MDB[("MongoDB")]:::db
    OAI["OpenAI API"]:::external

    U -->|"HTTPS:Navigate/Interact"| NX
    NX -->|"Read/Write:Workflows+Runs"| MDB
    NX -->|"LLMRequests(viaLangChain)"| OAI
  end

  %% =========================
  %% View B: Component Diagram
  %% =========================
  subgraph "Component View (Inside Next.js App)"
    direction TB

    %% --- UI Layer ---
    subgraph "UI Layer (App Router Pages + Shared UI)"
      direction TB

      LAYOUT["Root Layout (app/layout.tsx)"]:::ui
      CSS["Global Styles (app/globals.css)"]:::ui
      SHARED["Shared UI Components (components/*)"]:::ui

      LAND["Landing Page (/)"]:::ui
      BUILDER["Workflow Builder (/builder)"]:::ui
      DASH["Dashboard (/dashboard)"]:::ui
      HIST["Run History (/history)"]:::ui
      RUNDETAIL["Run Detail (/run/[id])"]:::ui
      STATUS["Status (/status)"]:::ui

      LAYOUT -->|"wraps"| LAND
      LAYOUT -->|"wraps"| BUILDER
      LAYOUT -->|"wraps"| DASH
      LAYOUT -->|"wraps"| HIST
      LAYOUT -->|"wraps"| RUNDETAIL
      LAYOUT -->|"wraps"| STATUS

      CSS -->|"styles"| LAYOUT
      SHARED -->|"usedBy"| LAND
      SHARED -->|"usedBy"| BUILDER
      SHARED -->|"usedBy"| DASH
      SHARED -->|"usedBy"| HIST
      SHARED -->|"usedBy"| RUNDETAIL
      SHARED -->|"usedBy"| STATUS
    end

    %% --- API Layer ---
    subgraph "API Layer (Next.js Route Handlers: app/api/*)"
      direction TB

      API_HEALTH["GET /api/health"]:::api
      API_WORKFLOWS["GET/POST /api/workflows"]:::api
      API_RUNS["GET/POST /api/runs"]:::api
      API_EXEC["POST /api/execute (Execution Entrypoint)"]:::apiHot
    end

    %% --- Core Services / Domain ---
    subgraph "Core Services (Execution + Persistence)"
      direction TB

      TYPES["Shared Types/Contracts (lib/types.ts)"]:::core

      subgraph "Execution Engine"
        direction TB
        ENGINE{{"LangChain Orchestrator (lib/langchain.ts)"}}:::engine
        STAGES["Workflow Stages (data-driven)\nCleanse → Summarize → Translate → Refine ..."]:::engineSub
        ENGINE -->|"orchestrates"| STAGES
      end

      subgraph "Persistence Layer (MongoDB via Mongoose)"
        direction TB
        DBLIFE["Mongoose Connection Lifecycle (lib/mongoose.ts)"]:::data
        DBHELP["DB Helper/Connector (lib/db.ts)"]:::data
        WF_MODEL["Workflow Model (models/Workflow.ts)\n→ workflows collection"]:::data
        RUN_MODEL["Run Model (models/Run.ts)\n→ runs collection"]:::data

        DBHELP -->|"uses"| DBLIFE
        WF_MODEL -->|"uses"| DBLIFE
        RUN_MODEL -->|"uses"| DBLIFE
      end
    end

    %% --- External deps (referenced by internals) ---
    subgraph "External Services"
      direction TB
      EXT_MDB[("MongoDB (MONGODB_URI)")]:::db
      EXT_OAI["OpenAI API"]:::external
    end

    %% --- Future / Roadmap (optional, dashed) ---
    subgraph "Future (Roadmap)"
      direction TB
      FUT_AUTH["Auth (OAuth/JWT)"]:::future
      FUT_CRON["Cron Scheduling / Background Runner"]:::future
      FUT_BRANCH["Branching Logic"]:::future
      FUT_EXPORT["Export/Import Workflows"]:::future
    end
  end

  %% =========================
  %% Main Flows (UI -> API -> Core -> External)
  %% =========================
  BUILDER -->|"save/loadWorkflow"| API_WORKFLOWS
  API_WORKFLOWS -->|"validate+types"| TYPES
  API_WORKFLOWS -->|"CRUD:Workflow"| WF_MODEL
  WF_MODEL -->|"persist"| EXT_MDB

  BUILDER -->|"executeWorkflow"| API_EXEC
  API_EXEC -->|"validate+types"| TYPES
  API_EXEC -->|"loadWorkflowById"| WF_MODEL
  WF_MODEL -->|"read"| EXT_MDB
  API_EXEC -->|"runPipeline"| ENGINE
  ENGINE -->|"prompt+context"| EXT_OAI
  EXT_OAI -->|"completion/result"| ENGINE
  API_EXEC -->|"persistRun(outputs+status)"| RUN_MODEL
  RUN_MODEL -->|"write"| EXT_MDB
  API_EXEC -->|"returnRunId+status"| BUILDER

  HIST -->|"listRuns"| API_RUNS
  RUNDETAIL -->|"getRunById"| API_RUNS
  API_RUNS -->|"validate+types"| TYPES
  API_RUNS -->|"queryRuns"| RUN_MODEL
  RUN_MODEL -->|"read"| EXT_MDB

  STATUS -->|"healthCheck"| API_HEALTH
  API_HEALTH -->|"checkDbConnectivity"| DBHELP
  DBHELP -->|"ping/connect"| EXT_MDB

  %% Light coupling hints
  API_WORKFLOWS -.->|"mayUse"| DBHELP
  API_RUNS -.->|"mayUse"| DBHELP
  API_EXEC -.->|"mayUse"| DBHELP

  %% Env template reference (documentation/config)
  ENV["Environment Template (.env.example)"]:::config
  ENV -.->|"defines:MONGODB_URI,OPENAI_API_KEY"| EXT_MDB
  ENV -.->|"defines:OPENAI_API_KEY"| EXT_OAI

  %% =========================
  %% Click Events (component_mapping)
  %% =========================
  click LAND "https://github.com/mayank-dotcom/flow/blob/main/app/page.tsx"
  click BUILDER "https://github.com/mayank-dotcom/flow/blob/main/app/builder/page.tsx"
  click DASH "https://github.com/mayank-dotcom/flow/blob/main/app/dashboard/page.tsx"
  click HIST "https://github.com/mayank-dotcom/flow/blob/main/app/history/page.tsx"
  click RUNDETAIL "https://github.com/mayank-dotcom/flow/blob/main/app/run/[id]/page.tsx"
  click STATUS "https://github.com/mayank-dotcom/flow/blob/main/app/status/page.tsx"

  click LAYOUT "https://github.com/mayank-dotcom/flow/blob/main/app/layout.tsx"
  click CSS "https://github.com/mayank-dotcom/flow/blob/main/app/globals.css"
  click SHARED "https://github.com/mayank-dotcom/flow/tree/main/components/"

  click API_HEALTH "https://github.com/mayank-dotcom/flow/blob/main/app/api/health/route.ts"
  click API_WORKFLOWS "https://github.com/mayank-dotcom/flow/blob/main/app/api/workflows/route.ts"
  click API_RUNS "https://github.com/mayank-dotcom/flow/blob/main/app/api/runs/route.ts"
  click API_EXEC "https://github.com/mayank-dotcom/flow/blob/main/app/api/execute/route.ts"

  click ENGINE "https://github.com/mayank-dotcom/flow/blob/main/lib/langchain.ts"
  click DBLIFE "https://github.com/mayank-dotcom/flow/blob/main/lib/mongoose.ts"
  click DBHELP "https://github.com/mayank-dotcom/flow/blob/main/lib/db.ts"
  click TYPES "https://github.com/mayank-dotcom/flow/blob/main/lib/types.ts"

  click WF_MODEL "https://github.com/mayank-dotcom/flow/blob/main/models/Workflow.ts"
  click RUN_MODEL "https://github.com/mayank-dotcom/flow/blob/main/models/Run.ts"

  click ENV "https://github.com/mayank-dotcom/flow/blob/main/.env.example"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#E8F7EE,stroke:#1B7F3A,stroke-width:1.5px,color:#0B3D1A;
  classDef app fill:#EEF4FF,stroke:#2B5BD7,stroke-width:1.5px,color:#0B1B3A;
  classDef ui fill:#E6F0FF,stroke:#3B82F6,stroke-width:1.2px,color:#0B1B3A;
  classDef api fill:#F3E8FF,stroke:#7C3AED,stroke-width:1.2px,color:#2E1065;
  classDef apiHot fill:#F5D0FE,stroke:#6D28D9,stroke-width:2px,color:#2E1065;
  classDef engine fill:#FFEDD5,stroke:#F97316,stroke-width:2px,color:#4A2506;
  classDef engineSub fill:#FFF7ED,stroke:#FB923C,stroke-width:1.2px,color:#4A2506;
  classDef data fill:#F3F4F6,stroke:#6B7280,stroke-width:1.2px,color:#111827;
  classDef db fill:#E5E7EB,stroke:#111827,stroke-width:1.5px,color:#111827;
  classDef future fill:#FFFFFF,stroke:#9CA3AF,stroke-width:1.2px,stroke-dasharray: 6 4,color:#374151;
  classDef config fill:#ECFDF5,stroke:#10B981,stroke-width:1.2px,color:#064E3B;
```
