Skip to main content

Activity Dashboard 2.0 - Design Update

Date: November 27, 2025 Version: 2.0 Status: Final Design Package Meeting: Will-Hal Design Review

Table of Contents​

  1. Executive Summary
  2. Key Design Insights from Meeting
  3. Design Philosophy
  4. Documentation Package
  5. Implementation Roadmap

Executive Summary​

The Activity Dashboard 2.0 represents a fundamental shift from machinery metrics to journey navigation. Based on stakeholder analysis from the November 27, 2025 design review meeting with Will and Hal, this update transforms the dashboard from showing "how the engine works" to "where we're going and what's in the way."

Core Transformation​

From Engine Diagnostics:

  • Message counts, session durations, token usage
  • "How is it doing it?"
  • Machinery-focused interface

To GPS Navigation:

  • Task progress, blocked features, route to completion
  • "What has it made?"
  • Journey-focused interface

Critical Quote from Stakeholder​

"The gold isn't in how is it doing it... the real stuff is features, deliverables, targets reached. What you want is: How do I get from A to B? What are my obstacles? And what's my route?" — Will, Design Review Meeting, November 27, 2025

Key Design Insights​

1. The Navigation Metaphor​

The dashboard should function like a car's GPS navigation system, not its engine diagnostics panel.

GPS Dashboard Elements:

  • Where am I? → Current task progress
  • Where going? → Project milestones
  • What route? → Task → Commit → Done
  • What obstacles? → Blocked tasks only

Not Shown (Engine Metrics):

  • RPM, fuel injection rate, engine temperature
  • Similarly: Message counts, session duration, token usage

2. Exception-Based Display​

"If it's 40, 40, 40, 40, 40 every time, don't show it."

Rule: Only show deviations from baseline. Hide uniform data.

MetricBaselineDisplay Rule
QA Score40 (passing)Show only if ≠ 40
Task StatusNormal flowShow only if blocked
Build StatusSuccessShow only if failed

3. Task-Centric Architecture​

Everything flows toward tasks as the primary entity:

TASK (Primary)
├── ☑ Checkbox (source of truth for completion)
├── Status (pending/in_progress/blocked/done)
├── Linked Sessions (evidence)
└── Linked Commits (evidence)

Sessions and commits are supporting evidence, not primary metrics.

4. Three-Level Information Hierarchy​

LEVEL 1: Primary View (Non-scrolling - "actual information on a non-scrolling screen")
├── Portfolio summary (all projects)
├── Task Kanban (selected project)
├── 5 activity highlights
├── Blocked tasks panel
└── Work distribution chart

LEVEL 2: Drill-Down (On-demand)
├── Full task list with details
├── Commit timeline
├── Session summaries
└── Progress burndown

LEVEL 3: Deep Inspection (Hidden - "we can have it in the details")
├── Session message history
├── Commit diffs
├── Task change history
└── Raw activity logs

5. The 5-Second Test​

Users must answer these questions in < 5 seconds without scrolling:

  1. Which project needs attention?
  2. What tasks are in progress?
  3. What is blocking progress?
  4. What completed recently?
  5. Am I on track?

Design Philosophy​

GPS Not Engine: What to Remove vs Keep​

Remove from Primary View​

Engine MetricWhy Remove
Message counts"Nobody cares" - no actionable signal
Session durationShows process, not progress
Token usageEngine internals
Word countsMachinery metric
Uniform QA scoresRepeating data = no information
Version numbersUnless different from expected

Keep in Primary View​

Navigation ElementWhy Keep
Task checkboxesSource of truth for completion
Project progress barsHigh-level position indicator
Blocked tasks"Obstacles in the way"
Linked commitsEvidence of progress
Activity highlights (5 max)Recent journey milestones
Kanban board"Has value because you can see features moving from left to right"

Sessions as Journey Segments​

"Sessions are segments of the journey... we need to connect them into the map."

Sessions are not primary information. They are:

  • Context for understanding what was worked on
  • Evidence linking to tasks
  • Memory for continuity

Display Rule: Show session count as badge/metadata on tasks. Full session details available on drill-down only.

Assumptive Baseline Principle​

Principle: Uniform data provides no signal.

Implementation:

  • Detect repeating values
  • Hide anything that's consistently the same
  • Only highlight/show deviations
  • Mark anomalies prominently

Documentation Package​

This design update includes the following comprehensive documents:

Core Design Documents​

  1. Software Design Document (SDD)

    • System architecture
    • Data model & ERD
    • API specifications
    • Component design

  2. Technical Design Document (TDD)

    • Task linking algorithms (Commit→Task, Session→Task)
    • Progress calculation logic
    • Activity feed prioritization
    • Real-time update mechanisms
    • Frontend implementation details

  3. Architecture Decision Records (ADRs)

    • ADR-001: Task-Centric Architecture
    • ADR-002: Checkbox as Source of Truth
    • ADR-003: Exception-Based Display
    • ADR-004: Session-to-Task Linking
    • ADR-005: Real-Time Updates (WebSocket)
    • ADR-006: Three-Level Hierarchy
    • ADR-007: Activity Feed Prioritization
    • ADR-008: Multi-Project Portfolio

  4. UI Component Specifications

    • ProjectSummaryBar
    • KanbanBoard
    • TaskCard
    • ActivityFeed
    • BlockerPanel
    • WorkDistributionChart
    • ProjectSelector
    • Unified Dashboard Layout

  5. Meeting Transcript

    • Full Will-Hal design review (November 27, 2025)
    • Key stakeholder quotes
    • Design decisions and rationale

Multi-Project Dashboard Design​

Complete integrated design package combining:

  • Software architecture
  • Technical implementation
  • UI specifications
  • Component prompts

Implementation Roadmap​

Phase 1: Foundation (Week 1-2)​

Priority: P0 - Critical Path

  • Multi-project data model

    • Projects, ProjectPlans, TaskLists, Tasks
    • TASK.checked as source of truth
    • Status enum: pending/in_progress/review/blocked/done

  • Task Kanban Board

    • 4 columns: Pending | In Progress | Review | Done
    • Blocked tasks highlighted within In Progress
    • Task cards with checkbox, title, complexity badge

  • Blocked Task Detection

    • Filter status='blocked'
    • Days blocked calculation
    • Blocker panel UI (orange/amber styling)

  • Progress Calculation

    progress_pct = (COUNT(checked=true) / COUNT(*)) × 100

Phase 2: Linking (Week 3-4)​

Priority: P1 - High Value

  • Commit→Task Linking

    • Explicit references (#TASK-123 in commit message)
    • Title similarity matching (threshold: 0.7)
    • File path overlap analysis
    • Confidence scoring

  • Session→Task Linking

    • Keyword extraction (NLP)
    • Entity recognition (file paths, identifiers)
    • Match score calculation
    • Top 5 matches with confidence

  • Link Management

    • Confidence indicators in UI
    • User confirm/reject interface
    • Link evidence display

Phase 3: Dashboard Assembly (Week 5-6)​

Priority: P1 - Core Experience

  • Project Summary Bar

    • All projects with progress bars
    • Task counts (N/M completed)
    • Commit counts (last 7 days)
    • Blocker indicators (red dot)

  • Activity Feed (5 items max)

    • Weighted prioritization algorithm
    • Task completed: weight 100
    • Task blocked: weight 90
    • Commit: weight 50
    • Session: weight 30

  • Work Distribution Chart

    weighted_score = commits×3 + sessions×1 + tasks×5
    percentage = project_score / total_score × 100

Phase 4: Real-Time Updates (Week 7)​

Priority: P2 - Enhanced Experience

  • WebSocket Infrastructure

    • Connection management
    • Project subscription model
    • Event broadcasting

  • Event Types

    • task.updated, task.completed, task.blocked
    • progress.changed
    • commit.new, session.ended

  • Optimistic Updates

    • Immediate UI response
    • Rollback on failure
    • Conflict resolution

Phase 5: Polish & Optimization (Week 8)​

Priority: P3 - Production Ready

  • Caching Strategy

    • Portfolio summary: 60s TTL
    • Kanban board: 30s TTL
    • Activity feed: 60s TTL
    • Work distribution: 300s TTL

  • Performance

    • Query optimization
    • Materialized views
    • Batch loading

  • Responsive Design

    • Mobile: Single column, horizontal Kanban scroll
    • Tablet: 2-column layout
    • Desktop: Full layout, non-scrolling

  • Accessibility

    • ARIA labels
    • Keyboard navigation
    • Focus management
    • Screen reader support

Data Model​

Core Entities​

CREATE TABLE projects (
    id UUID PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    status VARCHAR(50) DEFAULT 'active'
);

CREATE TABLE task_lists (
    id UUID PRIMARY KEY,
    plan_id UUID REFERENCES project_plans(id),
    name VARCHAR(255) NOT NULL,
    category VARCHAR(100)
);

CREATE TABLE tasks (
    id UUID PRIMARY KEY,
    list_id UUID REFERENCES task_lists(id),
    title VARCHAR(500) NOT NULL,
    checked BOOLEAN DEFAULT FALSE,  -- SOURCE OF TRUTH
    status VARCHAR(50) DEFAULT 'pending',
    complexity VARCHAR(10),
    blocked_reason TEXT
);

CREATE TABLE llm_sessions (
    id UUID PRIMARY KEY,
    project_id UUID REFERENCES projects(id),
    started_at TIMESTAMP,
    ended_at TIMESTAMP,
    message_count INTEGER,
    summary TEXT
);

CREATE TABLE git_commits (
    sha VARCHAR(40) PRIMARY KEY,
    repo_id UUID REFERENCES git_repos(id),
    message TEXT NOT NULL,
    author VARCHAR(255),
    timestamp TIMESTAMP,
    additions INTEGER,
    deletions INTEGER
);

CREATE TABLE task_commit_links (
    task_id UUID REFERENCES tasks(id),
    commit_sha VARCHAR(40) REFERENCES git_commits(sha),
    confidence DECIMAL(3,2),
    link_type VARCHAR(20),  -- 'explicit' | 'inferred'
    evidence TEXT
);

CREATE TABLE task_session_links (
    task_id UUID REFERENCES tasks(id),
    session_id UUID REFERENCES llm_sessions(id),
    confidence DECIMAL(3,2),
    link_type VARCHAR(20),
    evidence TEXT
);

API Design​

REST Endpoints​

GET  /api/v1/dashboard
     → DashboardResponse (portfolio + kanban + activity + blockers)

GET  /api/v1/dashboard/portfolio
     → ProjectSummary[] (all projects with progress)

GET  /api/v1/dashboard/activity?limit=5
     → ActivityHighlight[] (top 5 prioritized events)

GET  /api/v1/projects/{id}/kanban
     → KanbanBoard (tasks by status columns)

PATCH /api/v1/tasks/{id}
      → Task (update checked/status)

WebSocket Events​

// Server → Client
{
  "type": "task.completed",
  "project_id": "proj-1",
  "task_id": "t-123",
  "changes": { "checked": true, "status": "done" }
}

{
  "type": "progress.changed",
  "project_id": "proj-1",
  "progress_pct": 67.5,
  "tasks_completed": 27,
  "tasks_total": 40
}

// Client → Server
{
  "type": "subscribe",
  "project_ids": ["proj-1", "proj-2", "proj-3"]
}

UI Layout Specification​

┌─────────────────────────────────────────────────────────────────────┐
│  CODITECT                      [All Projects ▼]    [⚙ Settings]     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─ PROJECT SUMMARY BAR ──────────────────────────────────────┐   │
│  │  Auth System     ████████████░░░░░░ 58%  7/12  3 commits   │   │
│  │  Payment Gateway ████████░░░░░░░░░░ 40%  4/10  1 commit    │   │
│  │  User Dashboard  ██████████████░░░░ 70% 14/20  5 commits   │   │
│  └────────────────────────────────────────────────────────────┘   │
│                                                                     │
│  ┌─ TASK JOURNEY ───────────────────────────────────────────────┐ │
│  │  PENDING   IN PROGRESS    REVIEW        DONE                │ │
│  │  ┌──────┐  ┌──────────┐  ┌────────┐  ┌───────────┐         │ │
│  │  │☐Rate │  │☐Refresh  │  │        │  │☑JWT      │         │ │
│  │  │ Limit│  │ Token    │  │ Empty  │  │☑Auth     │         │ │
│  │  └──────┘  │ 60%████  │  │        │  │☑Login    │         │ │
│  │            │⚠Blocked  │  └────────┘  └───────────┘         │ │
│  │            └──────────┘                                     │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌─ RECENT ACTIVITY ─────┐  ┌─ ATTENTION REQUIRED ──────────┐    │
│  │  ✓ JWT complete   2h  │  │  ⚠️ MFA Setup                 │    │
│  │    3 commits, 2 sess  │  │     Blocked: API spec         │    │
│  │  ⎇ abc123: +45/-12 3h │  │     Blocked for: 3 days       │    │
│  │  ✓ Login merged   5h  │  │     [View] [Resolve]          │    │
│  │  💬 Rate limit    6h  │  │                               │    │
│  │  ⚠️ MFA blocked   8h  │  │  No other blockers            │    │
│  └───────────────────────┘  └───────────────────────────────┘    │
│                                                                     │
│  ┌─ WORK DISTRIBUTION (This Week) ──────────────────────────────┐ │
│  │  Auth System     ████████████████████████░░░░░░░░ 45%        │ │
│  │  Payment Gateway █████████████░░░░░░░░░░░░░░░░░░ 25%        │ │
│  │  User Dashboard  ████████░░░░░░░░░░░░░░░░░░░░░░░ 20%        │ │
│  │  Documentation   ████░░░░░░░░░░░░░░░░░░░░░░░░░░░ 10%        │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Key Success Metrics​

The 5-Second Test Results​

✅ Question 1: Which project needs attention? → Answer: Auth System (58%, has blocker) → Source: Project Summary Bar, red dot indicator

✅ Question 2: What tasks are in progress? → Answer: Refresh Token Logic (60% complete), MFA Setup (blocked) → Source: Kanban Board, In Progress column

✅ Question 3: What is blocking progress? → Answer: MFA Setup, blocked for 3 days, awaiting API spec → Source: Blocker Panel (orange highlighted)

✅ Question 4: What completed recently? → Answer: JWT tokens (2h ago), Login form merged (5h ago) → Source: Activity Feed, top 2 items

✅ Question 5: Am I on track? → Answer: Auth System 58% (7/12 tasks), trending positive → Source: Project Summary Bar, progress visualization

Result: All questions answerable in < 5 seconds without scrolling.

Migration from 1.0 to 2.0​

Data Transformation Required​

  1. Session Data

    • Extract session summaries for activity feed
    • Link sessions to tasks via NLP
    • Hide message-level details from primary view

  2. Task Data

    • Ensure all tasks have checked boolean
    • Migrate status to new enum
    • Identify blocked tasks and reasons

  3. Commit Data

    • Parse commit messages for task references
    • Calculate file overlap with tasks
    • Generate link confidence scores

UI Migration​

  1. Remove from Primary View

    • Message count displays
    • Session duration metrics
    • Token usage charts
    • Verbose AI summaries

  2. Add to Primary View

    • Project summary bar
    • Kanban board (if not present)
    • Blocker panel
    • Work distribution chart

  3. Reorganize

    • Session details → Level 3 (deep inspection)
    • Commit timeline → Level 2 (drill-down)
    • Task history → Level 2 (drill-down)

Appendix: Key Stakeholder Quotes​

"The gold isn't in how is it doing it... the real stuff is features, deliverables, targets reached."

"What you want is: How do I get from A to B? What are my obstacles? And what's my route?"

"If it's 40, 40, 40, 40, 40 every time, don't show it."

"5 things that happened and a simple definition of these things."

"Sessions are segments of the journey... we need to connect them into the map."

"The thing you don't want to see [is] the neurons firing. We want to see what we're thinking about."

"A Kanban board has value because you can see features moving from left to right."

"Actual information on a non-scrolling screen."

"You see the map and your route and any obstacles in the way. Even gas and charge are secondary."

"As cars have gotten better, you focus less on the car. You're no longer looking at gauges... you're just looking at the map."

Document History​

VersionDateAuthorChanges
2.02025-11-27Design TeamComplete design package based on Will-Hal meeting analysis
1.02025-11-26Design TeamInitial dashboard specification

References:

  • SDD-Activity-Dashboard.md
  • TDD-Activity-Dashboard.md
  • ADRs-Activity-Dashboard.md
  • UI-Prompts-Activity-Dashboard.md
  • MULTI-PROJECT-DASHBOARD-DESIGN.md
  • Meeting Transcript: cuu-ewbn-jrj-2025-11-27T1040-WILL-HAL.txt

This document represents the authoritative 2.0 design update for the Coditect Activity Dashboard, incorporating stakeholder feedback from the November 27, 2025 design review meeting.