The Problem

Teams need a low‑friction, web‑based whiteboard that supports real‑time collaboration, AI‑assisted drawing, and easy onboarding. Existing tools either lock developers into proprietary stacks or require heavy infrastructure to self‑host.

What This Does

Neoflow is a Next.js / React application that renders a tldraw‑powered canvas (components/Tl/editor.jsx) and layers UI components (toolbars, sidebars, buttons) around it. API endpoints under app/api/ handle authentication (app/api/auth/[...nextauth]/Options.ts), project CRUD, team invitations, and AI generation (app/api/gpt/route.ts). The Tailwind config (tailwind.config.js) supplies the visual theme, while Prisma (prisma/schema.prisma) defines the relational data model for users, teams, and projects.

How It Is Wired

  • Entry point – npm run dev (from package.json) starts the Next.js server, which loads app/layout.jsx and app/page.jsx.
  • Routing – Each file in app/api/**/route.ts exports a handler that Next.js mounts under /api/.... For example, app/api/gpt/route.ts receives POST requests, parses the body, and forwards the prompt to the AI service.
  • Authentication hub – app/api/auth/[...nextauth]/Options.ts is imported by 18 other modules (the highest‑import count). It configures NextAuth, supplies session callbacks, and is the sole gatekeeper for protected routes.
  • UI hub – components/ui/button.jsx is imported by 13 components, making it the primary reusable button implementation. Changes here ripple across the UI.
  • Editor flow – The canvas component (components/Tl/editor.jsx) imports several Mermaid helpers (components/Tl/Mermaid/*.jsx) and the monaco‑mermaid integration (components/Tl/Mermaid/monaco‑mermaid.js). User actions bubble up to Redux‑style state in lib/state/useEditor.js, which persists changes via the Prisma API.
  • Blast‑radius hotspots –
  • app/api/auth/[...nextauth]/Options.ts (18 importers) – any modification affects authentication across the app.
  • components/ui/button.jsx (13 importers) – UI tweaks propagate widely.
  • components/Tl/editor.jsx imports six internal modules, giving it an instability score of 1.
  • No circular dependencies – The import graph contains 113 modules and 62 edges with zero cycles, simplifying static analysis.

How To Use It

# Clone the forked repo (use the provided URL)
git clone https://github.com/moses-y/Neoflow.git
cd Neoflow

# Install dependencies
npm --force i   # as documented in README

# Copy the example environment and fill required keys
cp .env.example .env   # (keys not listed in repo – add DB URL, NextAuth secret, etc.)

# Run the development server
npm run dev

# Open http://localhost:3000 in a browser

The repo supplies next.config.js (Next.js build settings) and tailwind.config.js (styling). No Dockerfile or CI scripts are present, so containerization must be added manually if required.

Real‑World Use

A product team can self‑host Neoflow behind their corporate SSO by customizing app/api/auth/[...nextauth]/Options.ts to use Azure AD. Front‑end developers extend components/Tl/editor.jsx with custom drawing tools, while backend engineers add new Prisma models and API routes under app/api/ to persist domain‑specific metadata.

Code Health & Issues

  • HIGH – No LICENSE – repository root lacks a licence file; default is “all rights reserved”.
  • HIGH – No test suite – 113 source files, zero test files; regressions are unchecked.
  • HIGH – No CI/CD pipeline – no .github/workflows or similar; builds are never automatically verified.
  • MEDIUM – Dependabot missing – only one manifest (package.json); no automated dependency updates.
  • LOW – Missing repo conventions – no .editorconfig, .gitattributes, or formatter config; style consistency is unenforced.
  • HIGH (cognitive load) – Deep nesting – files such as app/api/auth/[...nextauth]/Options.ts have indentation depth 6, making logic hard to follow.
  • HIGH (clarity) – Duplicated blocks – similar 6‑line snippets repeat across 41 API files (e.g., app/api/gpt/route.ts, app/api/team/route.ts).
  • MEDIUM (cognitive load) – Oversized file – components/Tl/Mermaid/monaco-mermaid.js is 815 lines; should be split by responsibility.

The Bottom Line

Neoflow delivers a functional, open‑source whiteboard with real‑time collaboration and AI features, but the codebase suffers from missing licensing, testing, and CI infrastructure, plus several maintainability hot‑spots. It is suitable for teams willing to invest in refactoring and adding DevOps guardrails before production use.