backend-data-contracts

This repository is the single source of truth for all Protocol Buffer (Protobuf) schema definitions used across the Owlboard Rail Ingress and Processing microservices. It follows a Contract-First approach, where language-specific code (Go, TypeScript) is generated and distributed via private registries.

Purpose

The Protobuf files defined here serve as the immutable data contract for:

1. Ingress Logic: Ensuring the Node.js and Go inregrate properly by sharing types.
2. Message Payloads: Defining messages for cross-service communication.
3. Persistence: Defining the expected structure of documents in MongoDB for the Go processing services.

Directory Structure

Path	Description	Contents
proto/	Source of Truth. Contains the Protobuf schema definitions.	rail_backend/v1/*.proto
buf.yaml	Workspace Config. Defines linting and breaking change rules (Buf v2).	Workspace settings
buf.gen.yaml	Generation Config. Defines how Go and TS code is built.	Plugin & Managed Mode settings
gen/	Transient Output. Generated code resides here during CI/CD.	.pb.go, .js, .d.ts (Git Ignored)

Code Generation and Publishing Workflow

The generation and release process is automated via Gitea Actions. It is triggered whenever a new SemVer tag (e.g., v1.0.0) is pushed to this repository.

1. Validation: buf lint ensures schemas follow best practices.
2. Generation: buf generate creates Go and TypeScript code using local plugins.
3. TS Release: Compiles .ts to .js and publishes to the Gitea NPM Registry as @owlboard/backend-data-contracts.
4. Go Release: Initializes a go.mod, zips the artifacts, and pushes them to the Gitea Go Package Registry.

To Consume the Contracts

1. Go Services

Since the package is hosted in the Gitea Package Registry, you must configure your environment to use the Gitea instance as a proxy.

Setup:

export GOPROXY=[https://git.fjla.uk/api/packages/owlboard/go,https://proxy.golang.org,direct](https://git.fjla.uk/api/packages/owlboard/go,https://proxy.golang.org,direct)