stemedb/applications/aphoria-dashboard/QUICK_REFERENCE.md

Aphoria Dashboard Quick Reference

Project Path Configuration

Where to Set It

Sidebar → Bottom section → "Project Path" input

The path persists in localStorage across page reloads.

How Components Use It

import { useProjectPath } from "@/lib/hooks/useProjectPath";

function MyComponent() {
  const { projectPath, setProjectPath, isLoading } = useProjectPath();

  // Use projectPath in API calls
  const result = await client.someOperation({ project_path: projectPath });
}

Storage Functions (Advanced)

import {
  getProjectPath,
  setProjectPath,
  clearProjectPath,
  hasCustomProjectPath
} from "@/lib/project/storage";

// Direct localStorage access (usually not needed - use hook instead)
const path = getProjectPath();           // Get from localStorage
setProjectPath("/new/path");             // Save to localStorage
clearProjectPath();                       // Remove from localStorage
const isCustom = hasCustomProjectPath(); // Check if custom path set

Component Patterns

Scans Panel

• No local path state
• Uses useProjectPath() hook
• Validates path before scanning
• ScanForm displays path as read-only

Claims Panel

• No local path state
• Uses useProjectPath() hook
• Validates path before all operations (list, verify, coverage)
• Shows path in card header

Corpus Panel

• Does NOT use project path (queries across all projects)
• No changes needed

Visual Indicators

• Green Dot (●) in sidebar = custom path is set
• "Default path" = using fallback default
• "Custom path" = using localStorage value

Error Handling

All operations validate the path:

if (!projectPath.trim()) {
  setError("Please set a project path in the sidebar");
  return;
}

Environment Variables

# Optional: Override default project path
NEXT_PUBLIC_DEFAULT_PROJECT_PATH=/custom/default/path

Used when:

1. localStorage is empty (new user)
2. Server-side rendering (before localStorage available)

Debugging

Check localStorage in DevTools

1. Open DevTools → Application → Local Storage
2. Look for key: aphoria-project-path
3. Value shows current path

Clear Stored Path

// In browser console:
localStorage.removeItem('aphoria-project-path');
location.reload();

Architecture

Storage Layer (SSR-safe):
  lib/project/storage.ts
    ↓
React Hook (Client-side):
  lib/hooks/useProjectPath.ts
    ↓
Components:
  - layout/sidebar.tsx (input)
  - scans/scans-panel.tsx (consumer)
  - claims/claims-panel.tsx (consumer)

Files Modified

Created:

• src/lib/project/storage.ts - localStorage persistence
• src/lib/hooks/useProjectPath.ts - React hook

Modified:

• src/components/layout/sidebar.tsx - Project path input
• src/components/scans/scans-panel.tsx - Use hook, remove local state
• src/components/scans/scan-form.tsx - Display-only path
• src/components/claims/claims-panel.tsx - Use hook, remove duplication

Testing

Unit Tests (Not Implemented Yet)

// Example test structure:
describe('useProjectPath', () => {
  it('loads from localStorage on mount', () => {});
  it('saves to localStorage on change', () => {});
  it('returns empty string during SSR', () => {});
});

E2E Tests (Not Implemented Yet)

test('project path persists across navigation', async ({ page }) => {
  await page.goto('/scans');
  await page.fill('[placeholder="/path/to/project"]', '/test/path');
  await page.goto('/claims');
  // Verify path is still /test/path
});

Common Issues

Issue: Path not persisting

Solution: Check if localStorage is enabled in browser

Issue: "Please set a project path in sidebar"

Solution: Enter a valid path in sidebar input

Issue: SSR hydration mismatch

Solution: Hook uses isLoading state to avoid rendering path until client-side

Issue: Default path not working

Solution: Check NEXT_PUBLIC_DEFAULT_PROJECT_PATH env var or hardcoded default in storage.ts

Future Enhancements

See PROJECT_PATH_IMPLEMENTATION.md for:

• Recent projects list
• Project validation
• Multi-project support
• Project metadata storage