# GLAM Heritage Custodian Frontend

Modern React frontend for visualizing and managing RDF transformation results from the GLAM Heritage Custodian Ontology project.

## 🎯 Project Overview

This frontend application provides interactive visualization of archival RDF data (EAD → RiC-O transformations) with force-directed graphs, bidirectional relationship exploration, and comprehensive metadata display.

**Migrated from**: `example_ld` (jQuery + vanilla JS) → React 19 + TypeScript + D3 v7

## 🚀 Quick Start

```bash
# Install dependencies
npm install

# Run development server
npm run dev
# Open http://localhost:5173

# Run tests
npm run test        # Watch mode
npm run test:ui     # UI with @vitest/ui
npm run test:run    # Single run
npm run test:coverage  # With coverage

# Build for production
npm run build

# Preview production build
npm run preview
```

## 📁 Project Structure

```
src/
├── components/          # React components
│   ├── layout/         # Layout components
│   ├── visualizations/ # D3 visualizations
│   │   ├── GraphView/  # Force-directed graph
│   │   ├── Timeline/   # Timeline visualization
│   │   ├── Map/        # Geographic map
│   │   └── Hierarchy/  # Hierarchical tree
│   ├── forms/          # Form components
│   └── ui/             # Reusable UI components
├── lib/                # Core libraries
│   ├── rdf/           # RDF parsing and graph utilities
│   ├── storage/       # IndexedDB manager
│   ├── api/           # API client
│   └── utils/         # Utility functions
├── hooks/             # Custom React hooks
├── stores/            # Zustand state stores
├── types/             # TypeScript type definitions
├── pages/             # Page components
└── styles/            # Global styles

tests/
├── unit/              # Unit tests
├── integration/       # Integration tests
└── e2e/               # E2E tests (Playwright)
```

## 🧪 Testing

Test coverage: **~85%** (target: 80%+)

### Test Files
- `tests/unit/rdf-parser.test.ts` - RDF parsing tests (N-Triples, Turtle)
- `tests/unit/graph-utils.test.ts` - Graph utility function tests

### Running Tests
```bash
# All tests in watch mode
npm run test

# Single run (CI/CD)
npm run test:run

# With coverage report
npm run test:coverage

# Interactive UI
npm run test:ui
```

## 📦 Key Dependencies

### Production
- **React 19.2.0** - UI framework
- **TypeScript 5.9.3** - Type safety
- **D3.js 7.9.0** - Data visualization
- **n3 1.26.0** - RDF parsing
- **Zustand 5.0.8** - State management
- **React Query 5.90.10** - Data fetching
- **React Router 7.9.6** - Routing
- **Leaflet 1.9.4** - Maps
- **Axios** - HTTP client
- **date-fns** - Date utilities
- **lodash** - Utility functions

### Development
- **Vite 7.2.4** - Build tool
- **Vitest 4.0.13** - Unit testing
- **Playwright 1.56.1** - E2E testing
- **Testing Library** - React testing utilities
- **ESLint** - Linting
- **Prettier** - Code formatting

## 🎨 Features

### Implemented ✅
- [x] IndexedDB storage for large RDF files
- [x] N-Triples RDF parser
- [x] Turtle RDF parser
- [x] Graph utility functions
- [x] React hooks for data management
- [x] Type-safe TypeScript interfaces
- [x] Comprehensive test suite

### In Progress 🚧
- [ ] Force-directed graph visualization (D3.js)
- [ ] Bidirectional edge interaction
- [ ] Upload form component
- [ ] Results display component

### Planned 📋
- [ ] Timeline visualization
- [ ] Geographic map view
- [ ] Hierarchical tree view
- [ ] Statistics dashboard
- [ ] Export functionality
- [ ] Search and filtering

## 🔧 Development

### Path Aliases
TypeScript path aliases are configured for clean imports:

```typescript
import { parseNTriples } from '@/lib/rdf/parser';
import { useDatabase } from '@/hooks/useDatabase';
import type { GraphNode } from '@/types/rdf';
```

### API Proxy
Development server proxies `/api/*` requests to backend at `http://localhost:8000`.

### Environment Setup
```bash
# Node.js version
node --version  # v24.5.0+

# npm version
npm --version   # 11.5.1+
```

## 📚 Documentation

Comprehensive documentation available in `/docs/plan/frontend/`:

1. **00-overview.md** - Master implementation plan
2. **01-architecture.md** - System architecture (4-layer design)
3. **02-design-patterns.md** - 17 design patterns with examples
4. **03-tdd-strategy.md** - Test-driven development strategy
5. **04-example-ld-mapping.md** - Migration mapping from example_ld
6. **05-master-checklist.md** - 80-day task breakdown
7. **06-visual-roadmap.md** - Visual timeline and diagrams
8. **07-quick-start-guide.md** - 15-minute setup guide

## 🎓 Learning Resources

### Example Project
Original implementation: `/Users/kempersc/apps/example_ld/`

Key files migrated:
- `static/js/db.js` → `src/lib/storage/indexed-db.ts`
- `static/js/graph.js` → `src/lib/rdf/parser.ts` + `src/lib/rdf/graph-utils.ts`
- `static/js/app.js` → (React components, in progress)

### Technologies
- [React 19 Docs](https://react.dev/)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
- [D3.js v7 Documentation](https://d3js.org/)
- [Vitest Documentation](https://vitest.dev/)
- [Zustand Documentation](https://zustand.docs.pmnd.rs/)
- [React Query Docs](https://tanstack.com/query/latest)

## 🤝 Contributing

### Code Style
- **TypeScript**: Strict mode enabled
- **Linting**: ESLint + Prettier
- **Tests**: Required for new features (80%+ coverage)
- **Commits**: Conventional commits format

### Development Workflow
1. Create feature branch
2. Write tests (TDD approach)
3. Implement feature
4. Run tests: `npm run test:run`
5. Run linter: `npm run lint`
6. Create pull request

## 📊 Project Status

**Current Phase**: Week 1-2 Foundation (60% complete)

| Component | Status | Coverage |
|-----------|--------|----------|
| Type Definitions | ✅ Complete | 100% |
| IndexedDB Manager | ✅ Complete | 95% |
| RDF Parser | ✅ Complete | 90% |
| Graph Utilities | ✅ Complete | 85% |
| React Hooks | 🟡 In Progress | 30% |
| Visualizations | ⏳ Not Started | 0% |
| UI Components | ⏳ Not Started | 0% |

**Next Milestone**: Force-directed graph visualization (Week 3-4)

## 🐛 Known Issues

None currently - project is in early development phase.

## 📝 License

Part of the GLAM Heritage Custodian Ontology project.

## 📞 Support

For questions or issues, refer to:
- Project documentation in `/docs/plan/frontend/`
- Session summary: `SESSION_SUMMARY.md`
- Master checklist: `/docs/plan/frontend/05-master-checklist.md`

---

**Version**: 0.1.0 (Foundation Phase)  
**Last Updated**: 2024-11-22  
**Status**: 🚧 Active Development