ADR-171: Cloud-Hosted User Dashboard for Licensed CODITECT Users

Status

Proposed — 2026-02-09

Context

CODITECT users currently work exclusively on local machines with data stored in SQLite databases. When they switch machines, change environments, or want browser-based access, their development context (sessions, trajectories, decisions, learnings) is inaccessible.

The trajectory dashboard (ADR-163) and executive BI enhancements (ADR-170) provide powerful analytics but only run locally. Licensed users need a cloud-hosted dashboard where:

1. Their local context is safely replicated to the cloud
2. They can access analytics from any browser
3. Only authenticated, licensed users can see their data
4. Team members can share project views within tenant boundaries

Existing Infrastructure

Component	Status	Location
Django Backend	Production (v1.22.0)	coditect-cloud-infra/backend/
User Auth (JWT + 2FA)	Complete	backend/users/
Multi-Tenant RBAC	Complete (48+ perms)	backend/tenants/, backend/permissions/
Context API	Complete	backend/context/views.py
Cloud Sync Client	Complete	scripts/core/cloud_sync_client.py
License Management	Complete	backend/licenses/
GCS Backup	Production	gs://coditect-cloud-infra-context-backups

Decision

D1: Dashboard Hosting at app.coditect.ai

Deploy the trajectory dashboard as a hosted web application:

• URL: https://app.coditect.ai/dashboard/
• Stack: React (from trajectory-dashboard) served by Django static files or CDN
• API: Django REST endpoints serve dashboard data from PostgreSQL
• Auth: JWT token from existing login flow at https://app.coditect.ai/

D2: Context Replication Pipeline

Local CLI → Cloud Sync Client → Context API → PostgreSQL
                                     ↓
                              Cloud Data Adapter
                                     ↓
                              Dashboard API Endpoints
                                     ↓
                              React Dashboard (Browser)

Sync scope: tool_analytics, decisions, learnings, error_solutions, skill_results, session metadata

Sync frequency: Configurable per user (default: every 15 minutes when connected)

Privacy: Each user's data is tenant-isolated via PostgreSQL RLS (Row-Level Security)

D3: Dashboard API Endpoints

New Django REST endpoints at backend/dashboard/:

Endpoint	Method	Description
/api/v1/dashboard/summary/	GET	Executive summary (overall %, health score)
/api/v1/dashboard/tracks/	GET	Track progress with task descriptions
/api/v1/dashboard/timeline/	GET	Time-series data (sessions, tokens, errors)
/api/v1/dashboard/agents/	GET	Agent activity breakdown
/api/v1/dashboard/tools/	GET	Tool usage analytics
/api/v1/dashboard/skills/	GET	Skill learnings and effectiveness
/api/v1/dashboard/session-logs/	GET	Session log digests
/api/v1/dashboard/projects/	GET	User's project list (filtered by permissions)

All endpoints require JWT auth and respect tenant/project RBAC.

D4: Dual-Mode Dashboard

The React dashboard supports two modes:

Mode	Data Source	Auth	URL
Local	data.json (static file)	None	localhost:5174
Cloud	REST API endpoints	JWT	app.coditect.ai/dashboard/

Mode detection: If window.location.hostname is localhost, use local mode. Otherwise, use cloud mode with auth.

Shared codebase: Same React components, different data fetching layer (static JSON vs. REST API).

D5: License Verification

Before serving dashboard data:

1. Check user has active CODITECT license via backend/licenses/ API
2. Verify license tier permits dashboard access (Pro, Team, Enterprise)
3. Free tier: limited to 7-day history, single project
4. Pro tier: unlimited history, 5 projects
5. Enterprise tier: unlimited everything, team sharing, admin views

Consequences

Positive

• Users can access their analytics from any browser, any device
• Context data is safely backed up in the cloud
• Team collaboration through shared tenant dashboards
• Single codebase for local and cloud dashboard
• Revenue path: dashboard is a premium feature

Negative

• Must maintain Django API endpoints in addition to Python data adapter
• Cloud hosting costs (~$200/month for production infra)
• Sync latency means cloud data is slightly behind local
• Must handle offline scenarios gracefully

Implementation Tasks

Track B: Frontend

• B.5.1: Add authentication flow to React dashboard (JWT login/logout)
• B.5.2: Create data fetching layer with local/cloud mode detection
• B.5.3: Build project selector with RBAC-filtered project list
• B.5.4: Add user preferences API integration (selected projects, theme)
• B.5.5: Implement license tier gating (feature locks for free tier)

Track A: Backend

• A.10.1: Create backend/dashboard/ Django app
• A.10.2: Implement dashboard API serializers and views
• A.10.3: Add dashboard data aggregation queries (PostgreSQL)
• A.10.4: Create sync ingestion endpoint for tool_analytics
• A.10.5: Add license tier permission checks

Track C: DevOps

• C.6.1: Deploy dashboard static assets to CDN
• C.6.2: Configure Cloud Run for dashboard API endpoints
• C.6.3: Set up PostgreSQL schema for synced analytics data
• C.6.4: Configure sync pipeline monitoring and alerting

Related ADRs

ADR	Title	Relevance
ADR-053	Cloud Sync Architecture	Data replication mechanism
ADR-092	Multi-Tenant RBAC	Permission model
ADR-118	Database Architecture	Source database schema
ADR-163	Trajectory Dashboard	Dashboard codebase
ADR-170	Multi-Project Dashboard	Project filtering