glam/frontend

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

# 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

# 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 ✅

• IndexedDB storage for large RDF files
• N-Triples RDF parser
• Turtle RDF parser
• Graph utility functions
• React hooks for data management
• Type-safe TypeScript interfaces
• 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:

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

# 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
• TypeScript Handbook
• D3.js v7 Documentation
• Vitest Documentation
• Zustand Documentation
• React Query Docs

🤝 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