Visual Roadmap

The visual roadmap provides an interactive, drag-and-drop interface for planning and visualizing your project's milestones and business goals. Unlike traditional linear lists, the roadmap shows how work items relate to each other and contribute to your strategic objectives.

Goals vs Milestones

The roadmap visualizes two distinct types of items:

Milestones (Flag Icon)

Milestones are concrete, deliverable work items that your team executes. They represent specific features, releases, or deliverables that can be planned, worked on, and completed.

Characteristics:

• Contain work items (tasks) that teams complete
• Have detailed progress tracking
• Can be assigned to specific teams
• Track velocity and generate forecasts
• Move through status lifecycle: Concept → Planned → In Progress → Done

Visual Appearance:

• Rectangle shape with flag icon
• Shows team avatar and business value score
• Displays progress chart when in progress
• Color-coded by status (gray=Concept, purple=Planned, blue=In Progress, green=Done)

Goals (Target Icon)

Goals represent high-level business objectives or strategic outcomes. They provide context and direction for your work, showing why you're building certain features.

Characteristics:

• Multiple milestones can contribute to achieving a single goal
• Don't contain work items directly
• Help prioritize and align team efforts
• Provide business context for technical work

Visual Appearance:

• Circular shape with target icon
• Circular shape, visually distinct from milestones
• Shows business value score
• Same color-coding by status as milestones

Dependencies and Goal Paths

The roadmap visualizes two types of relationships between items:

Dependencies (Purple Arrows)

Dependencies show prerequisite relationships between milestones. A purple arrow from Milestone A to Milestone B means "A must be completed before B can start."

Features:

• Animated when on the critical path
• Prevents circular dependencies
• Used for forecast calculations
• Click to remove (Owners only)
• Enable reverse planning from goals backwards to current state

Goal Paths (Amber Arrows)

Goal paths represent your chosen route through the roadmap - the specific sequence of milestones you've decided to focus on right now to achieve your goals.

Think of your roadmap as a map showing many possible routes to your destination. Some paths are direct, others are scenic detours, and some are experiments you might explore later. The goal path highlights which route you're actually taking.

Why Goal Paths Matter:

Your roadmap can contain multiple options and ideas - not all of them need to align or happen. You might have:

• Experimental features you're considering
• Alternative approaches to the same problem
• Nice-to-have features for later
• Multiple ways to achieve a business outcome

The goal path lets you say "this is what we're doing now" without deleting the other options.

Features:

• Amber (orange) colored arrows to distinguish from regular dependencies
• Always animated to highlight your strategic focus
• Thicker than regular dependencies (4px vs 3px)
• Filter the roadmap to show only goal path work
• Multiple milestones can contribute to the same goal (parallel progress)
• Used to determine execution priority and forecasts

Setting the Goal Path:

When you mark a milestone as "on goal path" (isOnGoalPath = true):

1. It gets included in execution order calculations
2. It appears in schedule forecasts
3. It's prioritized for team assignment
4. It shows in the "Goal Path Only" filter

Milestones not on the goal path remain visible but are deprioritized - they're possibilities, not commitments.

Grid and Positioning

The roadmap uses an 80×80 pixel grid for consistent spacing:

• All nodes snap to grid when dragged
• Grid size: 80px
• Milestone nodes: 240px × 112px (3 grid squares wide)
• Goal nodes: 112px × 112px (circular within square bounds)

Position Persistence: When you drag a node to a new position, the coordinates are saved to the database and persist across sessions.

Editing and Permissions

Owner Permissions

Only project Owners can edit the roadmap structure:

• ✅ Drag nodes to reposition them
• ✅ Create new milestones/goals by double-clicking empty space
• ✅ Connect nodes by dragging from connection handles
• ✅ Delete dependencies by clicking edges
• ✅ Create dependencies using the + buttons that appear on hover

Viewer Permissions

Other roles (Collaborator, Stakeholder, Viewer) can:

• ✅ View the roadmap and all connections
• ✅ Click nodes to see details
• ✅ Use filters to focus on specific work
• ❌ Cannot drag, create, or modify structure

Interactive Features

Creating Connections

Drag from handles:

1. Hover over a milestone/goal to see purple connection handles on left and right
2. Drag from the source (right handle) of the prerequisite
3. Drop on the target (left handle) of the dependent milestone
4. The connection is created immediately

Using + buttons:

1. Hover over a milestone to see + buttons on left and right
2. Click the left + button to create a new prerequisite
3. Click the right + button to create a new dependent milestone
4. A new node is created and automatically connected

Creating New Nodes

Double-click creation:

1. Double-click empty space on the canvas
2. A dialog opens to configure the new milestone/goal
3. Choose type (Milestone or Goal), name, and description
4. The node is created at the clicked position (snapped to grid)

Deleting Connections

Click edges to delete:

1. Click any dependency edge (arrow)
2. Confirm deletion in the dialog
3. The dependency is removed (does not delete the milestones)

Filtering the View

Goal Path Filter:

• Toggle "Goal Path Only" to show only milestones that contribute to strategic goals
• Hides milestones not connected to goals via amber arrows
• Helps focus on strategic work vs exploratory/experimental work

Status Filters:

• "Exclude Done Milestones" hides completed work to declutter the view
• Status filters combine: you can show only in-progress work on the goal path

Visual Legend

The roadmap includes a comprehensive legend showing:

Status Colors:

• Gray: Concept (early ideation, not planned)
• Purple: Planned (scheduled but not started)
• Blue: In Progress (actively being worked on)
• Green: Done (completed)

Node Types:

• Flag icon = Milestone (concrete deliverable)
• Target icon = Goal (strategic objective)

Connection Types:

• Amber animated arrow = Dependency on goal path (4px width)
• Purple solid arrow = Regular dependency (3px width)

Usage Instructions:

• Drag nodes to reposition (Owners only)
• Double-click empty space to create new nodes
• Connect nodes by dragging from handles
• Click edges to delete dependencies

Technical Details

The roadmap is built with React Flow, a library for node-based UIs. Key technical features:

• Grid snapping: All positions snap to 80px grid for alignment
• Real-time updates: Changes sync immediately via TRPC mutations
• Server-side filtering: Goal path and status filters run on the backend for performance
• Includes optimization: Dependencies and team assignments are eagerly loaded to minimize queries
• Smooth animations: Uses CSS transitions and React Flow's built-in animation system

Use Cases

Reverse Planning from Goals

A practical approach is working backwards from your goals. Instead of planning forward from where you are, start with where you want to be.

How it works:

1. Create a Goal representing your desired business outcome (e.g., "Launch to Enterprise Market")
2. Work backwards by asking "What milestone must be completed right before this goal?"
3. Create that milestone and connect it to the goal with a dependency
4. Repeat for each milestone, asking "What must be done before this?"
5. Mark the path by setting isOnGoalPath = true for your chosen route

This creates a chain from your current state to your goal, breaking down a big objective into achievable milestones.

Example: Launching Enterprise Features

By reverse planning, you ensure every milestone directly contributes to your goal - no wasted effort.

Managing Multiple Options

Real projects involve exploration and alternatives. Your roadmap should capture possibilities without committing to all of them.

Pattern: Exploring alternatives

Both milestones connect to the goal, but only "Guided Checklist" is on the goal path. The tutorial remains visible as an alternative if the checklist doesn't work out.

Benefits:

• Preserve context about decisions not taken
• Quick pivot if initial approach fails
• Document alternative approaches for team discussion
• Filter to "Goal Path Only" to see committed work

Strategic Planning

Use goals to represent quarterly OKRs or business initiatives, then connect the milestones that will contribute to achieving them. This creates a visual map of how tactical work aligns with strategy.

The goal path shows which of those connections you're actively pursuing - your current strategy, not all possible strategies.

Dependency Management

Visualize the critical path through your project by connecting milestones with dependencies. The roadmap makes it obvious which work is blocking other work, helping you prioritize effectively.

When combined with goal paths, dependencies enable reverse planning: start with the goal and work backward to identify what must be done first.

Multi-team Coordination

When multiple teams contribute to a shared goal, the roadmap shows how their work streams converge. Assign team avatars to milestones to see who's working on what.

Use the goal path to coordinate: all teams know which of their milestones are on the critical path vs. exploratory work.

Progress Tracking

As milestones move through statuses (Concept → Planned → In Progress → Done), the color-coding provides an at-a-glance view of project health. Goals show progress charts based on completion of their own items.

Best Practices

1. Use goals sparingly

• Create goals for significant business outcomes, not every feature
• Typical projects have 3-7 major goals
• Too many goals dilute focus
• Consider using Goal-type milestones as sub-goals for hierarchy

2. Be intentional with the goal path

• The goal path is your commitment, not your wishlist
• Only mark milestones as "on goal path" if you're actively pursuing them
• Keep alternatives visible but off the goal path
• Review and adjust the goal path as priorities change

3. Use reverse planning

• Start with the goal (outcome) and work backwards
• Ask "What must be done immediately before this?" for each step
• This ensures every milestone directly serves the goal
• Creates clearer dependencies and reduces scope creep

4. Minimize dependency complexity

• Keep the graph as simple as possible
• Long dependency chains increase risk and forecast uncertainty
• Parallel work is better than sequential when possible
• Use dependencies to capture true prerequisites, not nice-to-haves

5. Use spatial layout meaningfully

• Position goals at strategic locations (often top-right as "north star")
• Flow dependencies left-to-right (past → future) or bottom-to-top (foundation → goal)
• Group related milestones visually
• Use the grid to create clear rows or columns
• Reverse planning often creates vertical or diagonal chains toward goals

6. Use filters strategically

• Use "Goal Path Only" during strategic reviews and planning sessions
• Use "Exclude Done" to focus on current/future work
• Combine filters to create different views for different audiences
• Full roadmap view (no filters) shows all possibilities and context
• Goal path view shows commitments and priorities

FAQ

Q: What's the difference between a dependency and being on the goal path?

A: Dependencies are prerequisite relationships ("A must finish before B starts"). The goal path is your chosen strategy ("these are the milestones we're focusing on now"). A milestone can have dependencies without being on the goal path - it might be an alternative approach you're keeping as a backup.

Q: Can I have multiple goal paths?

A: The isOnGoalPath property is currently binary (true/false), so there's one goal path per project. However, you can have parallel branches on that path - multiple milestones contributing to the same goal. For truly separate initiatives, consider using different projects or sub-goals.

Q: How do I reverse plan a milestone?

A: Start by creating your goal. Then create a milestone and connect it to the goal with a dependency (the milestone must complete before the goal is achieved). Repeat: create another milestone that must complete before the first one, and so on, until you reach something you can start today. Mark all these milestones as "on goal path" to prioritize them.

Q: Should everything on the roadmap be on the goal path?

A: No! The roadmap should contain explorations, alternatives, and "someday maybe" ideas. Only milestones you're actively committed to should be on the goal path. This keeps your strategy clear while preserving context about other options.

Q: Can I create circular dependencies?

A: No, the system prevents circular dependencies. You cannot create a dependency that would form a loop (e.g., A depends on B, B depends on C, C depends on A).

Q: What happens if I delete a milestone that has dependencies?

A: Deleting a milestone removes all its dependencies. Dependent milestones become unblocked, and prerequisites lose their connection.

Q: Can milestones contribute to multiple goals?

A: Yes. You can connect a milestone to multiple goals via dependencies. The roadmap visualizes all these connections, making it easy to see how work contributes to different objectives.

Q: How do forecasts use the roadmap data?

A: Forecasts traverse dependency chains to calculate cumulative duration. Only milestones on the goal path are included in execution order calculations and delivery forecasts. Off-path milestones are visible but not scheduled. See Understanding Project Forecasts for details.

Q: Can Collaborators see the roadmap?

A: Yes, all roles can view the roadmap. Only Owners can edit structure and positioning.

Q: Does the roadmap work on mobile?

A: The roadmap is optimized for desktop/tablet use. On mobile, you can view and navigate but editing is limited by screen size and touch precision.