data-contracts

This repository is the single source of truth for all Protocol Buffer (Protobuf) schema definitions used across the Rail Ingress and Processing microservices.

Purpose

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

1. Message Queue Payloads: Defining messages pushed to the Artemis queue (Go Process Service consumption).
2. Database Schemas: Defining the expected structure of documents in MongoDB (Go Process and TypeScript API service consumption).
3. Cross-Service Communication: Ensuring type-safe data exchange between all polyglot services (Go, TypeScript).

Directory Structure and Artifacts

Path	Description	Contents
protos/rail/v1/	Source Code. Contains all source .proto files. Only these files reside on the main branch.	.proto files
ts/	Generated TypeScript/JavaScript code. Used as the root for the NPM package publish. Not committed to Git.	package.json, generated .js, .d.ts
go.mod	Defines the Go Module path: git.fjla.uk/owlboard/backend-data-contracts.	Go Module definition

Code Generation and Publishing Workflow (Gitea Action)

The generation process is automated via a Gitea Action (.gitea/workflows/generate_contracts.yml), which runs when a change is pushed to a source .proto file.

The action performs the following steps:

1. Generates all Go and TypeScript/JavaScript artifacts.
2. Go Artifacts: Commits the generated *.pb.go files to a new Git tag (e.g., v1.0.1), ensuring the main branch remains clean.
3. TypeScript Artifacts: Packages the generated files and publishes the corresponding version (e.g., 1.0.1) to the internal NPM registry.

To Consume the Contract:

Language	Artifact	Consumption Method
Go	Source Code (*.pb.go)	Requires a Git Tag. Update your service's go.mod file to reference the desired tag: git.fjla.uk/owlboard/backend-data-contracts v1.0.1.
TypeScript	NPM Package	Update the version in your package.json file and install: "@owlboard/contracts": "1.0.1".