kempersc/glam
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
glam/RUNNING_THE_APPLICATION.md
kempersc 3ff0e33bf9 Add UML diagrams and scripts for custodian schema 
- Created PlantUML diagrams for custodian types, full schema, legal status, and organizational structure.
- Implemented a script to generate GraphViz DOT diagrams from OWL/RDF ontology files.
- Developed a script to generate UML diagrams from modular LinkML schema, supporting both Mermaid and PlantUML formats.
- Enhanced class definitions and relationships in UML diagrams to reflect the latest schema updates.
2025-11-23 23:05:33 +01:00

655 lines
14 KiB
Markdown
Raw Blame History

# Running the GLAM Heritage Custodian Ontology Application
## Quick Start Guide
### Prerequisites
- Python 3.12+ with virtual environment
- Node.js 18+ with npm
- TypeDB 2.x server (optional, for database features)
### Start Everything (3 Commands)
```bash
# Terminal 1 - Activate Python environment (for backend scripts)
cd /Users/kempersc/apps/glam
source .venv/bin/activate
# Terminal 2 - Start frontend dev server
cd /Users/kempersc/apps/glam/frontend
npm run dev
# Terminal 3 - Start TypeDB (optional, only if using database features)
typedb server
```
Then open http://localhost:5174 in your browser.
---
## Detailed Setup Instructions
### 1. Python Environment Setup
The Python environment is used for data extraction scripts, schema validation, and backend utilities.
```bash
# Navigate to project root
cd /Users/kempersc/apps/glam
# Activate the virtual environment
source .venv/bin/activate
# Your prompt should change to show (glam-extractor-py3.12)
# Example: (glam-extractor-py3.12) (base) kempersc@Mac glam %
# Verify Python version
python --version
# Expected: Python 3.12.x
# Install/update dependencies (if needed)
pip install -e .
```
**What this enables**:
- LinkML schema validation
- Data extraction scripts
- RDF/OWL generation
- SPARQL query testing
- Wikidata API integration
**Common Python commands**:
```bash
# Validate a LinkML schema
linkml-validate -s schemas/20251121/linkml/01_custodian_name.yaml examples/example.yaml
# Generate OWL from LinkML
gen-owl schemas/20251121/linkml/01_custodian_name.yaml > output.owl.ttl
# Run data extraction script
python scripts/enrich_brazil_batch13.py
# Run tests
pytest tests/
```
---
### 2. Frontend Development Server
The frontend is a React + TypeScript application using Vite.
```bash
# Navigate to frontend directory
cd /Users/kempersc/apps/glam/frontend
# Install dependencies (first time only, or after package.json changes)
npm install
# Start development server
npm run dev
# Server starts on http://localhost:5174
# Output will show:
# VITE v5.x.x ready in XXX ms
# ➜ Local: http://localhost:5174/
# ➜ Network: use --host to expose
```
**IMPORTANT**: Always run `npm run dev` from the `frontend/` directory, not the project root!
**Error if run from wrong directory**:
```bash
# ❌ WRONG - From project root
cd /Users/kempersc/apps/glam
npm run dev
# Error: ENOENT: no such file or directory, open '.../package.json'
# ✅ CORRECT - From frontend directory
cd /Users/kempersc/apps/glam/frontend
npm run dev
# Server starts successfully
```
**Frontend npm commands**:
```bash
cd /Users/kempersc/apps/glam/frontend
# Development server (hot reload)
npm run dev
# Production build
npm run build
# Preview production build
npm run preview
# Type checking
npm run type-check
# Linting
npm run lint
# Run tests (if configured)
npm test
```
**Frontend structure**:
```
frontend/
├── src/
│ ├── components/ # Reusable React components
│ │ ├── graph/ # D3.js graph visualization
│ │ ├── layout/ # Navigation, Layout
│ │ ├── query/ # SPARQL query builder
│ │ └── uml/ # UML diagram visualization (NEW!)
│ ├── pages/ # Route pages
│ │ ├── Home.tsx
│ │ ├── Visualize.tsx
│ │ ├── QueryBuilderPage.tsx
│ │ └── UMLViewerPage.tsx # NEW!
│ ├── lib/ # Utilities
│ └── App.tsx # Main app + routing
├── public/ # Static assets
│ └── schemas/ # UML diagrams (NEW!)
└── package.json # Dependencies
```
---
### 3. TypeDB Server (Optional)
TypeDB is used for graph database features. Only needed if you're using the Database page or running TypeQL queries.
**Install TypeDB**:
```bash
# macOS with Homebrew
brew install typedb
# Or download from https://typedb.com/download
```
**Start TypeDB server**:
```bash
# Default configuration
typedb server
# Server starts on port 1729
# Output will show:
# TypeDB Server 2.x.x
# Listening on 0.0.0.0:1729
```
**TypeDB commands**:
```bash
# Check if server is running
typedb server status
# Stop server
typedb server stop
# Connect with console
typedb console
```
**TypeDB is optional** - The UML Viewer, Query Builder, and Visualize pages work without it.
---
## Common Workflows
### Workflow 1: View UML Diagrams
```bash
# Terminal 1 - Start frontend only
cd /Users/kempersc/apps/glam/frontend
npm run dev
# Open browser
# Navigate to: http://localhost:5174/uml-viewer
```
No Python or TypeDB needed for UML viewing!
---
### Workflow 2: Build SPARQL Queries
```bash
# Terminal 1 - Start frontend only
cd /Users/kempersc/apps/glam/frontend
npm run dev
# Open browser
# Navigate to: http://localhost:5174/query-builder
```
Query Builder generates queries in the frontend - no backend needed.
---
### Workflow 3: Visualize RDF Graph
```bash
# Terminal 1 - Start frontend
cd /Users/kempersc/apps/glam/frontend
npm run dev
# Open browser
# Navigate to: http://localhost:5174/visualize
# Upload an RDF/Turtle file or paste RDF data
```
Graph visualization runs in the browser with D3.js - no backend needed.
---
### Workflow 4: Run Data Extraction Scripts
```bash
# Terminal 1 - Activate Python environment
cd /Users/kempersc/apps/glam
source .venv/bin/activate
# Run extraction script
python scripts/enrich_brazil_batch13.py
# Or any other script
python scripts/extract_brazilian_institutions_v2.py
```
---
### Workflow 5: Validate LinkML Schemas
```bash
# Terminal 1 - Activate Python environment
cd /Users/kempersc/apps/glam
source .venv/bin/activate
# Validate schema against metamodel
linkml-validate -s schemas/20251121/linkml/01_custodian_name.yaml
# Validate data instance against schema
linkml-validate -s schemas/20251121/linkml/01_custodian_name.yaml \
schemas/20251121/examples/example.yaml
```
---
### Workflow 6: Full Stack Development
```bash
# Terminal 1 - Python environment
cd /Users/kempersc/apps/glam
source .venv/bin/activate
# Keep this terminal open for running scripts
# Terminal 2 - Frontend dev server
cd /Users/kempersc/apps/glam/frontend
npm run dev
# Runs on http://localhost:5174
# Terminal 3 - TypeDB server (if needed)
typedb server
# Runs on port 1729
# Terminal 4 - Available for git, testing, etc.
cd /Users/kempersc/apps/glam
# Run git commands, pytest, etc.
```
---
## Application Features by Route
### Home - `http://localhost:5174/`
- Project overview
- Documentation links
- Quick start guide
### UML Viewer - `http://localhost:5174/uml-viewer` ✨ NEW!
- Interactive D3.js UML diagrams
- Mermaid, PlantUML, GraphViz, ER diagrams
- Zoom, pan, drag nodes
- Click nodes for details
- 14 heritage custodian ontology diagrams
**No backend required** - Runs entirely in browser
### Query Builder - `http://localhost:5174/query-builder`
- Visual SPARQL query builder
- Add variables, triple patterns, filters
- Generate SPARQL syntax
- Execute queries (requires SPARQL endpoint)
**No backend required** for query building
### Visualize - `http://localhost:5174/visualize`
- Upload RDF/Turtle files
- Interactive force-directed graph
- SPARQL query execution
- Node metadata inspection
- Connection analysis
**No backend required** for file visualization
### Database - `http://localhost:5174/database`
- TypeDB integration
- Schema management
- Data import/export
**Requires TypeDB server** running on port 1729
### Settings - `http://localhost:5174/settings`
- Application configuration
- Theme settings
- API endpoint configuration
---
## Troubleshooting
### Issue: `npm run dev` fails with ENOENT error
**Cause**: Running npm from wrong directory
**Solution**:
```bash
# Always run from frontend/ directory
cd /Users/kempersc/apps/glam/frontend
npm run dev
```
---
### Issue: Python virtual environment not activated
**Symptoms**:
```bash
python --version
# Shows system Python, not 3.12
```
**Solution**:
```bash
cd /Users/kempersc/apps/glam
source .venv/bin/activate
# Prompt should show (glam-extractor-py3.12)
```
---
### Issue: Port 5174 already in use
**Symptoms**:
```
Error: Port 5174 is already in use
```
**Solution**:
```bash
# Find process using port 5174
lsof -ti:5174
# Kill the process
kill -9 $(lsof -ti:5174)
# Or use a different port
npm run dev -- --port 5175
```
---
### Issue: TypeDB connection failed
**Symptoms**:
```
Error: Unable to connect to TypeDB at localhost:1729
```
**Solution**:
```bash
# Check if TypeDB is running
typedb server status
# Start TypeDB if not running
typedb server
# Or skip TypeDB if not using Database page
```
---
### Issue: UML diagrams not loading
**Symptoms**:
```
Failed to load diagram: 404 Not Found
```
**Solution**:
```bash
# Verify schema files are in public directory
ls -la /Users/kempersc/apps/glam/frontend/public/schemas/20251121/uml/
# If missing, copy from source
cd /Users/kempersc/apps/glam
cp schemas/20251121/uml/mermaid/*.mmd frontend/public/schemas/20251121/uml/mermaid/
cp schemas/20251121/uml/plantuml/*.puml frontend/public/schemas/20251121/uml/plantuml/
cp schemas/20251121/uml/graphviz/*.dot frontend/public/schemas/20251121/uml/graphviz/
cp schemas/20251121/uml/erdiagram/*.mmd frontend/public/schemas/20251121/uml/erdiagram/
# Restart dev server
cd frontend
npm run dev
```
---
### Issue: TypeScript build errors
**Symptoms**:
```
src/components/graph/InteractiveGraph.tsx(108,10): error TS6133: 'isBidirectional' is declared but its value is never read.
```
**Solution**:
These are non-critical warnings. The app will still run in dev mode.
To suppress:
```bash
cd /Users/kempersc/apps/glam/frontend
npm run dev 2>&1 | grep -v "TS6133\|TS1484"
```
Or fix by removing unused variables/imports.
---
## Environment Variables
### Frontend (`.env`)
Create `frontend/.env` for configuration:
```env
# SPARQL Endpoint (optional)
VITE_SPARQL_ENDPOINT=http://localhost:7200/repositories/heritage-custodians
# TypeDB Connection (optional)
VITE_TYPEDB_HOST=localhost
VITE_TYPEDB_PORT=1729
# API Base URL (optional, for future backend)
VITE_API_BASE_URL=http://localhost:8000
```
**Note**: All `VITE_*` variables are exposed to the browser!
---
## Production Build
### Build Frontend for Production
```bash
cd /Users/kempersc/apps/glam/frontend
# Build optimized production bundle
npm run build
# Output in frontend/dist/
ls -la dist/
# Preview production build locally
npm run preview
# Runs on http://localhost:4173
```
### Deploy to Static Hosting
```bash
# Build
cd frontend
npm run build
# Deploy dist/ folder to:
# - GitHub Pages
# - Netlify
# - Vercel
# - AWS S3 + CloudFront
# - Any static hosting service
```
**Example - Deploy to GitHub Pages**:
```bash
cd /Users/kempersc/apps/glam/frontend
# Build
npm run build
# Deploy (assuming gh-pages npm package installed)
npm run deploy
```
---
## Quick Reference Card
### Start Frontend Only (Most Common)
```bash
cd /Users/kempersc/apps/glam/frontend && npm run dev
```
→ http://localhost:5174
### Start Frontend + Python Environment
```bash
# Terminal 1
cd /Users/kempersc/apps/glam && source .venv/bin/activate
# Terminal 2
cd /Users/kempersc/apps/glam/frontend && npm run dev
```
### Start Full Stack
```bash
# Terminal 1: Python
cd /Users/kempersc/apps/glam && source .venv/bin/activate
# Terminal 2: Frontend
cd /Users/kempersc/apps/glam/frontend && npm run dev
# Terminal 3: TypeDB (optional)
typedb server
```
### Stop All Servers
```bash
# Stop Vite (Ctrl+C in frontend terminal)
^C
# Stop TypeDB (Ctrl+C in TypeDB terminal)
^C
# Or kill processes by port
kill -9 $(lsof -ti:5174) # Vite
kill -9 $(lsof -ti:1729) # TypeDB
```
---
## Directory Navigation Aliases (Optional)
Add to your `~/.zshrc` or `~/.bashrc`:
```bash
# GLAM project aliases
alias glam='cd /Users/kempersc/apps/glam'
alias glamfe='cd /Users/kempersc/apps/glam/frontend'
alias glampy='cd /Users/kempersc/apps/glam && source .venv/bin/activate'
# Quick start commands
alias glam-dev='cd /Users/kempersc/apps/glam/frontend && npm run dev'
alias glam-py='cd /Users/kempersc/apps/glam && source .venv/bin/activate'
```
**Usage**:
```bash
# Navigate to project
glam
# Navigate to frontend and start dev server
glam-dev
# Activate Python environment
glam-py
```
---
## Summary of Key Directories
```
/Users/kempersc/apps/glam/
├── .venv/ # Python virtual environment (activate with source)
├── frontend/ # React/TypeScript frontend (run npm here!)
│ ├── src/ # Source code
│ ├── public/ # Static assets (UML diagrams here)
│ ├── package.json # npm dependencies (run npm install here)
│ └── vite.config.ts # Vite configuration
├── schemas/ # LinkML schemas and UML diagrams (source)
├── scripts/ # Python data extraction scripts
├── tests/ # Python unit tests
├── pyproject.toml # Python project config
└── README.md # Project documentation
```
---
## Getting Help
- **Frontend Issues**: Check `frontend/package.json` for dependencies
- **Python Issues**: Check `pyproject.toml` for Python packages
- **Schema Issues**: See `schemas/20251121/linkml/` for LinkML definitions
- **UML Viewer**: See `D3JS_UML_VISUALIZATION_COMPLETE.md` for details
- **Query Builder**: See `QUERY_BUILDER_LAYOUT_FIX.md` for usage
---
## Version Information
- **Node.js**: 18.x or higher
- **npm**: 9.x or higher
- **Python**: 3.12.x
- **React**: 18.x
- **TypeScript**: 5.x
- **Vite**: 5.x
- **D3.js**: 7.x
- **TypeDB**: 2.x (optional)
---
**Last Updated**: November 23, 2025
**Project**: GLAM Heritage Custodian Ontology
**Documentation**: Complete
Reference in a new issue View git blame Copy permalink