Developer Guide

Welcome to the PBS Knowledge developer documentation. This section covers everything you need to contribute to or extend the system.

Getting Started

Prerequisites

Before starting development, ensure you have:

• Node.js 20.x or later
• Docker and Docker Compose
• Git
• A code editor (VS Code recommended)

Quick Start

# Clone the repository
git clone https://github.com/cosanlab/pbs_knowledge.git
cd pbs_knowledge

# Copy environment file
cp .env.example .env
# Edit .env with your configuration

# Start development environment
docker compose -f docker-compose.hybrid.yml -f docker-compose.dev.yml up -d

# View logs
docker compose -f docker-compose.hybrid.yml -f docker-compose.dev.yml logs -f

Development URLs

• Frontend: http://localhost:5173 (Vite dev server)
• Backend API: http://localhost:3000
• TerminusDB: http://localhost:6363
• Application: http://localhost (via NGINX)

Project Structure

pbs_knowledge/
├── backend/              # Fastify API server
│   ├── src/
│   │   ├── routes/       # API route handlers
│   │   ├── services/     # Business logic
│   │   ├── plugins/      # Fastify plugins
│   │   ├── middleware/   # Request middleware
│   │   ├── workers/      # Background job processors
│   │   ├── schema/       # TerminusDB schema
│   │   └── types/        # TypeScript types
│   └── scripts/          # Utility scripts
├── frontend/             # Svelte 5 application
│   ├── src/
│   │   ├── lib/          # Shared libraries
│   │   ├── pages/        # Page components
│   │   └── routes/       # Route components
│   └── public/           # Static assets
├── documentation/        # This documentation site
├── nginx/                # NGINX configuration
├── docs/                 # Internal documentation
└── docker-compose*.yml   # Container configurations

Key Concepts

Knowledge Graph

PBS Knowledge uses TerminusDB as its primary database:

• Data modeled as a graph
• Relationships are first-class
• Schema-enforced data integrity
• GraphQL API for queries

Schema-Driven Development

Forms and validation are generated from the schema:

• TerminusDB schema defines data structure
• JSON Schema generated for validation
• Felte + AJV handle form rendering
• Consistent data handling throughout

Service Architecture

Backend follows a layered architecture:

• Routes handle HTTP
• Services contain business logic
• TerminusDB client manages data
• Workers process background jobs

Developer Documentation

Section	Description
Architecture	System design and patterns
Performance & Caching	Redis caching, query optimization
Authentication	SAML SSO and authorization
Deployment	Deployment procedures
Schemas	TerminusDB schema reference
Schema-Driven Forms	Form generation system
API Reference	REST API documentation
Contributing	How to contribute

Development Workflow

Making Changes

1. Create a feature branch
2. Make your changes
3. Test locally
4. Submit a pull request
5. Address review feedback
6. Merge after approval

Running Tests

# Backend tests
cd backend && npm run test:run

# Frontend tests
cd frontend && npm run test:run

# Type checking
cd frontend && npm run check
cd backend && npm run typecheck

Code Quality

# Lint all code
npm run lint

# Format code
npm run format

# Fix lint issues
npm run lint:fix

Getting Help

• GitHub Issues: Report bugs and request features
• Documentation: Check these docs first
• Code Comments: Read inline documentation
• Team: Contact the development team