Activity Dashboard Design Specification

------------------------------ Point A , Point B Route + Obstacles Speed Aggregated + Gas/Charge count Engine RPM HIDE - count Field Calculation...

Activity Dashboard Design Specification

Coditect Platform | UX Architecture Document
Version: 2.0
Date: November 27, 2025
Status: Design Phase

---

Executive Summary

This document captures the design principles and specifications for the Coditect Activity Dashboard, derived from stakeholder analysis. The core insight: users need to see the journey, not the engine.

Current implementation shows "how the machinery works" (conversations, messages, sessions). Users need "what has it made" (features, deliverables, milestones).

---

Data Sources Overview

The Activity Dashboard synthesizes data from four primary sources:

---

Data Model

Entity Relationship Diagram

Task Status State Machine

---

The Navigation Metaphor

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

Translation Matrix

Navigation Concept	Dashboard Equivalent	Data Source
Point A	Project start / Sprint baseline	PROJECT.created_at, TASK_LIST
Point B	Target tasks checked off	TASK.checked = true
Route	Task progression with commits	TASK.status + GIT_COMMIT
Obstacles	Blocked tasks	TASK.status = 'blocked'
Speed	Tasks completed / time period	Aggregated TASK + GIT_COMMIT
Gas/Charge	Session counts (secondary)	LLM_SESSION count
Engine RPM	Message counts	HIDE - MESSAGE count

---

Multi-Project Architecture

Portfolio View Structure

Project Drill-Down Hierarchy

---

Information Architecture

---

Core Design Principles

Principle 1: Task-Centric, Not Session-Centric

Principle 2: Checkbox as Source of Truth

Principle 3: Link Sessions & Commits to Tasks

Principle 4: Assumptive Baseline - Exception-Only Display

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

---

UI Layout Specification

Primary Dashboard View

┌─────────────────────────────────────────────────────────────────────────────┐
│  CODITECT                                    [All Projects ▼]  [⚙ Settings] │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─ PROJECT SUMMARY ───────────────────────────────────────────────────┐   │
│  │  Auth System     ████████████░░░░░░░░  58% (7/12 tasks)    3 commits │   │
│  │  Payment Gateway ████████░░░░░░░░░░░░  40% (4/10 tasks)    1 commit  │   │
│  │  User Dashboard  ██████████████░░░░░░  70% (14/20 tasks)   5 commits │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌─ TASK JOURNEY (Auth System) ────────────────────────────────────────┐   │
│  │                                                                      │   │
│  │   PENDING         IN PROGRESS       REVIEW          DONE            │   │
│  │  ┌───────────┐   ┌─────────────┐   ┌─────────┐   ┌─────────────┐   │   │
│  │  │ Rate      │   │ Refresh     │   │         │   │ ☑ JWT       │   │   │
│  │  │ Limiting  │ → │ Token Logic │   │         │   │   Tokens    │   │   │
│  │  │           │   │ ████░░ 60%  │   │         │   ├─────────────┤   │   │
│  │  └───────────┘   └─────────────┘   └─────────┘   │ ☑ Auth      │   │   │
│  │                  ┌─────────────┐                 │   Schema    │   │   │
│  │                  │ MFA Setup   │                 ├─────────────┤   │   │
│  │                  │ ⚠️ BLOCKED  │                 │ ☑ Login     │   │   │
│  │                  └─────────────┘                 │   Form      │   │   │
│  │                                                  └─────────────┘   │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  ┌─ RECENT ACTIVITY ───────────────┐  ┌─ ATTENTION REQUIRED ────────────┐  │
│  │                                 │  │                                  │  │
│  │  • ☑ JWT tokens complete        │  │  ⚠️ MFA Setup                   │  │
│  │    └ 3 commits, 2 sessions      │  │     Blocked: Awaiting API spec  │  │
│  │  • Refresh token at 60%         │  │     Task List: Backend          │  │
│  │    └ abc123: Add refresh logic  │  │     Project: Auth System        │  │
│  │  • ☑ Login form merged          │  │                                  │  │
│  │    └ PR #42 approved            │  │  ─────────────────────────────   │  │
│  │  • New session: Rate limiting   │  │  1 blocked task across projects │  │
│  │                                 │  │                                  │  │
│  └─────────────────────────────────┘  └──────────────────────────────────┘  │
│                                                                             │
│  ┌─ WORK DISTRIBUTION (This Week) ──────────────────────────────────────┐  │
│  │                                                                       │  │
│  │   Auth System       ████████████████████████░░░░░░░░░░  45% │ 12 commits│
│  │   Payment Gateway   ██████████░░░░░░░░░░░░░░░░░░░░░░░░  25% │  4 commits│
│  │   User Dashboard    ████████░░░░░░░░░░░░░░░░░░░░░░░░░░  20% │  6 commits│
│  │   Documentation     ████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  10% │  2 commits│
│  │                                                                       │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

---

Data Transformation Architecture

Complete Data Pipeline

Session-to-Task Matching

Commit-to-Task Matching

Progress Calculation

---

Component Specifications

1. Project Summary Bar

Data Requirements:

Field	Source	Calculation
progress_pct	TASK.checked	COUNT(checked=true) / COUNT(*)
task_summary	TASK	"N/M tasks"
commit_count	GIT_COMMIT	COUNT(last 7 days)
has_blockers	TASK.status	EXISTS(status='blocked')

2. Task Kanban Board

Data Requirements:

Column	Filter	Sort
PENDING	status='pending' AND checked=false	order ASC
IN PROGRESS	status='in_progress'	updated_at DESC
REVIEW	status='review'	updated_at DESC
DONE	checked=true	updated_at DESC
BLOCKED	status='blocked'	created_at ASC

3. Recent Activity Feed

Activity Prioritization:

Priority	Event Type	Display Format
1	Task completed (checked)	"☑ {task.title} complete"
2	Task blocked	"⚠️ {task.title} blocked"
3	Commit merged	"{sha}: {message}"
4	Session with task context	"Session: {inferred_topic}"
5	Status change	"{task.title} → {status}"

4. Blocker Panel

Query:

SELECT 
    t.id,
    t.title,
    t.description AS blocked_reason,
    p.name AS project_name,
    tl.name AS task_list_name,
    DATEDIFF(NOW(), t.updated_at) AS days_blocked
FROM tasks t
JOIN task_lists tl ON t.list_id = tl.id
JOIN project_plans pp ON tl.plan_id = pp.id
JOIN projects p ON pp.project_id = p.id
WHERE t.status = 'blocked'
ORDER BY t.updated_at ASC

5. Work Distribution Chart

Data Aggregation:

---

Technical Specifications

TypeScript Interfaces

// ============================================
// CORE ENTITIES
// ============================================

interface Project {
  id: string;
  name: string;
  description?: string;
  status: 'active' | 'archived' | 'paused';
  created_at: Date;
  updated_at: Date;
  
  // Relations
  git_repos: GitRepo[];
  project_plan: ProjectPlan;
  sessions: LLMSession[];
}

interface GitRepo {
  id: string;
  project_id: string;
  url: string;
  default_branch: string;
  current_commit: string;
  
  // Derived
  recent_commits: GitCommit[];
}

interface GitCommit {
  sha: string;
  repo_id: string;
  author: string;
  message: string;
  timestamp: Date;
  additions: number;
  deletions: number;
  files_changed: string[];
  
  // Linked
  linked_tasks: TaskLink[];
}

interface ProjectPlan {
  id: string;
  project_id: string;
  name: string;
  description?: string;
  target_date?: Date;
  
  // Relations
  task_lists: TaskList[];
}

interface TaskList {
  id: string;
  plan_id: string;
  name: string;
  order: number;
  category?: string;  // e.g., 'backend', 'frontend', 'testing'
  
  // Relations
  tasks: Task[];
  
  // Derived
  progress: number;  // 0-100
  total_tasks: number;
  completed_tasks: number;
}

interface Task {
  id: string;
  list_id: string;
  title: string;
  description?: string;
  checked: boolean;  // ☑ or ☐
  status: TaskStatus;
  complexity?: 'S' | 'M' | 'L' | 'XL';
  due_date?: Date;
  created_at: Date;
  updated_at: Date;
  
  // Linked evidence
  linked_sessions: SessionLink[];
  linked_commits: CommitLink[];
}

type TaskStatus = 
  | 'pending'      // Not started
  | 'in_progress'  // Being worked on
  | 'review'       // Awaiting review
  | 'blocked'      // Has obstacle
  | 'done';        // Completed (checked=true)

interface LLMSession {
  id: string;
  project_id: string;
  started_at: Date;
  ended_at?: Date;
  message_count: number;
  summary?: string;  // AI-generated, concise
  
  // Links
  linked_tasks: TaskLink[];
  
  // Hidden from primary view
  messages: Message[];
}

// ============================================
// LINKING TYPES
// ============================================

interface TaskLink {
  task_id: string;
  confidence: number;  // 0-1
  link_type: 'explicit' | 'inferred';
  evidence?: string;   // Why linked
}

interface SessionLink extends TaskLink {
  session_id: string;
}

interface CommitLink extends TaskLink {
  commit_sha: string;
}

// ============================================
// DASHBOARD TYPES
// ============================================

interface ProjectSummary {
  project: Project;
  progress_pct: number;
  tasks_completed: number;
  tasks_total: number;
  commits_this_week: number;
  sessions_this_week: number;
  blocked_count: number;
  has_blockers: boolean;
}

interface ActivityHighlight {
  id: string;
  type: 'task_completed' | 'commit' | 'session' | 'status_change' | 'blocked';
  title: string;          // Max 50 chars
  subtitle?: string;      // Max 30 chars
  project_id: string;
  task_id?: string;
  timestamp: Date;
  icon: 'check' | 'git' | 'chat' | 'alert';
}

interface BlockedTask {
  task: Task;
  project_name: string;
  task_list_name: string;
  blocked_reason?: string;
  days_blocked: number;
}

interface WorkDistribution {
  project_id: string;
  project_name: string;
  percentage: number;
  commit_count: number;
  session_count: number;
  tasks_completed: number;
  weighted_score: number;
}

// ============================================
// API RESPONSE TYPES
// ============================================

interface DashboardResponse {
  portfolio_summary: ProjectSummary[];
  selected_project?: {
    project: Project;
    kanban: KanbanBoard;
  };
  recent_activity: ActivityHighlight[];  // Max 5
  blocked_tasks: BlockedTask[];
  work_distribution: WorkDistribution[];
  last_updated: Date;
}

interface KanbanBoard {
  columns: KanbanColumn[];
}

interface KanbanColumn {
  status: TaskStatus;
  label: string;
  tasks: Task[];
  count: number;
}

Data Flow Diagram

---

What to Remove vs Keep

Content Classification

Detailed Classification

Category	Items	Rationale
✅ KEEP	Task checkboxes, status	Source of truth for progress
✅ KEEP	Project progress bars	High-level navigation
✅ KEEP	Blocked tasks	Exception-only display
✅ KEEP	Recent commits (linked)	Evidence of progress
✅ KEEP	5 activity highlights	Concise summary
⬇️ DRILL-DOWN	Session message history	Neuron-level detail
⬇️ DRILL-DOWN	Commit diffs	Code-level detail
⬇️ DRILL-DOWN	Full task history	Audit trail
⬇️ DRILL-DOWN	Token usage metrics	Engine diagnostics
❌ REMOVE	Message counts	No signal
❌ REMOVE	Word counts	No signal
❌ REMOVE	Uniform QA scores	Only show exceptions
❌ REMOVE	Session duration	Engine metric

---

Implementation Priorities

Priority Matrix

Priority	Component	Data Source	Effort
P0	Multi-Project Data Model	All sources	M
P0	Task Kanban Board	TASK, TASK_LIST	M
P0	Checkbox-Based Progress	TASK.checked	S
P0	Blocked Task Panel	TASK.status='blocked'	S
P1	Project Summary Bar	Aggregated PROJECT	M
P1	Activity Feed (5 items)	TASK, GIT_COMMIT, SESSION	M
P1	Session→Task Linking	LLM_SESSION + TASK	L
P1	Commit→Task Linking	GIT_COMMIT + TASK	M
P2	Work Distribution	Aggregated by project	M
P2	Commit Timeline	GIT_COMMIT by time	S
P3	Drill-Down Views	All sources	L

---

Success Criteria

The 5-Second Test

The dashboard succeeds when a user can answer these questions in < 5 seconds without scrolling:

Failure Indicators

The dashboard fails if it requires the user to:

• Scroll to see any project's progress
• Count messages to understand progress
• Mentally map sessions to tasks
• See tasks without clear status
• Read verbose AI summaries
• Navigate away to find blockers

---

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."

---

Document History

Version	Date	Author	Changes
1.0	2025-11-27	Design Team	Initial specification
2.0	2025-11-27	Design Team	Added multi-project data model, task lists with checkboxes, git commit linking, session-to-task mapping, complete TypeScript interfaces

---

This document defines the UX architecture for the Coditect Activity Dashboard, emphasizing task-centric views with checkbox-based progress tracking, multi-project portfolio management, and evidence linking from LLM sessions and git commits.