Vetrix Docs

Vetrix architecture

Internal-design reference for how the Vetrix platform is built. The pages here are implementation contracts — table and column names, endpoint shapes, Go accessors, and the rules each surface is written against — for readers reasoning about or changing the platform rather than operating a single feature.

Platform-wide references sit at this level; each subsystem keeps its own section below.

Platform-wide references

  • Naming doctrine: /merges canonical — Fixes /merges/** as the canonical merge-request route with /pulls/** kept only as a 308 redirect, and lists the wire-level identifiers that keep the older spelling.
  • Issue comment visibility — Defines the per-comment is_restricted model: which four caller classes may read a restricted comment, and the single accessor every surface routes the check through.
  • Code-search index operations — Architecture/internals reference for the code_search_index table and its outbox: how priming an empty index, surviving a default-branch rename, and the parked/stuck queue states work under the hood, with pointers to the operator runbooks that are authoritative for the procedures themselves.
  • Multi-agent token tracking — How per-agent Claude API usage is aggregated from local session transcripts into a per-run CSV and Markdown report attributed by ticket and stage.

Subsystems

  • CI/CD architecture — Indexes how a pipeline job is isolated, executed, retried and logged, and the gates, attestations and federated credentials that bound what a run may do.
  • Frontend architecture — Indexes the web client's interface conventions: the design-system tokens components build against and the alt-text contract for user-identity imagery.
  • Search architecture — Indexes the search data model: the ACL fields every document carries, the index mappings and query patterns, the actor-by-visibility permission matrix, and the deprecated legacy routes.
  • Security architecture — Indexes the deployment's security posture: pre-receive secret detection and rotation, the scanning backends and their findings surfaces, and the CI/CD execution threat model.