AI-powered project management workspace — Kanban board, Studio intake chat, documents, and journals backed by a multi-agent LangGraph orchestration layer.
| Layer | Stack |
|---|---|
| Frontend | Next.js App Router, React 19, Tailwind CSS v4 |
| Backend | Next.js API routes, PostgreSQL, Server-Sent Events (SSE) |
| AI | LangGraph StateGraph, multi-provider LLM (DeepSeek / OpenAI / Gemini), per-agent config |
| Auth | Role-Based Access Control (RBAC) with CSRF protection, rate limiting, and segment-based session boundaries |
| Testing | Vitest 4 + React Testing Library |
- Node.js 20 (locked via
.nvmrc) - PostgreSQL 15+
- pnpm 10+
# Install dependencies
pnpm install
# Set up environment
cp .env.example .env.local
# Edit .env.local with your DATABASE_URL and API keys
# Initialize database
psql $DATABASE_URL -f db/init.sql
# Start dev server
pnpm dev # → http://localhost:3000pnpm dev # Next.js dev server
pnpm build # Production build
pnpm test # Run all tests (207 files, 2919 tests)
pnpm test:watch # Vitest in watch mode
pnpm lint # ESLint
pnpm format # Prettier format all files
pnpm format:check # Check formatting (CI)
pnpm tsc --noEmit # TypeScript type check
pnpm audit:shared # Dynamic discovery of shared utils/components
pnpm migrate # Run pending DB migrations
pnpm migrate:status # Check migration statusvctrx/
├── app/ # Next.js App Router
│ ├── api/ # REST endpoints
│ │ ├── studio/chat/ # Studio SSE streaming + persistence
│ │ ├── tickets/ # Kanban ticket CRUD + search
│ │ ├── documents/ # Document instances + sections
│ │ ├── journals/ # Journal entries
│ │ ├── notifications/ # Unified notification feed (conferences + ticket events)
│ │ ├── projects/ # Project listing
│ │ └── settings/ # Project + version settings
│ ├── page.tsx # Root project picker
│ └── [projectId]/ # Per-project pages (board, chat, studio, db, docs, journals, settings)
├── components/ # React UI (organized by feature)
│ ├── shared/ # Reusable: Icon, MarkdownRenderer, NotificationBell, DropdownSelect, PriorityBadge
│ ├── layout/ # App shell: DashboardLayout, Navbar, Sidebar, useNotificationFeed
│ ├── chat/ # Chat: ChatView, ChatInput, ChatMessageBubble, TypingIndicator
│ ├── studio/ # Studio: CheckpointConfirmation, DocumentReviewPanel, QaWidgetRenderer
│ ├── kanban/ # Board: KanbanBoard, KanbanCard, TaskModal, TaskDetailModal
│ ├── conference/ # Conference: ConferenceView, ConferenceList, ConferenceDetail, EmptyState
│ ├── dashboard/ # Shared context: DashboardContext, useChatSession, chat-stream parser
│ ├── documents/ # Document table, editor, creation modal
│ ├── journals/ # Journal form, filters, timeline, entry cards
│ ├── db/ # Database viewer table
│ └── settings/ # Settings cards
├── lib/ # Backend core (no UI dependencies)
│ ├── agents/ # LangGraph state, routing, nodes, prompts, tools
│ │ ├── orchestration/studio/ # Studio-specific: state, nodes, loop, yield-gate, builders, context
│ │ ├── conference/ # Agents Conference: multi-turn inter-agent communication
│ │ ├── prompts/ # Role prompt stacks (Vision → Mission → Persona → Rules → System → Tools)
│ │ └── tools/ # 15 LLM-callable tools (web_search, take_note, read_document, run_conference, etc.)
│ ├── api-utils.ts # Shared API helpers: resolveAuth, forbiddenResponse, errorResponse
│ ├── db.ts # PostgreSQL pool singleton with exponential backoff retry
│ ├── rbac.ts # RBAC profiles, authorized roles, session access control
│ ├── llm/ # OpenAI-compatible model client (native fetch, no SDK)
│ ├── tickets/ # Ticket event system + role-behavior config + generic handler factory + listener
│ ├── core/ # Shared constants, utilities, types
│ └── types-db.ts # Database row type contracts
├── db/
│ └── init.sql # Full schema (23 tables) with indexes + seed data
├── migrations/ # Incremental DB migrations (auto-applied on startup)
├── docs/ # Technical documentation
│ ├── CONFERENCE.md # Multi-turn agent communication, prompt guide
│ ├── NOTIFICATIONS.md # Notification bell, unified feed, adding new sources
│ ├── STUDIO.md # Studio flow, state, tools, SSE protocol
│ ├── DATABASE.md # Schema reference, partitioning, queries
│ ├── APIS.md # API endpoint contracts
│ ├── RBAC.md # Role-based access control model
│ ├── TICKETS.md # Ticket event system
│ ├── AI-INTEGRATION.md # LLM provider setup + streaming
│ └── VERCEL.md # Deployment guide
├── code-rules-docs/ # Coding standards enforced in every session
│ ├── general-rules.md # TDD, git hooks, formatting, import sorting
│ ├── ui-rules.md # Design tokens, component structure, interactive IDs
│ ├── db-rules.md # Schema migrations, parameterization, type contracts
│ ├── backend-rules.md # API structure, JSDoc standards, error handling
│ └── tools-rules.md # Agent definitions, tool lifecycle, tool registry
└── scripts/ # CLI utilities (migrate.js, etc.)
Browser → Next.js App Router → Page (thin, delegates to view component)
│
▼
API Route (thin controller)
├── resolveAuth() → RBAC check
├── query() → PostgreSQL
└── SSE streaming → LLM Provider
All RBAC enforcement happens at the API route layer via x-user-profile header + lib/api-utils.ts. CSRF tokens are verified on all mutating requests (POST/PUT/PATCH/DELETE). Rate limiting is backed by Upstash Redis (distributed) with in-memory fallback. Database access flows through a single pool singleton in lib/db.ts with a withTransaction() helper for atomic multi-statement operations. The ticket event listener auto-starts with pnpm dev via Next.js instrumentation — no separate terminal needed. Quality gates run on pre-commit (lint-staged + related tests) and pre-push (type-check + lint + full test suite + build).
- Agents Conference — Multi-turn autonomous agent-to-agent communication. Any role can initiate a conference with any combination of target roles. Dynamic role composition merges prompt stacks into a composite panel. Strict "no assumptions" contract (ANSWER/CLARIFY/NO_ANSWER). Auto-escalation of unknowns to kanban tickets. Full conversation history persisted. See docs/CONFERENCE.md.
- Notification System — Reusable
NotificationBellcomponent with unread badge and dropdown. Unified notification feed API merges conference activity and ticket events. Polling-based client hook with unread tracking. Generic design — add new notification sources with zero UI changes. See docs/NOTIFICATIONS.md. - Studio: Intake & Scope — Multi-role Studio graph supporting PM-Customer intake and BA requirements analysis. PM-Customer conversation with progressive multi-checkpoint alignment, 12-section document generation, section-by-section review with all-sections-reviewed gating, and signing. BA autonomous FRD generation with Conference integration. 15 LLM tools available including read_document and run_conference. Role-parameterized SSE streaming + connection recovery. Extensible to any agent role via catalog.
- Kanban Board — Drag-and-drop task management with Postgres persistence. Columns: to_do → in_progress → review → done.
- Role Simulator — 11 agent profiles (Product Manager, Developers, QA Engineer, Security Reviewer, etc.) with RBAC-enforced access boundaries.
- AI Chat — Multi-agent streaming chat via SSE. Messages persist as JSONB in
conversations. - Document Hub — HTML document creation, editing, and folder-based organization.
- Partitioned Journals — Day-partitioned PostgreSQL journal logs with per-role scoping, per-ticket linking, and
ticketIdquery filter. - Ticket Event System — DB triggers auto-create tickets on version creation + downstream role handoff. Event handlers auto-transition kanban columns. Agent auto-invocation when tickets enter in_progress. In-process listener auto-starts with
pnpm dev. See docs/TICKETS.md. - Agent Role Reusability — Single
RoleBehaviorConfigper agent role drives all ticket transitions, tool access, context assembly, and document generation. Adding a new autonomous agent role is a config entry + 2 lines of registration — no per-role handler duplication. GenericcreateAgentHandler()factory replaces bespoke handlers. - Provider Agnostic — Multi-provider support: DeepSeek, OpenAI (GPT-5.4/5.5), Google Gemini (3.1/3.5). Swap via settings.
- Per-Agent LLM Configuration — Each AI agent role (PM, BA, Developers, etc.) can use a different provider, model, thinking level, and API key. Overlord sees all; role simulator shows only own config. Falls back to project defaults.
| Profile | Type | Access |
|---|---|---|
| KT | Customer (Overlord) | All roles, all sessions, all data |
| Role profiles (PM, Dev, QA, etc.) | Role | Locked to own role and session |
| Unknown | Restricted | Denied by default |
Session access uses segment-based matching (session_product_manager) to prevent substring collisions. See docs/RBAC.md.
pnpm test # 207 test files, 2919 tests
pnpm test:watch # Watch mode
pnpm test -- --coverage # With coverage (80% threshold)Tests are colocated with source files (e.g., Foo.test.ts next to Foo.ts). Each test covers Happy, Error, Empty, and Edge scenarios.
| Doc | Covers |
|---|---|
| Agents Conference | Multi-turn agent-to-agent communication, dynamic role composition, no-assumptions contract, ticket escalation |
| Studio: Intake & Scope | PM-Customer flow, multi-checkpoint alignment, state schema, 13 tools, SSE protocol, connection recovery, UI components |
| Notifications | Common notification bell component, unified feed API, conference + ticket event notifications, unread tracking |
| Database Schema | 21 tables, indexes, partitioning, seed data |
| API Reference | Endpoint contracts, request/response shapes |
| RBAC Guide | Role profiles, authorization, session boundaries |
| Ticket Events | Event-driven automation, handlers, kanban transitions |
| AI Integration | LLM provider setup, streaming, prompt architecture |
| Deployment | Vercel deployment guide |
All code follows the standards in code-rules-docs/:
- UI: Zero hardcoded colors, design token CSS variables, semantic HTML, interactive element IDs
- Backend: Thin API controllers, typed catches, 3-line [WHAT]/[IN]/[OUT] JSDoc on all exports
- Database: Parameterized queries only, migration for every schema change, UUIDs throughout
- General: TDD (test first), barrel exports, import sorting, Prettier formatting, Conventional Commits