BranchPy
Log in

Docs-Builder

# BranchPy Backend

Version: 1.1.1
Last Updated: January 23, 2026
Status: Production

Overview

The BranchPy backend (rc-backend) is a Node.js/Express service hosted on Railway that provides:

  • Authentication & Licensing - User auth, JWT tokens, plan enforcement
  • Remote Cloud - Cloud-synced dashboards and analysis
  • Telemetry Ingestion - Usage analytics and error reporting
  • Health & Observability - Database connectivity diagnostics

Core Documentation

Document Purpose
README.md Overview (this document)
observability.md Health endpoints, logging, monitoring

Key Features

Authentication

  • JWT-based user authentication
  • Device management and binding
  • SSO integration (Microsoft, Google)
  • 30-day offline grace period

See also: Technical/auth/README.md

Telemetry

  • Privacy-first usage analytics
  • Error reporting and diagnostics
  • Opt-in collection with local storage
  • Manual and automatic upload modes

See also: Technical/telemetry/README.md

Database Architecture

  • Core DB: User accounts, licenses, devices, sessions
  • Telemetry DB: Usage events, errors, analytics
  • Graceful degradation (telemetry DB optional)
  • Pool health monitoring

See also: observability.md

Quick Start

Health Check

# Check if backend is running
curl https://api.branchpy.com/health

# Check database connectivity
curl https://api.branchpy.com/health/db

Authentication Flow

# Login (get JWT token)
curl -X POST https://api.branchpy.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "..."}'

# Use token for subsequent requests
curl https://api.branchpy.com/user/profile \
  -H "Authorization: Bearer <token>"

Architecture

┌─────────────────────────────────────────────┐
│           VS Code Extension                  │
│  • License validation                       │
│  • Feature gating                           │
│  • Telemetry upload                         │
└──────────────┬──────────────────────────────┘
               │ HTTPS
               ↓
┌─────────────────────────────────────────────┐
│         rc-backend (Railway)                 │
│  • Express.js server                        │
│  • JWT authentication                       │
│  • Route handlers                           │
└──────┬────────────────────┬─────────────────┘
       │                    │
   Core DB            Telemetry DB
   (PostgreSQL)       (PostgreSQL)
   • Users            • Events
   • Licenses         • Errors
   • Devices          • Analytics

Environment Configuration

Required Variables

# Core Database
CORE_DB_URL=postgresql://user:pass@host:5432/core

# JWT Secret
JWT_SECRET=<secure_random_string>

# Railway (auto-provided)
RAILWAY_ENVIRONMENT=production
RAILWAY_GIT_COMMIT_SHA=abc1234

Optional Variables

# Telemetry Database (graceful degradation if absent)
TELEMETRY_DB_URL=postgresql://user:pass@host:5432/telemetry

# Build Identification
GITHUB_SHA=abc1234
BUILD_ID=12345

Deployment

The backend is deployed on Railway with:

  • Automatic deployments from main branch
  • PostgreSQL databases (core + telemetry)
  • Health check endpoints for readiness
  • Structured logging to Railway logs

See also: Technical/deployment/README.md

Monitoring & Observability

Health Endpoints

  • GET /health - Service uptime (always 200)
  • GET /health/db - Database connectivity (200/503)

Structured Logging

All backend operations emit structured JSON logs:

{
  "ts": "2026-01-23T14:32:11.382Z",
  "level": "info",
  "component": "auth",
  "event": "login.success",
  "user_id": "usr_123",
  "request_id": "req_abc"
}

Error Tracking

  • All errors include code, message, severity
  • Request IDs for log correlation
  • Railway dashboard integration

See: observability.md

Security

Current Measures

  • HTTPS only (enforced by Railway)
  • JWT token-based authentication
  • Password hashing (bcrypt)
  • SQL injection protection (parameterized queries)
  • Rate limiting (future)

Future Enhancements

  • API key rotation
  • Request rate limiting
  • IP allowlisting for admin endpoints
  • Audit logging

Source References

This document consolidates information from:

  • docs/v1.1.0/backend/health-and-observability/HEALTH_DB_ENDPOINT.md
  • docs/v1.1.0/rc-backend/ (various files)