35 lines
2.1 KiB
Markdown
35 lines
2.1 KiB
Markdown
# 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"`. |
|