# 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"`. |