cce54358d2
**Git Commit Tracking** - Automatically capture git commit hash when claims/observations are ingested - Store in assertion metadata for temporal context and audit trails - Graceful degradation in non-git environments - Solves double-commit problem by capturing hash at ingestion time **Implementation** - walker/git.rs: get_current_commit_hash() utility function - bridge.rs: Accept optional git_commit parameter in all conversion functions - episteme/local: Store project_root, capture git hash during ingestion - 5 new tests for git hash tracking + metadata validation - All 1162 aphoria tests passing **Documentation Overhaul** - README: Added Observations vs Claims distinction, git tracking, dashboard - CLI Reference: New sections for git integration and ignore/exclusion system - Comprehensive ignore documentation: .aphoriaignore, inline comments, 4 methods - Enhanced verification engine docs with matching capabilities - DOCUMENTATION_UPDATES.md: Complete audit summary **Dashboard Separation** - Moved Aphoria-specific UI from stemedb-dashboard to aphoria-dashboard - Clean separation of concerns: StemeDB for core, Aphoria for security - Added dashboard documentation and setup guides Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
215 lines
6.0 KiB
Markdown
215 lines
6.0 KiB
Markdown
# 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.
|