Software Design Document (SDD)
Coditect Activity Dashboard
Document Version: 1.0
Date: November 27, 2025
Status: Draft
Author: Architecture Team
1. Introduction
1.1 Purpose
This Software Design Document (SDD) describes the architectural design, component specifications, and implementation details for the Coditect Activity Dashboard. The dashboard provides a unified view of development progress across multiple projects by synthesizing data from LLM sessions, Git commits, project plans, and task lists.
1.2 Scope
This document covers:
- System architecture and component design
- Data models and relationships
- API specifications
- Integration patterns
- Security considerations
1.3 Definitions and Acronyms
| Term | Definition |
|---|---|
| LLM | Large Language Model |
| ADR | Architecture Decision Record |
| DTO | Data Transfer Object |
| DI | Dependency Injection |
| ERD | Entity Relationship Diagram |
1.4 References
- Activity Dashboard Design Specification v2.0
- Coditect Platform Architecture Guide
- FoundationDB Operations Manual
2. System Overview
2.1 System Context
┌─────────────────────────────────────────────────────────────────────────┐
│ CODITECT PLATFORM │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Git Provider│ │ LLM Service │ │ Task Store │ │
│ │ (GitHub) │ │ (Claude) │ │ (Internal) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ DATA INTEGRATION LAYER │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Commit │ │ Session │ │ Task │ │ Project │ │ │
│ │ │ Ingester │ │ Ingester │ │ Sync │ │ Sync │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ LINKING SERVICE │ │
│ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │ │
│ │ │ Session→Task │ │ Commit→Task │ │ Progress │ │ │
│ │ │ Matcher │ │ Matcher │ │ Calculator │ │ │
│ │ └────────────────┘ └────────────────┘ └────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ AGGREGATION SERVICE │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Project │ │ Blocker │ │ Activity │ │ Work │ │ │
│ │ │ Progress │ │ Detector │ │ Feed │ │ Distrib │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ DASHBOARD API │ │
│ │ /api/v1/dashboard | /api/v1/projects │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ DASHBOARD UI │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Portfolio│ │ Kanban │ │ Activity │ │ Blocker │ │ │
│ │ │ Summary │ │ Board │ │ Feed │ │ Panel │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
2.2 Design Principles
- Task-Centric View: All data flows toward task progress, not session metrics
- Exception-Based Display: Only show anomalies; hide uniform data
- Progressive Disclosure: Three-level information hierarchy
- Real-Time Updates: WebSocket-based live updates
- Offline Resilience: Graceful degradation when services unavailable
3. Architectural Design
3.1 Component Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ FRONTEND LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ React Application │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │
│ │ │ DashboardPage│ │ ProjectPage │ │ TaskDetailPage │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐│ │
│ │ │ Components ││ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ ││ │
│ │ │ │ProjectSummary│ │ KanbanBoard │ │ ActivityFeed │ ││ │
│ │ │ │Bar │ │ │ │ │ ││ │
│ │ │ └──────────────┘ └──────────────┘ └──────────────────────┘ ││ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ ││ │
│ │ │ │BlockerPanel │ │WorkDistrib │ │ TaskCard │ ││ │
│ │ │ │ │ │Chart │ │ │ ││ │
│ │ │ └──────────────┘ └──────────────┘ └──────────────────────┘ ││ │
│ │ └─────────────────────────────────────────────────────────────┘│ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────────────┐│ │
│ │ │ State Management ││ │
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ ││ │
│ │ │ │DashboardStore│ │ ProjectStore │ │ WebSocketManager │ ││ │
│ │ │ └──────────────┘ └──────────────┘ └──────────────────────┘ ││ │
│ │ └─────────────────────────────────────────────────────────────┘│ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ BACKEND LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ API Gateway (FastAPI) │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │/dashboard │ │/projects │ │/tasks │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │/commits │ │/sessions │ │/ws/dashboard │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Service Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │DashboardSvc │ │ProjectSvc │ │TaskSvc │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │LinkingSvc │ │AggregationSvc│ │ActivitySvc │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Repository Layer │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────┐ │ │
│ │ │ProjectRepo │ │TaskRepo │ │SessionRepo │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────────────────┘ │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │CommitRepo │ │LinkRepo │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────┐
│ DATA LAYER │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────────────┐ │
│ │ FoundationDB │ │ Redis │ │ Git Provider API │ │
│ │ (Primary) │ │ (Cache) │ │ (GitHub/GitLab) │ │
│ └──────────────┘ └──────────────┘ └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
3.2 Data Flow
┌─────────────────────────────────────────────────────────────────────────┐
│ DATA FLOW DIAGRAM │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ External Sources │
│ ──────────────── │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 1. INGESTION │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Git Webhooks │ │Session End │ │Task Update │ │ │
│ │ │ │ │Events │ │Events │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
│ └────────────┼────────────────┼────────────────┼───────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 2. NORMALIZATION │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Parse Commit │ │Extract │ │Validate │ │ │
│ │ │Message │ │Session Meta │ │Task Schema │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
│ └────────────┼────────────────┼────────────────┼───────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 3. LINKING │ │
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
│ │ │ Task Matcher │ │ │
│ │ │ • Explicit refs: #TASK-123, closes #456 │ │ │
│ │ │ • Fuzzy match: title similarity > 0.7 │ │ │
│ │ │ • File overlap: commit files ∩ task context │ │ │
│ │ └──────────────────────────┬──────────────────────────────┘ │ │
│ └─────────────────────────────────┼────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 4. AGGREGATION │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Progress % │ │Blocked List │ │Activity │ │ │
│ │ │by Project │ │Detection │ │Ranking │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │
│ └────────────┼────────────────┼────────────────┼───────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ 5. PRESENTATION │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │Portfolio │ │Kanban │ │Activity │ │ │
│ │ │Summary │ │Board │ │Feed (5 max) │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
4. Data Design
4.1 Entity Relationship Diagram
┌─────────────────────────────────────────────────────────────────────────┐
│ ERD │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PROJECT │ 1 * │ GIT_REPO │ 1 * │ GIT_COMMIT │ │
│ ├──────────────┤─────────├──────────────┤─────────├──────────────┤ │
│ │ id │ │ id │ │ sha │ │
│ │ name │ │ project_id │ │ repo_id │ │
│ │ description │ │ url │ │ message │ │
│ │ status │ │ default_branch│ │ author │ │
│ │ created_at │ │ current_commit│ │ timestamp │ │
│ │ updated_at │ └──────────────┘ │ additions │ │
│ └──────┬───────┘ │ deletions │ │
│ │ └───────┬──────┘ │
│ │ 1 │ │
│ │ │ │
│ ▼ 1 │ │
│ ┌──────────────┐ │ │
│ │ PROJECT_PLAN │ │ │
│ ├──────────────┤ │ │
│ │ id │ │ │
│ │ project_id │ │ │
│ │ name │ │ │
│ │ target_date │ │ │
│ └──────┬───────┘ │ │
│ │ 1 │ │
│ │ │ │
│ ▼ * │ │
│ ┌──────────────┐ ┌──────────────┐ │ │
│ │ TASK_LIST │ 1 * │ TASK │◄───────────────┘ │
│ ├──────────────┤─────────├──────────────┤ (commit_links) │
│ │ id │ │ id │ │
│ │ plan_id │ │ list_id │ ┌──────────────┐ │
│ │ name │ │ title │ │ LLM_SESSION │ │
│ │ order │ │ description │◄────────├──────────────┤ │
│ │ category │ │ checked │ │ id │ │
│ └──────────────┘ │ status │ (session│ project_id │ │
│ │ complexity │ _links)│ started_at │ │
│ │ due_date │ │ ended_at │ │
│ │ created_at │ │ message_count│ │
│ │ updated_at │ │ summary │ │
│ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ TASK_LINK │ │SESSION_LINK │ │
│ ├──────────────┤ ├──────────────┤ │
│ │ id │ │ id │ │
│ │ task_id │ │ task_id │ │
│ │ commit_sha │ │ session_id │ │
│ │ confidence │ │ confidence │ │
│ │ link_type │ │ link_type │ │
│ │ evidence │ │ evidence │ │
│ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
4.2 Database Schema
-- Projects
CREATE TABLE projects (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
description TEXT,
status VARCHAR(50) DEFAULT 'active' CHECK (status IN ('active', 'archived', 'paused')),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Git Repositories
CREATE TABLE git_repos (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
url VARCHAR(500) NOT NULL,
default_branch VARCHAR(100) DEFAULT 'main',
current_commit VARCHAR(40),
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- Git Commits
CREATE TABLE git_commits (
sha VARCHAR(40) PRIMARY KEY,
repo_id UUID NOT NULL REFERENCES git_repos(id) ON DELETE CASCADE,
author VARCHAR(255) NOT NULL,
message TEXT NOT NULL,
timestamp TIMESTAMP WITH TIME ZONE NOT NULL,
additions INTEGER DEFAULT 0,
deletions INTEGER DEFAULT 0,
files_changed JSONB DEFAULT '[]'
);
-- Project Plans
CREATE TABLE project_plans (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
project_id UUID NOT NULL UNIQUE REFERENCES projects(id) ON DELETE CASCADE,
name VARCHAR(255) NOT NULL,
description TEXT,
target_date DATE
);
-- Task Lists
CREATE TABLE task_lists (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
plan_id UUID NOT NULL REFERENCES project_plans(id) ON DELETE CASCADE,
name VARCHAR(255) NOT NULL,
list_order INTEGER DEFAULT 0,
category VARCHAR(100)
);
-- Tasks
CREATE TABLE tasks (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
list_id UUID NOT NULL REFERENCES task_lists(id) ON DELETE CASCADE,
title VARCHAR(500) NOT NULL,
description TEXT,
checked BOOLEAN DEFAULT FALSE,
status VARCHAR(50) DEFAULT 'pending'
CHECK (status IN ('pending', 'in_progress', 'review', 'blocked', 'done')),
complexity VARCHAR(10) CHECK (complexity IN ('S', 'M', 'L', 'XL')),
due_date DATE,
blocked_reason TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- LLM Sessions
CREATE TABLE llm_sessions (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,
started_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
ended_at TIMESTAMP WITH TIME ZONE,
message_count INTEGER DEFAULT 0,
summary TEXT
);
-- Task-Commit Links
CREATE TABLE task_commit_links (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
commit_sha VARCHAR(40) NOT NULL REFERENCES git_commits(sha) ON DELETE CASCADE,
confidence DECIMAL(3,2) DEFAULT 1.0 CHECK (confidence BETWEEN 0 AND 1),
link_type VARCHAR(20) DEFAULT 'inferred' CHECK (link_type IN ('explicit', 'inferred')),
evidence TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(task_id, commit_sha)
);
-- Task-Session Links
CREATE TABLE task_session_links (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
session_id UUID NOT NULL REFERENCES llm_sessions(id) ON DELETE CASCADE,
confidence DECIMAL(3,2) DEFAULT 1.0 CHECK (confidence BETWEEN 0 AND 1),
link_type VARCHAR(20) DEFAULT 'inferred' CHECK (link_type IN ('explicit', 'inferred')),
evidence TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
UNIQUE(task_id, session_id)
);
-- Indexes for performance
CREATE INDEX idx_tasks_list_id ON tasks(list_id);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_checked ON tasks(checked);
CREATE INDEX idx_git_commits_repo_id ON git_commits(repo_id);
CREATE INDEX idx_git_commits_timestamp ON git_commits(timestamp DESC);
CREATE INDEX idx_llm_sessions_project_id ON llm_sessions(project_id);
CREATE INDEX idx_task_commit_links_task_id ON task_commit_links(task_id);
CREATE INDEX idx_task_session_links_task_id ON task_session_links(task_id);
5. API Design
5.1 REST API Endpoints
Dashboard Endpoints
GET /api/v1/dashboard
Returns: DashboardResponse
Query Params:
- project_id (optional): Filter to single project
- time_range: 'day' | 'week' | 'month' (default: 'week')
GET /api/v1/dashboard/portfolio
Returns: ProjectSummary[]
GET /api/v1/dashboard/activity
Returns: ActivityHighlight[]
Query Params:
- limit: number (default: 5, max: 20)
- project_id (optional)
GET /api/v1/dashboard/blockers
Returns: BlockedTask[]
Query Params:
- project_id (optional)
Project Endpoints
GET /api/v1/projects
Returns: Project[]
GET /api/v1/projects/{id}
Returns: Project with related entities
GET /api/v1/projects/{id}/kanban
Returns: KanbanBoard
GET /api/v1/projects/{id}/progress
Returns: ProgressMetrics
Task Endpoints
GET /api/v1/tasks/{id}
Returns: Task with linked sessions and commits
PATCH /api/v1/tasks/{id}
Body: { checked?, status?, title?, description? }
Returns: Task
GET /api/v1/tasks/{id}/evidence
Returns: { sessions: SessionLink[], commits: CommitLink[] }
5.2 WebSocket Events
Connection: ws://api/v1/ws/dashboard
Events (Server → Client):
- task.updated: { task_id, changes }
- task.completed: { task_id, project_id }
- task.blocked: { task_id, reason }
- commit.new: { commit, linked_tasks }
- session.ended: { session_id, linked_tasks }
- progress.changed: { project_id, new_progress }
Events (Client → Server):
- subscribe: { project_ids: string[] }
- unsubscribe: { project_ids: string[] }
5.3 Response DTOs
interface DashboardResponse {
portfolio_summary: ProjectSummary[];
selected_project?: {
project: Project;
kanban: KanbanBoard;
};
recent_activity: ActivityHighlight[];
blocked_tasks: BlockedTask[];
work_distribution: WorkDistribution[];
last_updated: string; // ISO timestamp
}
interface ProjectSummary {
project_id: string;
project_name: string;
progress_pct: number;
tasks_completed: number;
tasks_total: number;
commits_this_period: number;
sessions_this_period: number;
blocked_count: number;
has_blockers: boolean;
}
interface KanbanBoard {
columns: KanbanColumn[];
}
interface KanbanColumn {
status: TaskStatus;
label: string;
tasks: TaskCard[];
count: number;
}
interface TaskCard {
id: string;
title: string;
checked: boolean;
status: TaskStatus;
complexity?: string;
linked_commits_count: number;
linked_sessions_count: number;
days_in_status: number;
}
interface ActivityHighlight {
id: string;
type: 'task_completed' | 'commit' | 'session' | 'status_change' | 'blocked';
title: string;
subtitle?: string;
project_id: string;
project_name: string;
task_id?: string;
timestamp: string;
icon: 'check' | 'git' | 'chat' | 'alert';
}
interface BlockedTask {
task_id: string;
task_title: string;
project_id: string;
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;
}
6. Component Design
6.1 Frontend Components
| Component | Purpose | Props | State |
|---|---|---|---|
DashboardPage | Main container | - | selectedProject, timeRange |
ProjectSummaryBar | Portfolio overview | projects: ProjectSummary[] | - |
KanbanBoard | Task visualization | kanban: KanbanBoard | dragState |
TaskCard | Individual task | task: TaskCard | expanded |
ActivityFeed | Recent highlights | activities: ActivityHighlight[] | - |
BlockerPanel | Exception display | blockers: BlockedTask[] | - |
WorkDistributionChart | Effort breakdown | distribution: WorkDistribution[] | - |
6.2 Service Classes
class DashboardService:
"""Aggregates data for dashboard display"""
async def get_dashboard(
self,
project_id: Optional[str] = None,
time_range: str = 'week'
) -> DashboardResponse:
"""Get complete dashboard data"""
async def get_portfolio_summary(self) -> List[ProjectSummary]:
"""Get all projects with progress metrics"""
async def get_activity_feed(
self,
limit: int = 5,
project_id: Optional[str] = None
) -> List[ActivityHighlight]:
"""Get prioritized activity highlights"""
class LinkingService:
"""Links sessions and commits to tasks"""
async def link_commit_to_tasks(
self,
commit: GitCommit
) -> List[TaskLink]:
"""Find and create task links for a commit"""
async def link_session_to_tasks(
self,
session: LLMSession
) -> List[TaskLink]:
"""Find and create task links for a session"""
def calculate_link_confidence(
self,
source_text: str,
task: Task
) -> float:
"""Calculate confidence score for a potential link"""
class ProgressService:
"""Calculates progress metrics"""
async def calculate_project_progress(
self,
project_id: str
) -> ProgressMetrics:
"""Calculate progress from checkbox state"""
async def detect_blocked_tasks(
self,
project_id: Optional[str] = None
) -> List[BlockedTask]:
"""Find all tasks with status='blocked'"""
7. Security Considerations
7.1 Authentication & Authorization
- JWT-based authentication
- Project-level access control
- Role-based permissions (viewer, editor, admin)
7.2 Data Protection
- All API endpoints require authentication
- Sensitive data encrypted at rest
- Audit logging for task modifications
7.3 Input Validation
- Schema validation on all API inputs
- SQL injection prevention via parameterized queries
- XSS prevention in frontend rendering
8. Performance Considerations
8.1 Caching Strategy
| Data | Cache Duration | Invalidation |
|---|---|---|
| Portfolio summary | 1 minute | On task update |
| Kanban board | 30 seconds | On task update |
| Activity feed | 1 minute | On new activity |
| Work distribution | 5 minutes | On commit/session |
8.2 Query Optimization
- Denormalized progress counters on project_plans
- Materialized view for activity feed
- Batch loading for linked entities
8.3 Scalability
- Horizontal scaling via stateless API servers
- Read replicas for dashboard queries
- Message queue for async linking operations
9. Deployment Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ GCP DEPLOYMENT │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Cloud Load Balancer │ │
│ └─────────────────────────────┬───────────────────────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Cloud Run │ │ Cloud Run │ │ Cloud Run │ │
│ │ (API) │ │ (API) │ │ (API) │ │
│ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ FoundationDB │ │ Memorystore │ │ Cloud Pub/Sub │ │
│ │ (Primary DB) │ │ (Redis Cache) │ │ (Events) │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
10. Appendices
10.1 Glossary
| Term | Definition |
|---|---|
| Checkbox | Boolean flag indicating task completion |
| Linking | Process of associating sessions/commits with tasks |
| Portfolio | Collection of all user's projects |
| Blocker | Task with status='blocked' requiring attention |
10.2 Document History
| Version | Date | Author | Changes |
|---|---|---|---|
| 1.0 | 2025-11-27 | Architecture Team | Initial release |