mirror of
https://github.com/BradGroux/veritas-kanban.git
synced 2026-10-08 20:57:51 +00:00
70c8c06e56
v4.0 docs update: CHANGELOG, README, FEATURES, API-REFERENCE, 11 new SOPs, MCP docs, version bumps to 4.0.0, docs cleanup. Closes #229.
146 lines
5.6 KiB
Markdown
146 lines
5.6 KiB
Markdown
# Design: Parallel Work Stream Visualization
|
|
|
|
**Status:** Design Draft
|
|
**GitHub Issue:** #43
|
|
**Priority:** Medium
|
|
|
|
## Overview
|
|
|
|
Add a timeline/swimlane view to visualize parallel task execution, showing which tasks ran concurrently, how long each took, and where bottlenecks occurred.
|
|
|
|
## Use Cases
|
|
|
|
1. **Multi-agent sprint review** — After spawning 12 parallel agents, see which completed first, where time was spent
|
|
2. **Bottleneck detection** — Identify tasks that blocked others or took unexpectedly long
|
|
3. **Capacity planning** — Understand actual parallelism achieved vs theoretical max
|
|
4. **Sprint retrospective** — Visualize sprint execution for process improvement
|
|
|
|
## Proposed Architecture
|
|
|
|
### Data Model
|
|
|
|
The timeline view will use existing data:
|
|
|
|
- `task.timeTracking.entries[]` — Start/end times per task
|
|
- `task.status` — Current state
|
|
- `task.agent` — Assigned agent
|
|
- `activity-log.json` — Status change timestamps
|
|
|
|
New fields (optional):
|
|
|
|
- `task.parallelismGroup` — Group related parallel tasks
|
|
- `task.dependsOn[]` — Explicit dependencies for visualization
|
|
|
|
### API Endpoints
|
|
|
|
```typescript
|
|
// Timeline data for a date range
|
|
GET /api/analytics/timeline
|
|
Query: { from: ISO, to: ISO, agent?: string, project?: string }
|
|
Response: {
|
|
tasks: [{
|
|
id: string,
|
|
title: string,
|
|
agent: string,
|
|
segments: [{ start: ISO, end: ISO, status: string }]
|
|
}],
|
|
metrics: {
|
|
parallelismFactor: number,
|
|
throughput: number,
|
|
avgLeadTime: number
|
|
}
|
|
}
|
|
|
|
// Aggregate metrics for a sprint
|
|
GET /api/analytics/metrics
|
|
Query: { sprint?: string, from?: ISO, to?: ISO }
|
|
Response: {
|
|
tasksCompleted: number,
|
|
avgDuration: number,
|
|
parallelismPeak: number,
|
|
agentUtilization: Record<string, number>
|
|
}
|
|
```
|
|
|
|
### UI Components
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ [Kanban] [Timeline] [Dashboard] 🔍 Filter 📅 │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ 2026-02-05 8:00 9:00 10:00 11:00 │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ veritas │███████████████████████│ │
|
|
│ │ REL-001 │ │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ codex-1 │ │█████│ │
|
|
│ │ │REL-2│ │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ codex-2 │ │████████│ │
|
|
│ │ │ REL-3 │ │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ codex-3 │ │██████████████│ │
|
|
│ │ │ REL-4 │ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Components needed:**
|
|
|
|
1. `TimelinePage.tsx` — New page at `/timeline`
|
|
2. `TimelineChart.tsx` — Gantt-style visualization (use @nivo/gantt or custom)
|
|
3. `TimelineFilters.tsx` — Date range, agent, project filters
|
|
4. `ParallelismMetrics.tsx` — Key metrics cards
|
|
|
|
### Implementation Phases
|
|
|
|
**Phase 1: Data Layer (2-3 hours)**
|
|
|
|
- [ ] Add timeline API endpoint
|
|
- [ ] Aggregate time tracking data into segments
|
|
- [ ] Calculate parallelism metrics
|
|
|
|
**Phase 2: Basic UI (4-6 hours)**
|
|
|
|
- [ ] Create TimelinePage with navigation
|
|
- [ ] Implement basic Gantt chart (horizontal bars)
|
|
- [ ] Add date range picker
|
|
|
|
**Phase 3: Polish (2-4 hours)**
|
|
|
|
- [ ] Add swimlanes per agent
|
|
- [ ] Color-code by task type/status
|
|
- [ ] Zoom levels (hour/day/week)
|
|
- [ ] Hover tooltips with task details
|
|
|
|
**Phase 4: Integration (2 hours)**
|
|
|
|
- [ ] Link from task cards to timeline position
|
|
- [ ] Add to dashboard as widget option
|
|
|
|
## Technical Decisions
|
|
|
|
**Chart Library Options:**
|
|
|
|
1. `@nivo/gantt` — React-native, good for static Gantt charts
|
|
2. `react-gantt-schedule-timeline-calendar` — Feature-rich but heavy
|
|
3. Custom with D3 — Maximum flexibility, more work
|
|
4. CSS Grid + custom — Simplest, good for MVP
|
|
|
|
**Recommendation:** Start with CSS Grid + custom for MVP, migrate to @nivo if needed.
|
|
|
|
## Dependencies
|
|
|
|
- Existing time tracking data must be populated
|
|
- Status history service provides state change timestamps
|
|
|
|
## Risks
|
|
|
|
1. **Data gaps** — Tasks without time tracking won't appear
|
|
2. **Performance** — Large date ranges with many tasks may be slow
|
|
3. **Complexity** — Full Gantt features (drag, resize, dependencies) add significant scope
|
|
|
|
## Success Metrics
|
|
|
|
- Users can identify which tasks ran in parallel
|
|
- Average parallelism factor is visible
|
|
- Sprint retrospectives use the timeline view
|