# 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)**

```bash
# 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`:

```bash
#!/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:

```bash
# 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.