Skip to content

Development Guide

This guide covers the development workflow and best practices for XRXP.

Development Workflow

1. Branch Naming

  • feature/description - New features
  • bugfix/description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring

2. Commit Messages

Use clear, descriptive commit messages:

feat: add user authentication
fix: resolve WebSocket connection timeout
docs: update API endpoint documentation
refactor: simplify session service logic

3. Before Committing

Run tests for affected services:

# Dashboard
pnpm --filter @xrxp/dashboard test

# API
pnpm --filter @xrxp/api test

# WebSocket
pnpm --filter @xrxp/websocket-ingestion test:retro

Service Development

Dashboard (SvelteKit)

pnpm --filter @xrxp/dashboard install
pnpm --filter @xrxp/dashboard dev  # Development server on :5174

Key directories: - apps/dashboard/src/routes/ - SvelteKit routes - apps/dashboard/src/lib/api/ - API client - apps/dashboard/src/lib/websocket/ - live subscription store - apps/dashboard/src/lib/components/ - dashboard UI components

REST API

pnpm --filter @xrxp/api install
pnpm --filter @xrxp/api dev

Key directories: - src/routes/ - Express routes - src/controllers/ - Request handlers - src/services/ - Business logic - src/config/ - runtime configuration and logger wiring

WebSocket Server

pnpm --filter @xrxp/websocket-ingestion install
pnpm --filter @xrxp/websocket-ingestion dev

Key directories: - src/services/ - WebSocket and data processing - src/config/ - Configuration - test/ - Retro-compatibility tests

Debugging

Dashboard

Use browser devtools and the Svelte component tooling available in your setup.

Backend

Use console.log or Winston logger:

const logger = require('./src/utils/logger');

logger.debug('Debug message', { data: value });
logger.info('Info message');
logger.error('Error message', error);

Database Migrations

When changing database schema:

  1. Update packages/database/prisma/schema.prisma
  2. Create migration scripts
  3. Test migrations on a copy of production data
  4. Document changes in service docs

Environment Variables

Never commit sensitive values:

  • Use .env.local for local development
  • Add new variables to .env.example without real values
  • Document all new variables in docs

Code Review Checklist

Before submitting PR:

  • [ ] Code follows style guidelines
  • [ ] Tests pass
  • [ ] Documentation updated
  • [ ] No hardcoded secrets
  • [ ] Error handling implemented
  • [ ] Logging added for important operations

Documentation

Update docs when:

  • Adding new features
  • Changing API endpoints
  • Modifying configuration
  • Updating architecture

Build docs locally:

./scripts/docs.sh serve