🚀 NexusFlow

A real-time, full-stack Agile collaboration platform built with .NET 9 and React 19 - with deep AI integration powered by OpenRouter.

About • Demo • Features • Architecture • Tech Stack • Getting Started • Diagrams • Project Structure • Issues & Feedback

About

NexusFlow is a production-grade project management tool inspired by Trello and Jira, built from the ground up as a full-stack portfolio project. It features real-time collaboration via SignalR WebSockets, a rich Kanban board with drag-and-drop, multiple view modes, and a deep AI layer powered by the OpenRouter API.

Demo

🌐 Live Demo

Try it out: https://nexusflow123.vercel.app

⚠️ The live demo runs on free-tier infrastructure (Vercel + Render + Supabase). The backend may be slow to respond on the first request (cold start ~30s) and could occasionally be unavailable. Performance will improve after the first request wakes the server up.

Real-Time Collaboration (SignalR)

AI Features (Generation, Breakdown, Enhancements)

AI Architect

Board & Task Generation

Task Breakdown & Subtasks

Diagram Generation

Text Enhancements & Writing Assistant

Board Views (Table, Calendar, Timeline, Dashboard)

Features

Board & Task Management

• Drag-and-Drop Kanban boards — Move tasks and columns with optimistic UI updates (no lag, instant feedback, server-sync with automatic rollback on failure)
• Multiple View Modes — Switch between Board, Table, Calendar, Timeline, and Dashboard analytics views on any board
• Rich Task Cards — Tasks support assignees, labels, due dates, priorities, attachments, checklists (subtasks), time logging, and a rich-text description editor
• Board Templates — Create new boards from pre-configured templates (Kanban, Scrum, etc.)
• Board Lifecycle — Boards can be closed (read-only) and reopened; permanently deleted by admins
• Trash Zone — Drag a card to the trash drop zone to delete it instantly

Workspaces & Teams

• Workspace Management — Organize multiple boards under a workspace with member management
• Role-Based Access Control — Owner, Admin, Member, and Viewer roles scoped to both workspaces and individual boards
• Invite System — Invite members by username search or generate shareable invite links with configurable roles
• My Tasks Page — A personal cross-board view of all tasks assigned to you

Real-Time Collaboration (SignalR)

• Live board updates — Every task creation, move, update, and delete is broadcast via SignalR to all connected members — no page refresh needed
• Live column management — Column creation, rename, reorder, and deletion synced in real time
• Presence Tracking — See green online indicators for each board member who is currently viewing the board
• Live Notifications — In-app notification drawer with real-time delivery for board events
• Conflict-safe drag-and-drop — Server updates from other users are silently queued while you're dragging to prevent UI conflicts

AI Features (OpenRouter Integration)

NexusFlow includes a deep AI layer powered by the OpenRouter API — a unified gateway to models like stepfun/step-3.5-flash with automatic fallback to google/gemini-2.0-flash. Users configure their own API key in their profile, validated live before it is ever saved.

• AI Board & Task Generation — Describe your project idea and choose a template type (Kanban, Scrum, Sales/CRM, Bug Tracking). The AI generates a complete ready-to-use board: all columns and 6–10 pre-seeded tasks, each with a unique title, detailed description, and priority level.
• AI Task Injection per Column — Inside any board, click the ✨ AI button on a column and type a plain-language instruction (e.g. "set up CI/CD pipeline"). The AI intelligently breaks it down into 3–5 distinct, actionable tasks.
• Rich Text AI Writing Assistant — The task description editor (TipTap) has a built-in AI toolbar with 6 modes:
• 🔁 Enhance — Improve clarity and structure of existing text
• ✏️ Fix Grammar — Correct grammar and spelling
• ✂️ Shorten — Condense content while preserving key info
• 💼 Make Professional — Rewrite in a formal, professional tone
• 💬 Custom Instruction — Type any natural-language instruction for the AI to follow
• ✍️ Write from Title — Auto-generate a full task description just from the task title
• AI Subtask Generation — Inside the task detail modal, the AI reads the task title and description to generate 3–7 concrete, actionable subtask checklist items automatically.
• AI Diagram Generation — The AI can generate a PlantUML Entity-Relationship or architectural diagram based on context you describe, rendered inline in the task modal.
• Smart model fallback — Requests go to the primary model first; if it fails, the system automatically retries with the fallback model transparently.
• Per-user key management — Each user stores their own OpenRouter key (encrypted at rest), validated by a real API call before ever being persisted.

User Profiles & Appearance

• Rich profile page — Edit full name, job title, department, organization, location, bio, and avatar (URL or file upload)
• Username customization — Change your display username with real-time validation
• Theme preference — Light/Dark mode toggle, persisted server-side per user
• Privacy mode — "Appear offline always" toggle to hide your online presence from teammates

Notifications & Activity

• In-app notification drawer — Real-time notification feed powered by SignalR
• Activity log — Per-card activity feed tracking all changes (moves, edits, comments, status changes)
• Emoji reactions — React to activity log entries

Analytics & Automations

• Board Analytics Modal — Visual charts for task completion rates, priority distribution, and member workload
• Board Automations — Rule-based automations (e.g., auto-assign a label or change priority when a card moves to a specific column)
• Time Logging — Track time spent on individual tasks; per-task time logs

Architecture

NexusFlow is structured as three loosely coupled layers communicating over HTTP REST and WebSockets.

Overview

The React 19 frontend (Vite + TypeScript) communicates with the ASP.NET Core Web API (.NET 9) over two channels: - HTTP/REST with JWT Bearer tokens for standard CRUD operations - SignalR WebSockets for real-time push events (task moves, presence updates, notifications)

The API is organized into a thin controller → scoped service → EF Core pipeline. Business logic lives entirely in injectable service classes (IBoardService, ITaskService, etc.), keeping controllers as simple request routers. A singleton PresenceTracker service maintains an in-memory map of which users are online on which boards, without any database polling.

The PostgreSQL database (provisioned via Supabase — local Docker for development, cloud for production) is fully managed by EF Core code-first migrations, making the schema reproducible on any machine.

AI requests are made directly from the frontend using the user's own OpenRouter API key, so AI credentials never transit the backend server.

System Architecture Diagram

flowchart TB
    subgraph Browser["Browser"]
        FE["React 19 Frontend\n(Vite + TypeScript)"]
    end

    subgraph API["ASP.NET Core Web API (.NET 9)"]
        CTRL["Controllers\n(Auth, Boards, Tasks, Workspaces...)"]
        SVC["Service Layer\n(IBoardService, ITaskService...)"]
        HUB["BoardHub\n(SignalR)"]
        PT["PresenceTracker\n(Singleton DI)"]
        EF["EF Core DbContext"]
    end

    subgraph DB["PostgreSQL (Supabase)"]
        TABLES["Tables: Users, Boards, Columns,\nTaskCards, Labels, Automations..."]
    end

    AI["OpenRouter API\n(AI Gateway)"]

    FE -- "HTTP/REST (JWT Bearer)" --> CTRL
    FE <-- "WebSocket (SignalR)" --> HUB
    HUB --> PT
    CTRL --> SVC
    SVC --> EF
    EF --> TABLES
    FE -- "AI requests\n(user's own key)" --> AI

Key Design Decisions

Decision	Rationale
Optimistic UI	All mutations update the UI instantly and roll back automatically if the server returns an error, providing seamless UX with no perceived latency.
SignalR presence tracking	A singleton PresenceTracker maps ConnectionIds to UserIds and BoardIds, enabling live online indicators without polling.
Service layer pattern	Business logic lives in scoped services injected via ASP.NET Core DI, keeping controllers thin and testable.
Code-First migrations	The entire database schema is defined in C# and managed via EF Core migrations, making it fully reproducible from any machine.
Drag-and-drop conflict guard	When a user is mid-drag, incoming SignalR TaskMoved events are silently queued via an isDraggingRef guard and applied after the drag ends, preventing ghost-card artifacts.
Per-user AI key validation	The OpenRouter API key is validated by making a real test call before being persisted, ensuring no broken keys are ever stored.

Tech Stack

Layer	Technology
Backend	C# / .NET 9, ASP.NET Core Web API
ORM	Entity Framework Core 9 (Code-First)
Database	PostgreSQL (via Supabase — local Docker or cloud)
Auth	JWT Bearer tokens + BCrypt password hashing
Real-Time	ASP.NET Core SignalR (WebSockets)
Frontend	React 19, TypeScript 5, Vite
UI Library	Mantine 7 (dark/light theme)
Drag & Drop	@hello-pangea/dnd
Rich Text	TipTap editor
Icons	Tabler Icons
HTTP Client	Axios
AI	OpenRouter API (user-supplied key)

Getting Started

Full setup guide: See SETUP.md for detailed instructions.

Prerequisites

Tool	Version
.NET SDK	9.0+
Node.js	18+
Docker Desktop	Latest

Option A — Local Docker (Recommended)

This spins up a full local Supabase (PostgreSQL) environment automatically.

First-time setup (run once after cloning):

.\init-dev.ps1

Daily development (after first-time setup):

.\start-dev.ps1

The script automatically starts Supabase, applies migrations, and launches both the backend (localhost:5145) and frontend (localhost:5173).

Option B — Cloud Supabase

If you prefer not to use Docker, point the app to a cloud Supabase project.

1. Create a Supabase project at supabase.com and copy your connection string.

2. Configure the backend (backend/appsettings.json):

{
  "ConnectionStrings": {
    "DefaultConnection": "YOUR_SUPABASE_CONNECTION_STRING"
  },
  "JwtSettings": {
    "SecretKey": "your-strong-random-secret-key-min-32-chars",
    "Issuer": "NexusFlow",
    "Audience": "NexusFlowUsers"
  }
}

3. Apply migrations:

cd backend
dotnet ef database update

4. Run the backend:

cd backend
dotnet run
# → API running at http://localhost:5145

5. Run the frontend:

cd frontend
npm install
npm run dev
# → App running at http://localhost:5173

Diagrams

These diagrams use Mermaid.js which is natively rendered by GitHub — no plugins needed.

Database Entity-Relationship Diagram

```mermaid erDiagram Users { int id PK string username string email string passwordHash string fullName string avatarUrl string openRouterApiKey string themePreference bool displayOfflineAlways datetime createdAt } Workspaces { int id PK string name int ownerId FK } WorkspaceMembers { int workspaceId FK int userId