37 lines
2.2 KiB
Markdown
37 lines
2.2 KiB
Markdown
# 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) |