# 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:**
```bash
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)