lhumina_code/hero_planner

Fork 0

implement fancy viewer #3

New issue

Open

opened 2026-05-05 18:52:52 +00:00 by despiegk · 3 comments

despiegk commented

2026-05-05 18:52:52 +00:00

Owner

Hero Planner — Planning Map Functional Specifications

Purpose

The Planning Map is a new visual navigation experience for Hero Planner.

The existing tabular UI remains the primary interface for managing records through classic tabs, tables, and forms.

The Planning Map adds a graphical, interactive way to understand how all planning elements relate to each other. It allows users to explore a plan from strategy to execution, budget, revenue, resources, and risk.

The goal is not to replace the existing UI.

The goal is to add a dynamic visual layer on top of the existing data model.

Core Principle

Tables are where we maintain the plan.
The Planning Map is where we understand the plan.

Existing UI

The existing UI must remain unchanged as the main operational interface.

It includes classic tabs and table layouts for:

SWOT items
Necessary conditions
Requirements
Stories
Deliverables
Milestones
Cost centers
Costs
Revenue centers
Revenues
Resources
Currency rates
Comments
Links

Users can continue to create, edit, update, and delete records through the current forms and tables.

New Planning Map Experience

A new visual experience must be added.

This can be implemented as:

a new tab inside the existing application, or
a full-screen experience opened from the existing UI, or
both

Recommended label:

Planning Map

Optional action label:

Open Full Screen

The Planning Map should provide a large visual workspace where users can navigate all relationships between planning entities.

Main User Goal

The Planning Map should help a user answer questions such as:

Why are we doing this work?
What opportunity, weakness, or threat is driving the plan?
What conditions must be true for success?
What requirements are still missing?
What stories need to be executed?
What deliverables must be produced?
What milestones are at risk?
What does this plan cost?
What revenue does this plan create?
Which resources are assigned?
What is blocked?
What is overdue?
What can make the plan fail?

Visual Model

Each planning entity is represented as a visual card, node, or marker.

Relationships between entities are shown as visible lines.

The Planning Map should support open and close behaviour so the user can expand or collapse parts of the plan.

The map should never show the entire database by default. It should always start from a selected focus item and expand outward.

The user starts by selecting a focus entity.

Supported focus entities:

SWOT item
Necessary condition
Requirement
Story
Deliverable
Milestone
Cost center
Cost
Revenue center
Revenue
Resource

After selecting the focus entity, the Planning Map shows that item and its directly related items.

The user can then expand or collapse related branches.

Entry Points

From the Main UI

The existing application should include a new entry point:

Planning Map

This opens the general visual map experience.

From Any Table Row

Every relevant table row should include an action:

Show in Planning Map

When clicked, the Planning Map opens focused on that specific entity.

Example:

Story row → Show in Planning Map

This opens the map around the selected story and shows related conditions, deliverables, milestones, resources, costs, and comments.

From Entity Detail Forms

Entity detail forms should also include:

Show in Planning Map

This makes the visual navigation experience available from anywhere in the existing UI.

Core Interaction Requirements

Open and Close

Every visual item should be expandable and collapsible.

When closed, an item displays a summary.

Example:

Diligence Package
5 requirements
2 stories
€5k cost
1 blocked item
Due May 31

When opened, it reveals linked entities.

Example:

Diligence Package
  Requirements
  Stories
  Costs
  Milestones

The user should be able to open one branch without opening the full plan.

Focus on This

Every item should have a focus action:

Focus on this

When selected, the map recenters around that item and hides unrelated entities.

The focus view should show:

parent entities
direct child entities
linked costs
linked revenues
linked resources
linked milestones
comments
blocking or related items

This allows the user to move through the plan step by step without losing context.

Click to Inspect

Clicking a visual item opens a side panel.

The side panel should show:

title or name
description
entity type
status
priority
owner
deadline or target date
linked entities
comments
cost information, if relevant
revenue information, if relevant
resource information, if relevant

The side panel should include actions:

edit
open in table
add linked item
create link
remove link
add comment
focus on this

Search to Focus

The Planning Map should include search.

The user can search across all entity types.

Search results should show:

entity title or name
entity type
status
owner, if available
deadline, if available

Selecting a search result should focus the map on that entity.

Filters

The Planning Map should allow users to filter visible entity types.

Supported filters:

SWOT items
Necessary conditions
Requirements
Stories
Deliverables
Milestones
Cost centers
Costs
Revenue centers
Revenues
Resources
Comments
Links

Users should be able to hide or show entity types without deleting anything.

View Modes

The Planning Map should support different view modes.

Each view mode shows a different slice of the same underlying plan.

Strategy View

Purpose

To understand why the work exists and what strategic context drives it.

Primary Entities

SWOT items
Necessary conditions
Requirements

Main Questions

Which opportunity are we pursuing?
Which weakness must be fixed?
Which threat must be mitigated?
What must be true for success?
What requirements are still missing?

Typical Flow

SWOT Item → Necessary Condition → Requirement

Execution View

Purpose

To understand what work needs to be done and what outputs must be produced.

Primary Entities

Necessary conditions
Stories
Deliverables
Milestones
Resources

Main Questions

What work is required?
Who owns it?
What deliverables are expected?
Which milestones depend on this work?
What is blocked?
What is overdue?

Typical Flow

Condition → Story → Deliverable
Condition → Story → Milestone
Story → Resource

Finance View

Purpose

To understand cost, revenue, and budget impact.

Primary Entities

SWOT opportunities
Necessary conditions
Costs
Cost centers
Revenues
Revenue centers

Main Questions

What does this plan cost?
Which conditions require budget?
Which cost center absorbs the spend?
What revenue is expected?
Which revenue center does it belong to?
Is the plan financially attractive?

Typical Flow

Opportunity → Condition → Cost → Cost Center
Opportunity → Revenue → Revenue Center

Risk View

Purpose

To understand where the plan can fail.

Primary Entities

SWOT weaknesses
SWOT threats
Necessary conditions
Blocked stories
At-risk milestones
Missing requirements

Main Questions

What can prevent success?
Which conditions are blocked?
Which stories are blocked?
Which milestones are at risk?
Which items have no owner?
Which deadlines are missed?

Typical Flow

Weakness / Threat → Condition → Story → Milestone

Resource View

Purpose

To understand people, infrastructure, capacity, and allocation.

Primary Entities

Resources
Stories
Deliverables
Milestones
Costs

Main Questions

Which resources are assigned?
Which stories depend on which resources?
Which resources are overloaded?
Which resources have a cost rate?
What capacity is missing?

Typical Flow

Resource → Story → Deliverable
Resource → Story → Milestone

Visual Entity Types

SWOT Item

A SWOT item should appear as a strategic card.

It should clearly show its kind:

Strength
Weakness
Opportunity
Threat

It should show:

title
kind
priority
owner
status
deadline, if available

Necessary Condition

A necessary condition should appear as a prerequisite or blocker card.

It should show:

title
priority
owner
deadline
status
estimated cost, if available
number of linked requirements
number of linked stories

Requirement

A requirement should appear as a checklist-style card.

It should show:

title
priority
owner
deadline
status

Story

A story should appear as a work card.

It should show:

title
priority
owner
timeframe
deadline
status
number of deliverables
linked milestone, if available

Deliverable

A deliverable should appear as an output card.

It should show:

title
owner
deadline
status

Milestone

A milestone should appear as a date marker.

It should show:

title
target date
status
number of linked stories
number of linked conditions

Cost Center

A cost center should appear as a budget bucket.

It should show:

name
kind
owner
total linked cost
number of cost items

Cost

A cost should appear as an expense chip or cost card.

It should show:

title
amount
currency
normalised EUR value, if available
cost center
owner
status

Revenue Center

A revenue center should appear as an income bucket.

It should show:

name
kind
owner
total linked revenue
number of revenue items

Revenue

A revenue should appear as an income chip or revenue card.

It should show:

title
amount
currency
normalised EUR value, if available
revenue center
owner
status

Resource

A resource should appear as a person or infrastructure card.

It should show:

name
kind
availability
cost
currency
cost period
number of linked stories

Comment

Comments should not appear as large primary nodes by default.

They should appear as indicators on entity cards.

Example:

3 comments

Clicking the indicator opens the comments section in the side panel.

Link

Links should appear as visible relationship lines between entities.

Where possible, the Planning Map should infer a human-readable relationship label from the connected entity types.

Examples:

From	To	Label
SWOT Opportunity	Necessary Condition	requires
Necessary Condition	Requirement	requires
Necessary Condition	Story	addressed by
Necessary Condition	Cost	costs
Story	Deliverable	produces
Story	Milestone	due by
Story	Resource	assigned to
Opportunity	Revenue	generates
Cost	Cost Center	belongs to
Revenue	Revenue Center	belongs to

Collapsed Summary Behaviour

When a node or group is collapsed, it should display summary information.

Examples:

Opportunity Summary

Close $1M Customer Deal
4 conditions
7 stories
€48k cost
€1M revenue
2 blocked
3 overdue

Condition Summary

Diligence Package Ready
5 requirements
2 stories
€5k cost
1 milestone
status: blocked

Story Summary

Prepare Customer Proposal
2 deliverables
1 milestone
2 resources
due May 20
status: in progress

Resource Summary

Senior Developer
3 linked stories
daily rate: €750
availability: partial

Status and Health Indicators

The Planning Map should visually indicate health.

Supported indicators:

done
in progress
open
blocked
cancelled
overdue
missing owner
missing deadline
over budget
missing linked requirement
missing linked story
milestone at risk

These indicators should be visible on cards and usable in filters.

Metrics Panel

The Planning Map should include a compact summary panel.

It should show context-specific metrics for the currently focused map.

Suggested metrics:

total number of visible entities
total estimated cost
total expected revenue
margin or net value
number of blocked items
number of overdue items
number of unassigned items
number of missing deadlines
number of open conditions
number of completed deliverables

The metrics should update when the user changes focus, filters, or view mode.

Breadcrumbs

The Planning Map should show a breadcrumb path when navigating.

Example:

Customer Deal A → Diligence Package → Prepare Diligence Story

Breadcrumbs allow the user to move back to earlier focus points.

Mini Map

For larger maps, the Planning Map should include a small overview mini map.

The mini map helps users understand where they are in the larger visual structure.

Presentation Mode

The Planning Map should support a read-only presentation mode.

Presentation mode should:

hide editing controls
simplify the visual layout
show high-level summaries
support stepping through view modes
allow the user to present the plan in a meeting

Linking Behaviour

The Planning Map must support creating and removing links between entities.

Users should be able to:

create a link from one selected entity to another
remove an existing link
view all links for the selected entity
open either side of a link
focus the map on the linked entity

Creating or removing a link in the Planning Map must update the same underlying data used by the existing table UI.

Editing Behaviour

The Planning Map should allow editing through the side panel.

However, the Planning Map does not need to replace the full table forms.

Minimum editing requirements:

update title or name
update description
update status
update priority
update owner
update deadline or target date
add comment
create linked item
create link
remove link

The side panel should also include:

Open full form

or:

Open in table

This gives access to the existing full editing interface.

Data Consistency

The Planning Map must use the same data as the existing tabs and tables.

Any change made in the Planning Map must be reflected in the classic UI.

Any change made in the classic UI must be reflected in the Planning Map.

The Planning Map must not create a separate planning model.

Empty States

No Focus Selected

Show:

Select an item to start exploring your plan.

Suggested starting options:

choose opportunity
choose milestone
choose condition
choose story
search all entities

No Links Found

Show:

This item has no linked entities yet.

Suggested actions:

add linked item
create link
open in table

Too Many Items

If the map would show too many items, show a warning:

This map contains many linked items. Start with a smaller focus or apply filters.

Suggested actions:

focus on one entity
switch view mode
hide entity types
collapse all
show direct links only

Required Actions

Each visual entity should support these actions where relevant:

open
collapse
expand
focus on this
edit
open in table
add linked item
create link
remove link
add comment

Required Controls

The Planning Map should include:

search
focus selector
view mode selector
entity type filters
status filters
expand all direct links
collapse all
reset view
open full screen
presentation mode
metrics panel
legend

Example: Deal Planning

User opens Planning Map.
User selects Opportunity: Close $1M customer deal.
Map shows linked necessary conditions.
User expands Diligence package must be ready.
Map shows linked requirements, stories, costs, and milestones.
User clicks Prepare diligence package.
Side panel opens with owner, status, deadline, deliverables, and comments.
User sees the story is blocked.
User switches to Risk View.
Map highlights the blocked condition and at-risk milestone.
User adds a comment and assigns an owner.
User opens the same story in the classic table form for full editing.

MVP Requirements

Add a new Planning Map entry point.
Allow opening the Planning Map from any table row using Show in Planning Map.
Allow selecting a focus entity.
Show the selected entity as the center of the map.
Show directly linked entities around the focus entity.
Allow expanding linked entities.
Allow collapsing linked entities.
Show different visual cards for major entity types.
Show relationship lines between linked entities.
Open a side panel when clicking an entity.
Show entity details in the side panel.
Allow basic editing from the side panel.
Allow adding comments from the side panel.
Allow creating links from the side panel.
Allow removing links from the side panel.
Add entity type filters.
Add status filters.
Add search-to-focus.
Add basic status and health indicators.
Add Open in table action.
Add Focus on this action.
Add collapse all and reset view actions.

Advanced Requirements

Add Strategy View.
Add Execution View.
Add Finance View.
Add Risk View.
Add Resource View.
Add collapsed summary cards.
Add calculated cost summaries.
Add calculated revenue summaries.
Add margin or net value summary.
Add milestone risk indicators.
Add missing owner indicators.
Add missing deadline indicators.
Add over-budget indicators.
Add breadcrumb navigation.
Add mini map.
Add presentation mode.
Add saved visual views.
Add relationship labels inferred from entity types.
Add ability to compare cost versus revenue for a selected opportunity.
Add ability to highlight everything blocking a selected milestone.
Add ability to highlight all work assigned to a selected resource.
Add ability to show only direct links or all expanded links.
Add ability to export or share a read-only map view.

Non-Goals

The Planning Map should not replace the existing table UI.

The Planning Map should not require users to manage all records visually.

The Planning Map should not show the full database by default.

The Planning Map should not become a separate data model.

The Planning Map should not force a strict hierarchy, because the underlying system allows any entity to link to any other entity.

Success Criteria

The Planning Map is successful if a user can:

open a plan visually from any existing table item
understand why a piece of work exists
see what conditions, stories, deliverables, costs, revenues, milestones, and resources are connected
expand and collapse the plan without getting lost
quickly identify blocked or risky items
navigate from visual map to classic table form
edit basic fields without leaving the map
use the map in a planning or deal review meeting

Product Summary

Hero Planner should keep its existing table-based UI for structured data management.

The new Planning Map should provide a graphical, full-screen, open-and-close planning experience.

It should make the system feel alive, connected, and strategic.

The user should be able to move from:

Opportunity

to:

Conditions

to:

Stories

to:

Deliverables

to:

Milestones

to:

Costs, Revenues, and Resources

without losing the strategic context.

TECH

use Cytoscape.js

# Hero Planner — Planning Map Functional Specifications ## Purpose The Planning Map is a new visual navigation experience for Hero Planner. The existing tabular UI remains the primary interface for managing records through classic tabs, tables, and forms. The Planning Map adds a graphical, interactive way to understand how all planning elements relate to each other. It allows users to explore a plan from strategy to execution, budget, revenue, resources, and risk. The goal is not to replace the existing UI. The goal is to add a dynamic visual layer on top of the existing data model. --- ## Core Principle ```text Tables are where we maintain the plan. The Planning Map is where we understand the plan. ``` --- ## Existing UI The existing UI must remain unchanged as the main operational interface. It includes classic tabs and table layouts for: * SWOT items * Necessary conditions * Requirements * Stories * Deliverables * Milestones * Cost centers * Costs * Revenue centers * Revenues * Resources * Currency rates * Comments * Links Users can continue to create, edit, update, and delete records through the current forms and tables. --- ## New Planning Map Experience A new visual experience must be added. This can be implemented as: * a new tab inside the existing application, or * a full-screen experience opened from the existing UI, or * both Recommended label: ```text Planning Map ``` Optional action label: ```text Open Full Screen ``` The Planning Map should provide a large visual workspace where users can navigate all relationships between planning entities. --- ## Main User Goal The Planning Map should help a user answer questions such as: * Why are we doing this work? * What opportunity, weakness, or threat is driving the plan? * What conditions must be true for success? * What requirements are still missing? * What stories need to be executed? * What deliverables must be produced? * What milestones are at risk? * What does this plan cost? * What revenue does this plan create? * Which resources are assigned? * What is blocked? * What is overdue? * What can make the plan fail? --- ## Visual Model Each planning entity is represented as a visual card, node, or marker. Relationships between entities are shown as visible lines. The Planning Map should support open and close behaviour so the user can expand or collapse parts of the plan. The map should never show the entire database by default. It should always start from a selected focus item and expand outward. --- ## Focus-Based Navigation The user starts by selecting a focus entity. Supported focus entities: * SWOT item * Necessary condition * Requirement * Story * Deliverable * Milestone * Cost center * Cost * Revenue center * Revenue * Resource After selecting the focus entity, the Planning Map shows that item and its directly related items. The user can then expand or collapse related branches. --- ## Entry Points ### From the Main UI The existing application should include a new entry point: ```text Planning Map ``` This opens the general visual map experience. ### From Any Table Row Every relevant table row should include an action: ```text Show in Planning Map ``` When clicked, the Planning Map opens focused on that specific entity. Example: ```text Story row → Show in Planning Map ``` This opens the map around the selected story and shows related conditions, deliverables, milestones, resources, costs, and comments. ### From Entity Detail Forms Entity detail forms should also include: ```text Show in Planning Map ``` This makes the visual navigation experience available from anywhere in the existing UI. --- ## Core Interaction Requirements ### Open and Close Every visual item should be expandable and collapsible. When closed, an item displays a summary. Example: ```text Diligence Package 5 requirements 2 stories €5k cost 1 blocked item Due May 31 ``` When opened, it reveals linked entities. Example: ```text Diligence Package Requirements Stories Costs Milestones ``` The user should be able to open one branch without opening the full plan. --- ### Focus on This Every item should have a focus action: ```text Focus on this ``` When selected, the map recenters around that item and hides unrelated entities. The focus view should show: * parent entities * direct child entities * linked costs * linked revenues * linked resources * linked milestones * comments * blocking or related items This allows the user to move through the plan step by step without losing context. --- ### Click to Inspect Clicking a visual item opens a side panel. The side panel should show: * title or name * description * entity type * status * priority * owner * deadline or target date * linked entities * comments * cost information, if relevant * revenue information, if relevant * resource information, if relevant The side panel should include actions: * edit * open in table * add linked item * create link * remove link * add comment * focus on this --- ### Search to Focus The Planning Map should include search. The user can search across all entity types. Search results should show: * entity title or name * entity type * status * owner, if available * deadline, if available Selecting a search result should focus the map on that entity. --- ### Filters The Planning Map should allow users to filter visible entity types. Supported filters: * SWOT items * Necessary conditions * Requirements * Stories * Deliverables * Milestones * Cost centers * Costs * Revenue centers * Revenues * Resources * Comments * Links Users should be able to hide or show entity types without deleting anything. --- ## View Modes The Planning Map should support different view modes. Each view mode shows a different slice of the same underlying plan. --- ## Strategy View ### Purpose To understand why the work exists and what strategic context drives it. ### Primary Entities * SWOT items * Necessary conditions * Requirements ### Main Questions * Which opportunity are we pursuing? * Which weakness must be fixed? * Which threat must be mitigated? * What must be true for success? * What requirements are still missing? ### Typical Flow ```text SWOT Item → Necessary Condition → Requirement ``` --- ## Execution View ### Purpose To understand what work needs to be done and what outputs must be produced. ### Primary Entities * Necessary conditions * Stories * Deliverables * Milestones * Resources ### Main Questions * What work is required? * Who owns it? * What deliverables are expected? * Which milestones depend on this work? * What is blocked? * What is overdue? ### Typical Flow ```text Condition → Story → Deliverable Condition → Story → Milestone Story → Resource ``` --- ## Finance View ### Purpose To understand cost, revenue, and budget impact. ### Primary Entities * SWOT opportunities * Necessary conditions * Costs * Cost centers * Revenues * Revenue centers ### Main Questions * What does this plan cost? * Which conditions require budget? * Which cost center absorbs the spend? * What revenue is expected? * Which revenue center does it belong to? * Is the plan financially attractive? ### Typical Flow ```text Opportunity → Condition → Cost → Cost Center Opportunity → Revenue → Revenue Center ``` --- ## Risk View ### Purpose To understand where the plan can fail. ### Primary Entities * SWOT weaknesses * SWOT threats * Necessary conditions * Blocked stories * At-risk milestones * Missing requirements ### Main Questions * What can prevent success? * Which conditions are blocked? * Which stories are blocked? * Which milestones are at risk? * Which items have no owner? * Which deadlines are missed? ### Typical Flow ```text Weakness / Threat → Condition → Story → Milestone ``` --- ## Resource View ### Purpose To understand people, infrastructure, capacity, and allocation. ### Primary Entities * Resources * Stories * Deliverables * Milestones * Costs ### Main Questions * Which resources are assigned? * Which stories depend on which resources? * Which resources are overloaded? * Which resources have a cost rate? * What capacity is missing? ### Typical Flow ```text Resource → Story → Deliverable Resource → Story → Milestone ``` --- ## Visual Entity Types ### SWOT Item A SWOT item should appear as a strategic card. It should clearly show its kind: * Strength * Weakness * Opportunity * Threat It should show: * title * kind * priority * owner * status * deadline, if available --- ### Necessary Condition A necessary condition should appear as a prerequisite or blocker card. It should show: * title * priority * owner * deadline * status * estimated cost, if available * number of linked requirements * number of linked stories --- ### Requirement A requirement should appear as a checklist-style card. It should show: * title * priority * owner * deadline * status --- ### Story A story should appear as a work card. It should show: * title * priority * owner * timeframe * deadline * status * number of deliverables * linked milestone, if available --- ### Deliverable A deliverable should appear as an output card. It should show: * title * owner * deadline * status --- ### Milestone A milestone should appear as a date marker. It should show: * title * target date * status * number of linked stories * number of linked conditions --- ### Cost Center A cost center should appear as a budget bucket. It should show: * name * kind * owner * total linked cost * number of cost items --- ### Cost A cost should appear as an expense chip or cost card. It should show: * title * amount * currency * normalised EUR value, if available * cost center * owner * status --- ### Revenue Center A revenue center should appear as an income bucket. It should show: * name * kind * owner * total linked revenue * number of revenue items --- ### Revenue A revenue should appear as an income chip or revenue card. It should show: * title * amount * currency * normalised EUR value, if available * revenue center * owner * status --- ### Resource A resource should appear as a person or infrastructure card. It should show: * name * kind * availability * cost * currency * cost period * number of linked stories --- ### Comment Comments should not appear as large primary nodes by default. They should appear as indicators on entity cards. Example: ```text 3 comments ``` Clicking the indicator opens the comments section in the side panel. --- ### Link Links should appear as visible relationship lines between entities. Where possible, the Planning Map should infer a human-readable relationship label from the connected entity types. Examples: | From | To | Label | | ------------------- | ------------------- | ------------ | | SWOT Opportunity | Necessary Condition | requires | | Necessary Condition | Requirement | requires | | Necessary Condition | Story | addressed by | | Necessary Condition | Cost | costs | | Story | Deliverable | produces | | Story | Milestone | due by | | Story | Resource | assigned to | | Opportunity | Revenue | generates | | Cost | Cost Center | belongs to | | Revenue | Revenue Center | belongs to | --- ## Collapsed Summary Behaviour When a node or group is collapsed, it should display summary information. Examples: ### Opportunity Summary ```text Close $1M Customer Deal 4 conditions 7 stories €48k cost €1M revenue 2 blocked 3 overdue ``` ### Condition Summary ```text Diligence Package Ready 5 requirements 2 stories €5k cost 1 milestone status: blocked ``` ### Story Summary ```text Prepare Customer Proposal 2 deliverables 1 milestone 2 resources due May 20 status: in progress ``` ### Resource Summary ```text Senior Developer 3 linked stories daily rate: €750 availability: partial ``` --- ## Status and Health Indicators The Planning Map should visually indicate health. Supported indicators: * done * in progress * open * blocked * cancelled * overdue * missing owner * missing deadline * over budget * missing linked requirement * missing linked story * milestone at risk These indicators should be visible on cards and usable in filters. --- ## Metrics Panel The Planning Map should include a compact summary panel. It should show context-specific metrics for the currently focused map. Suggested metrics: * total number of visible entities * total estimated cost * total expected revenue * margin or net value * number of blocked items * number of overdue items * number of unassigned items * number of missing deadlines * number of open conditions * number of completed deliverables The metrics should update when the user changes focus, filters, or view mode. --- ## Breadcrumbs The Planning Map should show a breadcrumb path when navigating. Example: ```text Customer Deal A → Diligence Package → Prepare Diligence Story ``` Breadcrumbs allow the user to move back to earlier focus points. --- ## Mini Map For larger maps, the Planning Map should include a small overview mini map. The mini map helps users understand where they are in the larger visual structure. --- ## Presentation Mode The Planning Map should support a read-only presentation mode. Presentation mode should: * hide editing controls * simplify the visual layout * show high-level summaries * support stepping through view modes * allow the user to present the plan in a meeting Suggested presentation sequence: ```text 1. Strategy View 2. Execution View 3. Finance View 4. Risk View 5. Resource View ``` --- ## Linking Behaviour The Planning Map must support creating and removing links between entities. Users should be able to: * create a link from one selected entity to another * remove an existing link * view all links for the selected entity * open either side of a link * focus the map on the linked entity Creating or removing a link in the Planning Map must update the same underlying data used by the existing table UI. --- ## Editing Behaviour The Planning Map should allow editing through the side panel. However, the Planning Map does not need to replace the full table forms. Minimum editing requirements: * update title or name * update description * update status * update priority * update owner * update deadline or target date * add comment * create linked item * create link * remove link The side panel should also include: ```text Open full form ``` or: ```text Open in table ``` This gives access to the existing full editing interface. --- ## Data Consistency The Planning Map must use the same data as the existing tabs and tables. Any change made in the Planning Map must be reflected in the classic UI. Any change made in the classic UI must be reflected in the Planning Map. The Planning Map must not create a separate planning model. --- ## Empty States ### No Focus Selected Show: ```text Select an item to start exploring your plan. ``` Suggested starting options: * choose opportunity * choose milestone * choose condition * choose story * search all entities ### No Links Found Show: ```text This item has no linked entities yet. ``` Suggested actions: * add linked item * create link * open in table ### Too Many Items If the map would show too many items, show a warning: ```text This map contains many linked items. Start with a smaller focus or apply filters. ``` Suggested actions: * focus on one entity * switch view mode * hide entity types * collapse all * show direct links only --- ## Required Actions Each visual entity should support these actions where relevant: * open * collapse * expand * focus on this * edit * open in table * add linked item * create link * remove link * add comment --- ## Required Controls The Planning Map should include: * search * focus selector * view mode selector * entity type filters * status filters * expand all direct links * collapse all * reset view * open full screen * presentation mode * metrics panel * legend --- ## Suggested Navigation Flow ### Example: Deal Planning 1. User opens Planning Map. 2. User selects Opportunity: `Close $1M customer deal`. 3. Map shows linked necessary conditions. 4. User expands `Diligence package must be ready`. 5. Map shows linked requirements, stories, costs, and milestones. 6. User clicks `Prepare diligence package`. 7. Side panel opens with owner, status, deadline, deliverables, and comments. 8. User sees the story is blocked. 9. User switches to Risk View. 10. Map highlights the blocked condition and at-risk milestone. 11. User adds a comment and assigns an owner. 12. User opens the same story in the classic table form for full editing. --- ## MVP Requirements * [ ] Add a new `Planning Map` entry point. * [ ] Allow opening the Planning Map from any table row using `Show in Planning Map`. * [ ] Allow selecting a focus entity. * [ ] Show the selected entity as the center of the map. * [ ] Show directly linked entities around the focus entity. * [ ] Allow expanding linked entities. * [ ] Allow collapsing linked entities. * [ ] Show different visual cards for major entity types. * [ ] Show relationship lines between linked entities. * [ ] Open a side panel when clicking an entity. * [ ] Show entity details in the side panel. * [ ] Allow basic editing from the side panel. * [ ] Allow adding comments from the side panel. * [ ] Allow creating links from the side panel. * [ ] Allow removing links from the side panel. * [ ] Add entity type filters. * [ ] Add status filters. * [ ] Add search-to-focus. * [ ] Add basic status and health indicators. * [ ] Add `Open in table` action. * [ ] Add `Focus on this` action. * [ ] Add collapse all and reset view actions. --- ## Advanced Requirements * [ ] Add Strategy View. * [ ] Add Execution View. * [ ] Add Finance View. * [ ] Add Risk View. * [ ] Add Resource View. * [ ] Add collapsed summary cards. * [ ] Add calculated cost summaries. * [ ] Add calculated revenue summaries. * [ ] Add margin or net value summary. * [ ] Add milestone risk indicators. * [ ] Add missing owner indicators. * [ ] Add missing deadline indicators. * [ ] Add over-budget indicators. * [ ] Add breadcrumb navigation. * [ ] Add mini map. * [ ] Add presentation mode. * [ ] Add saved visual views. * [ ] Add relationship labels inferred from entity types. * [ ] Add ability to compare cost versus revenue for a selected opportunity. * [ ] Add ability to highlight everything blocking a selected milestone. * [ ] Add ability to highlight all work assigned to a selected resource. * [ ] Add ability to show only direct links or all expanded links. * [ ] Add ability to export or share a read-only map view. --- ## Non-Goals The Planning Map should not replace the existing table UI. The Planning Map should not require users to manage all records visually. The Planning Map should not show the full database by default. The Planning Map should not become a separate data model. The Planning Map should not force a strict hierarchy, because the underlying system allows any entity to link to any other entity. --- ## Success Criteria The Planning Map is successful if a user can: * open a plan visually from any existing table item * understand why a piece of work exists * see what conditions, stories, deliverables, costs, revenues, milestones, and resources are connected * expand and collapse the plan without getting lost * quickly identify blocked or risky items * navigate from visual map to classic table form * edit basic fields without leaving the map * use the map in a planning or deal review meeting --- ## Product Summary Hero Planner should keep its existing table-based UI for structured data management. The new Planning Map should provide a graphical, full-screen, open-and-close planning experience. It should make the system feel alive, connected, and strategic. The user should be able to move from: ```text Opportunity ``` to: ```text Conditions ``` to: ```text Stories ``` to: ```text Deliverables ``` to: ```text Milestones ``` to: ```text Costs, Revenues, and Resources ``` without losing the strategic context. # TECH use Cytoscape.js

despiegk commented

2026-05-05 18:59:00 +00:00

Author

Owner

Implementation Spec for Issue #3

Objective

Add a new "Planning Map" — an interactive, focus-based visual graph of planning entities — to the existing hero_planner_web UI, without altering the data model. Reuses the same /rpc JSON-RPC backend that drives the current table UI; adds a new top-level tab plus "Show in Planning Map" entry points from rows and detail forms. Targets the issue's MVP requirements only.

Requirements (MVP, from issue)

New "Planning Map" tab and "Show in Planning Map" actions from row + detail.
Visual nodes for all entity types (SWOT, condition, requirement, story, deliverable, milestone, cost_center, revenue_center, cost, revenue, resource), colored/iconed by type.
Edges drawn from link.list results plus implicit refs (cost/revenue entity_type/entity_id, cost_center_id/revenue_center_id).
Focus mode: pick one entity, render that entity + its directly linked neighbors. Click a neighbor to refocus.
Side panel on node click: title, description, type, status, priority, owner, deadline, linked entities, comments. Actions: edit basic fields, open in table, add linked item, create link, remove link, add comment, focus on this.
Search-to-focus across all entity types.
Entity-type filters (toggle visibility per type).
Status/health visual indicators (color border or badge by status/priority).
Breadcrumb of focus history.
Data consistency: no new model, no new RPC methods.

Tech Approach

Library: Cytoscape.js (UMD via CDN). Drop-in <script> tag fits the current Bootstrap-from-CDN pattern in index.html; no build pipeline change. Built-in nodes/edges, type styling, layouts (cose/breadthfirst/concentric), pan/zoom, click handlers, and BFS/neighborhood selectors. MIT license, ~350 KB minified.
Architecture: New map tab alongside existing tabs. Map code added inline in index.html to match the existing single-file pattern. Reuses existing rpc(), ENTITIES, linkType/fromLinkType, and cache helpers.
Data flow: On focus(entity), call (in parallel) <type>.get, link.list, comment.list, plus targeted neighbor .get to resolve neighbor titles. Render Cytoscape with focus + 1-hop neighborhood. The map never holds the full graph in MVP — it always renders one neighborhood for performance.
Edges: (a) bidirectional link.list results between any pair of types; (b) implicit refs (cost.entity_type/entity_id, revenue.entity_type/entity_id, cost.cost_center_id, revenue.revenue_center_id) drawn as dashed edges with a different label.
Entry points: new <li> in #main-tabs, hash routes #/map and #/map/<type>/<id>, and a "Show in Planning Map" button on each entity row card and inside the detail-pane header.