2761857b0d
- Implemented `owl_to_mermaid.py` to convert OWL/Turtle files into Mermaid class diagrams. - Implemented `owl_to_plantuml.py` to convert OWL/Turtle files into PlantUML class diagrams. - Added two new PlantUML files for custodian multi-aspect diagrams.
240 lines
6.6 KiB
Markdown
240 lines
6.6 KiB
Markdown
# 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
|