Code Style Guide

Practical coding standards for HeadlessX services, UI, and supporting runtimes.

by @saifyxpro

General principles

  • prefer small, explicit changes over broad rewrites
  • keep route contracts and UI states readable without guessing
  • update docs when behavior, routes, or environment requirements change

Backend

  • keep request validation close to route boundaries
  • preserve the shared SSE event flow: start, progress, result, error, done
  • avoid mixing queue-backed job behavior with inline request behavior unless the route explicitly needs both
  • never expose stored secrets back to clients

Frontend

  • prefer clear state transitions over hidden fallback logic
  • keep loading, empty, error, and success states explicit
  • align workbench patterns across scrapers when the experience is meant to feel shared

Service boundaries

HeadlessX spans multiple runtimes:

  • TypeScript in apps/api and apps/web
  • Python in apps/yt-engine
  • Go in apps/go-html-to-md-service

Keep each service idiomatic to its runtime, but keep the public contract consistent across the platform.

Documentation

  • write docs against the current repo state
  • do not leave duplicate pages that describe the same workflow differently
  • keep changelog history, but use task-focused guides for current behavior