RoadBoard

Multi-project execution, memory, and collaboration platform for humans and AI agents.

CI

Work in progress. RoadBoard 2.0 is under active development and not yet in beta. APIs, data models, and interfaces may change without notice. Not recommended for production use.

---

Why RoadBoard exists

Context loss is one of the most expensive problems in modern project work.

Teams lose track of decisions. Agents restart sessions without knowing what happened. Progress is scattered across chat threads, documents, and memory that belongs to no system. Work is repeated because no one can find what was already done.

RoadBoard is designed to be the operational control plane for complex project work — a single place where humans and AI agents share structured project state, preserve memory across sessions, and coordinate without losing context.

---

Core capabilities

• Multi-project planning — projects, phases, milestones, tasks, priorities, and dependencies
• Operational memory — persistent memory entries, decision records, and session handoffs
• Team collaboration — users, teams, project grants, role-based access control
• MCP agent access — 50 tools for agents to read and write project state via Model Context Protocol, with fine-grained per-token scope enforcement
• Atlas (CodeFlow) — interactive architecture map with domain groups, agent context view, drift validation, and Deep Code Map schema (File/Symbol/ExternalPackage)
• Audit trail — full activity log per project with filters by event type, actor type, and date range
• Project thumbnails — auto-refresh screenshots from project home URL + manual upload
• AI assistant — per-project chatbot config supporting Anthropic, OpenAI, and Ollama
• Web dashboard — swipeable project cards, skeleton loaders, task management, Atlas
• Async job layer — background refresh, summary generation, thumbnail refresh, and cleanup via BullMQ
• Local sync bridge — offline-first SQLite journal with sync engine to the central database

---

Architecture

apps/
  core-api          NestJS — projects, phases, tasks, memory, decisions, codeflow, release (port 3001)
  auth-access       NestJS — users, teams, sessions, MCP tokens (port 3002)
  mcp-service       MCP server (stdio + HTTP) — 50 tools for agent integration (port 3005)
  web-app           Next.js 15 — dashboard, project detail, task management, Atlas (port 3000)
  worker-jobs       NestJS + BullMQ — async jobs: refresh, summary, cleanup (port 3003)
  local-sync-bridge NestJS + SQLite — offline-first journal with sync engine (port 3004)

packages/
  domain            shared enums and domain types
  database          Prisma schema, migrations, seed
  auth              password hashing, token utilities
  grants            permission logic
  mcp-contracts     MCP tool schemas
  api-contracts     shared REST API types
  graph-db          Memgraph (Neo4j-compat) client + Cypher schema for CodeFlow
  demo-seed         seed content for "Tour Roadboard" demo project on signup
  local-storage     SQLite local-storage abstraction
  observability     logging/tracing setup
  config            env helpers

infra/
  docker/           docker-compose (PostgreSQL 16, Redis 7, Memgraph 2.18)
  systemd/          systemd .service + .path units for self-hosted deploy

Stack

• Runtime: Node.js 20, TypeScript strict
• Backend: NestJS 11 with Fastify adapter
• Frontend: Next.js 15 App Router, Tailwind CSS 4
• Database: PostgreSQL 16 (Prisma ORM), SQLite (local journal)
• Queue: Redis 7 + BullMQ
• Agent protocol: MCP (Model Context Protocol) via HTTP StreamableHTTP or stdio
• Monorepo: pnpm workspaces + Turborepo

---

Quickstart

Prerequisites

• Node.js 20+
• pnpm 9+
• Docker (for PostgreSQL and Redis)

Setup

# Clone
git clone https://github.com/Maless88/Roadboard.git
cd Roadboard

# Install dependencies
pnpm install

# Copy env and start infrastructure
cp .env.example .env
docker compose -f infra/docker/docker-compose.yml up -d

# Build all packages
pnpm build

The local Docker Compose stack now bootstraps Postgres, Redis, migrations, seed data, core-api, auth-access, mcp-service (HTTP on :3005), worker-jobs, local-sync-bridge, and the Next.js web-app.

Full local stack

# Build and run the full local stack
docker compose -f infra/docker/docker-compose.yml up -d --build

# Stop it
docker compose -f infra/docker/docker-compose.yml down

Start services

# core-api
DATABASE_URL="postgresql://roadboard:roadboard@localhost:5433/roadboard" \
  CORE_API_PORT=3001 AUTH_ACCESS_PORT=3002 \
  node apps/core-api/dist/main.js

# auth-access
DATABASE_URL="postgresql://roadboard:roadboard@localhost:5433/roadboard" \
  AUTH_ACCESS_PORT=3002 \
  node apps/auth-access/dist/main.js

# web-app (dev)
cd apps/web-app && pnpm dev

# worker-jobs
WORKER_JOBS_PORT=3003 node apps/worker-jobs/dist/main.js

# local-sync-bridge
LOCAL_SYNC_PORT=3004 JOURNAL_DB_PATH=.agent/journal.db \
  node apps/local-sync-bridge/dist/main.js

# mcp-service (HTTP mode)
MCP_TRANSPORT=http MCP_HTTP_PORT=3005 AUTH_ACCESS_PORT=3002 \
  node apps/mcp-service/dist/main.js

MCP server (for Claude / agent integration)

{
  "mcpServers": {
    "roadboard": {
      "command": "node",
      "args": ["apps/mcp-service/dist/main.js"],
      "env": {
        "MCP_TOKEN": "<your-mcp-token>",
        "CORE_API_PORT": "3001",
        "AUTH_ACCESS_PORT": "3002"
      }
    }
  }
}

For HTTP MCP clients, use http://127.0.0.1:3005/mcp with a bearer token issued by auth-access. Tokens carry a scopes array (GrantType[]) — each tool enforces the minimum required scope at call time.

API docs

• core-api: http://127.0.0.1:3001/docs
• auth-access: http://127.0.0.1:3002/docs

Health endpoints

• core-api: http://127.0.0.1:3001/health
• auth-access: http://127.0.0.1:3002/health
• worker-jobs: http://127.0.0.1:3003/health
• local-sync-bridge: http://127.0.0.1:3004/health
• mcp-service: http://127.0.0.1:3005/health
• web-app: http://127.0.0.1:3000/health

Seeded onboarding data

db:seed now creates a usable local onboarding state for roadboard-2:

• demo users and team memberships
• the Roadboard 2.0 project and admin grant
• the Wave 2 — Platform Hardening phase
• Wave 2 task and memory history aligned with the current repo state

---

MCP Tools

Each tool enforces a minimum GrantType scope. project.admin bypasses all checks.

Tool	Required scope	Description
initial_instructions	—	Operational protocol bootstrap (call once per session)
list_projects	project.read	List accessible projects
list_teams	project.read	List teams the caller belongs to (slug + role)
get_project	project.read	Get project details with phases
get_user	project.read	Get the current authenticated user
list_active_tasks	project.read	List tasks, optionally filtered by status
list_phases	project.read	List phases for a project
get_project_memory	project.read	List memory entries
prepare_task_context	project.read	Full context bundle for a specific task
prepare_project_summary	project.read	Project snapshot for agent onboarding
get_project_changelog	project.read	Structured changelog: tasks, phases, decisions, memory, audit
search_memory	project.read	Full-text search over memory entries
list_recent_decisions	project.read	List decisions, optionally filtered by status
list_skills	project.read	List available agent skills in the catalog
read_inbox	project.read	Read the agent inbox (notifications / email)
list_events	project.read	List calendar events
list_scheduled_activities	project.read	List scheduled (recurring) activities
create_task	task.write	Create a task in a phase (auto-selects first phase if omitted); accepts description, assigneeId, dueDate
update_task	task.write	Update title, description, phaseId, priority, assigneeId, or dueDate of an existing task
update_task_status	task.write	Update task status; accepts completionReport when marking done
delete_task	task.write	Delete a task
create_phase	project.write	Create a roadmap phase; can be linked to a decision via decisionId
update_phase	project.write	Update phase fields: title, status, dates, linked decision
attach_skill	project.write	Attach a skill to an agent / project
detach_skill	project.write	Detach a skill from an agent / project
sync_skills_catalog	project.write	Sync the agent skills catalog
mark_read	project.write	Mark inbox items as read
create_draft	project.write	Create an email / message draft
create_event	project.write	Create a calendar event
delete_event	project.write	Delete a calendar event
notify	project.write	Send a notification
create_scheduled_activity	project.write	Create a scheduled / recurring activity
create_reminder	project.write	Create a one-off reminder
pause_scheduled_activity	project.write	Pause a scheduled activity
delete_scheduled_activity	project.write	Delete a scheduled activity
create_memory_entry	memory.write	Create a memory entry
create_handoff	memory.write	Structured handoff entry for session continuity
create_decision	decision.write	Record an architectural decision; auto-logs to vault
update_decision	decision.write	Record outcome, change status, set resolvedAt
create_project	project.admin	Create a new project; auto-logs to vault
get_architecture_map	codeflow.read	Get the architecture graph (nodes + edges)
get_node_context	codeflow.read	Full context for an architecture node
get_architecture_snapshot	codeflow.read	Get a snapshot of the architecture graph
create_architecture_repository	codeflow.write	Register a CodeRepository for the project (one per onboarding)
create_architecture_node	codeflow.write	Add a workspace / module / service ArchitectureNode
create_architecture_edge	codeflow.write	Add a dependency edge (e.g. DEPENDS_ON / IMPORTS) between two nodes
create_architecture_link	codeflow.write	Tie a Task / Decision / Memory entry to an ArchitectureNode
link_task_to_node	codeflow.write	Semantic wrapper of create_architecture_link for tasks (call right after create_task)
create_architecture_annotation	codeflow.write	Attach a free-text note to an ArchitectureNode
ingest_architecture	codeflow.write	One-shot orchestrator: repository + nodes + edges + annotations in a single manifest call

---

Development

pnpm typecheck       # typecheck all packages
pnpm -r test         # run all tests
pnpm -r build        # build all packages and apps

---

Documentation

• ROADMAP.md — current milestone and upcoming phases
• CONTRIBUTING.md — how to contribute
• SECURITY.md — vulnerability reporting
• SUPPORT.md — where to ask questions
• CHANGELOG.md — version history
• docs/atlas-manual-use.md — using the Atlas architecture graph tab (Wave 5.1 manual MVP)
• docs/mcp-client-setup.md — connecting Claude Code or another MCP client to Roadboard
• docs/planning/ — architecture and design notes

---

Current status

Waves 1–6 are complete. The platform is functional end-to-end: REST APIs, MCP server, web dashboard, async jobs, local sync bridge, Memgraph-backed architecture graph, agent workspace (life-OS agents, rooms, scheduling, Telegram bridge), and self-hosted deploy are all implemented.

• Wave 3 — semantic memory search, agent-readable project changelog, richer decision model, memory summarization background jobs ✓
• Wave 4 — fine-grained MCP token scopes, project ownership model, per-project member management, MCP auto-vault, Phase–Decision linking, interactive Roadmap and Decisions accordions, 4 new MCP write tools ✓
• Wave 5.1 — Atlas (CodeFlow) manual MVP: ArchitectureNode/Edge/Link/Annotation, MCP atomic write tools, Architecture Map canvas in web-app, node detail drawer ✓
• Wave 5.2 — graph DB foundation: Memgraph 2.18 added to compose, @roadboard/graph-db Neo4j-compat client, dual-write GraphSyncService for nodes/edges, schema constraints + indexes ✓
• Wave 5.3 — agent-driven onboarding: ingest_architecture one-shot orchestrator, link_task_to_node semantic wrapper, enriched prepare_task_context with architecture nodes & decisions ✓
• Deploy UX — light/dark theme, single-pill release banner, self-hosted per-host deploy via systemd.path + systemd.service (no GitHub Actions workflow_dispatch needed) ✓
• CF-GDB-03b — Atlas storage cut over from Postgres to Memgraph: reads, writes and impact analysis are Memgraph-native; the architecture_* Prisma tables and GraphSyncService are retired ✓
• Wave 6 — Deep Code Map — file + symbol graph via ts-morph (deep-code-scan BullMQ queue), blast-radius queries on Memgraph ✓
• Agent workspace — life-OS agents with photorealistic avatars, agent rooms + Boardchat mobile, scheduling, skills catalog, durable memory (pgvector), Telegram bridge ✓

Active planning: LLM Runtime (provider registry, native OpenAI/Anthropic/Gemini adapters, Ollama baseline, per-role routing and budgets) and agent-platform hardening (human-in-the-loop permissions, context compaction, per-user runtimes). See ROADMAP.md.

The project is pre-beta. No stable release has been published yet. Breaking changes may occur on main.

---

Contributing

See CONTRIBUTING.md.

---

License

MIT — see LICENSE.