ADR-130: Business Intelligence Dashboard Architecture

Status

ACCEPTED - 2026-01-28

Context

CODITECT needs a comprehensive business intelligence solution to:

1. Visualize Project Progress - Track status across 14+ tracks with drill-down capability
2. Monitor Resource Allocation - Identify agent bottlenecks and workload distribution
3. Analyze Token Economics - Cost attribution, usage trends, budget tracking
4. Generate Reports - Export analytics as Markdown/PDF for stakeholders
5. Enable Local-First Operation - Work offline with local databases

Requirements

Requirement	Priority	Rationale
Real-time track progress visualization	P0	Core project management need
Token economics dashboard	P0	Cost control and billing prep
Resource allocation view	P1	Capacity planning
Export to Markdown/PDF	P1	Stakeholder communication
Local-first architecture	P0	Offline capability, privacy
Browser-based UI	P0	Cross-platform accessibility
Auto-launch capability	P1	Developer experience

Constraints

1. Must integrate with existing four-tier database architecture (ADR-118)
2. Must leverage existing component-viewer infrastructure
3. Must support offline operation with local SQLite databases
4. Must provide immediate value with mock data when databases unavailable

Decision

Implement a local React-based BI dashboard using the following architecture:

Technology Stack

Layer	Technology	Rationale
Frontend	React 18 + Vite 6	Matches component-viewer, fast HMR
Styling	Tailwind CSS 3.4	Consistent with existing tools
Charts	Recharts	React-native, lightweight
Icons	Lucide React	Consistent with component-viewer
CLI	Node.js ESM	Auto-launch, browser open
Data	SQLite (existing DBs)	Local-first, existing infrastructure

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                         /bi Command                              │
│                              │                                   │
│                              ▼                                   │
│                    ┌──────────────────┐                         │
│                    │    CLI (cli.js)   │                         │
│                    │  • Port config    │                         │
│                    │  • Browser launch │                         │
│                    │  • Data paths     │                         │
│                    └─────────┬────────┘                         │
│                              │                                   │
│                              ▼                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Vite Development Server                     │   │
│  │                   (localhost:5174)                       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                   │
│                              ▼                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                   React Application                      │   │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐        │   │
│  │  │  Overview   │ │   Tracks    │ │  Resources  │        │   │
│  │  │    View     │ │    View     │ │    View     │        │   │
│  │  └─────────────┘ └─────────────┘ └─────────────┘        │   │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐        │   │
│  │  │  Analytics  │ │   Export    │ │   Config    │        │   │
│  │  │    View     │ │   Module    │ │   Panel     │        │   │
│  │  └─────────────┘ └─────────────┘ └─────────────┘        │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                   │
│                              ▼                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                 Data Service Layer                       │   │
│  │    ┌──────────────┐    ┌──────────────┐                 │   │
│  │    │ API Client   │    │ Mock Data    │                 │   │
│  │    │ (when avail) │    │ (fallback)   │                 │   │
│  │    └──────────────┘    └──────────────┘                 │   │
│  └─────────────────────────────────────────────────────────┘   │
│                              │                                   │
│           ┌──────────────────┼──────────────────┐               │
│           ▼                  ▼                  ▼               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │ sessions.db │    │   org.db    │    │ platform.db │         │
│  │ (Tier 3)    │    │ (Tier 2)    │    │ (Tier 1)    │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
│                              │                                   │
│                              ▼                                   │
│                    ┌─────────────────┐                          │
│                    │   TRACK Files   │                          │
│                    │   (Tier 0)      │                          │
│                    └─────────────────┘                          │
└─────────────────────────────────────────────────────────────────┘

Data Flow

TRACK Files (MD) ──parse──▶ Track Progress Data
sessions.db ──query──▶ Token Economics
org.db ──query──▶ Decisions, Learnings
platform.db ──query──▶ Component Stats
                         │
                         ▼
              ┌──────────────────┐
              │   Data Service   │
              │  (dataService.js)│
              └────────┬─────────┘
                       │
                       ▼
              ┌──────────────────┐
              │  React App State │
              │   (useState)     │
              └────────┬─────────┘
                       │
           ┌───────────┼───────────┐
           ▼           ▼           ▼
      Overview    Tracks View  Analytics
         │             │           │
         ▼             ▼           ▼
    ┌─────────────────────────────────┐
    │       Export Module             │
    │  • Markdown generation          │
    │  • JSON export                  │
    │  • PDF (via browser print)      │
    └─────────────────────────────────┘

View Components

View	Purpose	Data Source
Overview	Executive KPIs, summary	All sources
Tracks	Track-by-track progress	TRACK files
Resources	Agent allocation, workload	Track assignments
Analytics	Token economics, trends	sessions.db

Export Capabilities

Format	Method	Use Case
Markdown	exportAsMarkdown()	Documentation, session logs
JSON	exportAsJSON()	Data exchange, API integration
PDF	Browser print dialog	Stakeholder reports

Alternatives Considered

1. Server-Side Dashboard (Python Flask)

Pros:

• Direct SQLite access
• No frontend build step

Cons:

• Additional runtime dependency
• Slower iteration cycle
• Less interactive UI

Decision: Rejected - Frontend-focused approach matches existing tools

2. Static Site Generator

Pros:

• No server required
• Easy deployment

Cons:

• No real-time updates
• Limited interactivity
• Requires rebuild for data changes

Decision: Rejected - Need real-time data refresh

3. Electron App

Pros:

• Native app experience
• Direct SQLite access

Cons:

• Large binary size
• More complex distribution
• Overkill for local dashboard

Decision: Rejected - Browser-based approach simpler

4. VS Code Extension

Pros:

• Integrated with development workflow
• Rich UI capabilities

Cons:

• Limited to VS Code users
• Complex development model
• Different from existing patterns

Decision: Rejected - Browser approach more universal

Consequences

Positive

1. Consistent Architecture - Matches component-viewer patterns
2. Fast Development - Vite HMR enables rapid iteration
3. Offline Capable - Local databases, mock data fallback
4. Export Ready - Built-in Markdown/JSON export
5. Extensible - Easy to add new views and data sources

Negative

1. Browser Dependency - Requires modern browser
2. No Real Backend - Limited to local data (acceptable for local-first)
3. Mock Data Gap - Initial version uses mock data

Neutral

1. Port Usage - Uses port 5174 (configurable)
2. NPM Dependencies - Requires npm install on first run

Implementation

Phase 1: Foundation (J.17.1) ✅

• Create tool directory structure
• Set up package.json with dependencies
• Create CLI for server launch
• Implement Vite configuration
• Create basic React app shell
• Implement overview dashboard

Phase 2: Data Integration (J.17.2)

• Create data service layer
• Implement TRACK file parser
• Connect to sessions.db queries
• Implement real-time refresh

Phase 3: Export & Reports (J.17.3)

• Markdown export function
• JSON export function
• Print-friendly CSS for PDF
• Scheduled report generation

Phase 4: Advanced Features (J.17.4)

• Historical trend charts (Recharts)
• Drill-down to individual tasks
• Custom date range selection
• Comparison views (week-over-week)

Related ADRs

ADR	Relationship
ADR-118	Four-tier database architecture (data source)
ADR-116	Track-based plan architecture (track data)
ADR-054	Track nomenclature (task IDs)
ADR-089	Component database separation (platform.db)

References

• Component Viewer Architecture
• Context Query Script
• Track Files
• BI Dashboard Tool
• /bi Command

---

Author: senior-architect Reviewers: frontend-react-typescript-expert Approved: 2026-01-28