Skip to content

Backend Documentation

This section contains comprehensive documentation for the Qubital backend service, including API endpoints, system architecture, development guides, and operational standards.

🚀 Quick Start

Base URLs

  • Development: https://dev-api.example.com
  • Production: https://api.example.com

Authentication

All API requests require authentication. See Authentication Endpoints for details on sign-in, OAuth flows, and token management.

📚 Documentation Sections

API Endpoints

Complete reference for all backend API endpoints:

  • Authentication - User authentication, OAuth flows, session management, and token handling
  • Organization - Organization management, settings, and member administration
  • Guest - Guest access, invitations, and temporary user management
  • Room - Virtual room creation, management, and LiveKit integration
  • Calendar - Calendar integration, event synchronization, and scheduling
  • Pilots - Pilot program features and experimental functionality

For a complete overview of all endpoints, see the Endpoints Index.

System Architecture & Operations

In-depth documentation on backend systems, patterns, and best practices:

  • Logging Standards & Architecture - Comprehensive guide to the structured logging system, context propagation, attribute helpers, layer-specific functions, and best practices for consistent logging across the codebase

  • Metrics System - Complete documentation of the LiveKit metrics observability pipeline, including webhook processing, Prometheus integration, Grafana Cloud setup, and operational considerations

Development Guides

Resources for backend developers:

  • How to Write an Endpoint - Step-by-step guide for creating new API endpoints following established patterns and conventions

  • Avatar Update Flow - Detailed documentation of the avatar upload and update process, including file handling and storage

🏗️ Architecture Overview

The Qubital backend is built with:

  • Language: Go
  • Framework: Gin (HTTP routing)
  • Database: PostgreSQL
  • Real-time Communication: LiveKit Cloud
  • Authentication: WorkOS
  • Observability: Grafana Cloud (metrics), Better Stack (logs)
  • Cloud Platform: Google Cloud Run

📋 Common Patterns

Error Responses

All error responses follow a consistent structure with appropriate HTTP status codes and descriptive error messages. See individual endpoint documentation for specific error cases.

Logging

The backend uses structured logging with log/slog. Always use context-aware logging functions (*Ctx) and attribute helpers. See Logging Standards for complete details.

Request Tracing

Every request is assigned a trace_id and request_id for correlation across logs and metrics. These are automatically propagated through the request context.

Multi-Tenant Isolation

All resources are scoped to organizations (org_id). The authentication middleware enriches the request context with organization information after token validation.