stemedb/applications/DASHBOARD_SYNC.md

Dashboard Sync Guide

This document explains how to sync shared code between StemeDB Dashboard and Aphoria Dashboard.

Architecture Decision

Both dashboards use the Copy with Documentation approach:

• Shared infrastructure is copied, not abstracted into a monorepo package
• This minimizes build complexity and allows independent versioning
• Controlled divergence is acceptable with documented sync procedures

Shared Components

Shared Code (Keep in Sync)

These files should be kept synchronized between dashboards:

UI Components (src/components/ui/)

• badge.tsx
• button.tsx
• card.tsx
• date-picker.tsx
• input.tsx
• separator.tsx
• sheet.tsx
• tabs.tsx

Shared Components (src/components/shared/)

• confirmation-dialog.tsx
• api-status.tsx
• error-state.tsx

Reusable Layout Components (src/components/layout/)

• header.tsx
• theme-toggle.tsx

Note: Do NOT sync sidebar.tsx - each dashboard has its own navigation.

Library Code (src/lib/)

• api/client.ts - API client (has both StemeDB + Aphoria methods)
• api/types.ts - Type definitions
• api/index.ts - API exports
• utils.ts - Utilities
• format.ts - Formatting helpers
• types.ts - Type definitions
• constants.ts - Constants
• auth/api-key.ts - API key handling

Base Configuration

• globals.css - TailwindCSS globals
• components.json - shadcn/ui config

Dashboard-Specific Code (Do NOT Sync)

StemeDB Dashboard Only

• src/app/skeptic/, src/app/layered/, src/app/sources/, src/app/quarantine/, src/app/circuit/, src/app/audit/
• src/components/skeptic/, src/components/layered/, src/components/sources/, src/components/quarantine/, src/components/circuit/, src/components/audit/
• src/components/layout/sidebar.tsx (6 routes)
• package.json (port 18188)

Aphoria Dashboard Only

• src/app/scans/, src/app/claims/, src/app/corpus/
• src/components/scans/, src/components/claims/, src/components/corpus/
• src/components/layout/sidebar.tsx (3 routes)
• package.json (port 18189)

Sync Procedures

When to Sync

You need to sync when:

1. Adding new shadcn/ui components - Add to both dashboards
2. Updating API types - Update lib/api/types.ts in both
3. Changing API client methods - Update lib/api/client.ts in both
4. Modifying shared utilities - Update lib/utils.ts, lib/format.ts, etc.
5. Changing globals.css - Update in both

How to Sync

Option 1: Manual Copy (Recommended)

# Sync UI components
cp -r stemedb-dashboard/src/components/ui/* aphoria-dashboard/src/components/ui/

# Sync shared components
cp -r stemedb-dashboard/src/components/shared/* aphoria-dashboard/src/components/shared/

# Sync layout components (except sidebar)
cp stemedb-dashboard/src/components/layout/header.tsx aphoria-dashboard/src/components/layout/
cp stemedb-dashboard/src/components/layout/theme-toggle.tsx aphoria-dashboard/src/components/layout/

# Sync lib directory
cp -r stemedb-dashboard/src/lib/* aphoria-dashboard/src/lib/

# Sync globals.css
cp stemedb-dashboard/src/app/globals.css aphoria-dashboard/src/app/

Option 2: rsync Script

Create a script sync-dashboards.sh:

#!/bin/bash
set -e

SRC="applications/stemedb-dashboard/src"
DEST="applications/aphoria-dashboard/src"

echo "Syncing shared code from StemeDB to Aphoria Dashboard..."

# Sync UI components
rsync -av --delete "$SRC/components/ui/" "$DEST/components/ui/"

# Sync shared components
rsync -av --delete "$SRC/components/shared/" "$DEST/components/shared/"

# Sync layout components (exclude sidebar)
rsync -av --exclude="sidebar.tsx" "$SRC/components/layout/" "$DEST/components/layout/"

# Sync lib directory
rsync -av --delete "$SRC/lib/" "$DEST/lib/"

# Sync globals.css
rsync -av "$SRC/app/globals.css" "$DEST/app/"

echo "Sync complete!"

Option 3: Reverse Sync (Aphoria → StemeDB)

If you make changes in Aphoria Dashboard first:

# Reverse direction
SRC="applications/aphoria-dashboard/src"
DEST="applications/stemedb-dashboard/src"

# Same rsync commands but reversed

Sync Checklist

After syncing, verify:

• Both dashboards build without errors
• No import errors in browser console
• Shared components render correctly in both dashboards
• API calls work in both dashboards
• UI components match in both dashboards

Dependency Version Management

Keep Aligned

Both package.json files should have matching versions for:

• next
• react
• react-dom
• tailwindcss
• @tailwindcss/postcss
• lucide-react
• class-variance-authority
• clsx
• tailwind-merge
• All other shared dependencies

Update Strategy

When updating dependencies:

1. Update package.json in both dashboards
2. Run npm install in both
3. Test both dashboards
4. Commit both at the same time

Future: Monorepo Packages

If code drift becomes problematic, consider refactoring to:

applications/
├── packages/
│   ├── dashboard-shared/     # Shared UI components, lib, utils
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── lib/
│   │   │   └── index.ts
│   │   └── package.json
│   └── dashboard-api/        # Shared API client
│       ├── src/
│       │   └── client.ts
│       └── package.json
├── stemedb-dashboard/
│   ├── package.json          # Depends on dashboard-shared
│   └── src/
└── aphoria-dashboard/
    ├── package.json          # Depends on dashboard-shared
    └── src/

This would:

• Eliminate manual syncing
• Enforce shared component consistency
• Add build complexity (workspace setup)
• Require version management between packages

Decision Point: If syncing more than once a week, migrate to monorepo.

Questions?

If you're unsure whether to sync a file:

• Is it in the Shared Code list above? → Sync it
• Is it in the Dashboard-Specific list? → Don't sync it
• Not sure? → Check if it's used by both dashboards. If yes, sync it.