# 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