OwlBoard/backend-data-contracts
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
Fred Boniface
2026-01-07 18:46:15 +00:00
parent 7fe1be9b48
commit f9463f3d29
1 changed files with 20 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
README.md
View File

@@ -1,32 +1,18 @@
# 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.
This repository is the single source of truth for all schema definitions used across the Owlboard backend communication and storage services. Language specific types are generated here and published to the Gitea package repository linked to the repo.
## 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**) |
| Path | Description |
| :--- | :--- |
| `schemas` | JSON Schema files organised into clear subfolders |
| `scripts` | Workflow Scripts |
## 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
@@ -34,4 +20,18 @@ Since the package is hosted in the Gitea Package Registry, you must configure yo
**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)
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)
```
### 2. Typescript Services
You will need to configure .npmrc in your projects root directory to point to the correct repo:
```bash
@owlboard:registry=https://git.fjla.uk/api/packages/OwlBoard/npm/
```
Then you can install as usual:
```bash
npm install @owlboard/backend-data-contracts@0.1.0
```