How mayank-dotcom/flow works
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/*