glam/RUNNING_THE_APPLICATION.md

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)

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

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

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

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

# ❌ 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:

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:

# macOS with Homebrew
brew install typedb

# Or download from https://typedb.com/download

Start TypeDB server:

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

# 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

# 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

# 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

# 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

# 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

# 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

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

# Always run from frontend/ directory
cd /Users/kempersc/apps/glam/frontend
npm run dev

---

Issue: Python virtual environment not activated

Symptoms:

python --version
# Shows system Python, not 3.12

Solution:

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:

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

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

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

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:

# 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

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

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

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)

cd /Users/kempersc/apps/glam/frontend && npm run dev

→ http://localhost:5174

Start Frontend + Python Environment

# 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

# 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

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

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

# 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