BaryoDev / BaryoDev/barakoCMS

Services: starters, client libraries and a tutorial, so a message handling service takes 15 minutes

Open
#834 0 comments 0 reactions 0 assignees View on GitHub
module
Dominant language
C#
Stars
6
Forks
7
Avg merge
4h 42m
Merged PRs (30d)
307

Description

Arnel, 14 September 2026: "how easy is it to set up the services that receive messages? We must teach them or give them starters." A developer should have a working service, receiving a message from a workflow and writing a result back, in under 15 minutes, without reading the transport code.

## Change

**Starters.**
- `dotnet new barakocms-service -n Acme.Payroll` in `BarakoCMS.Templates`, beside `barakocms-module`: a small ASP.NET Core worker with one handler, `pay.compute`, that verifies the message signature, computes, and posts a journal entry back, plus tests that run against `BarakoCMS.Testing`.
- A TypeScript starter from `create-barako-app --service`, with the same handler shape for Node.
- Both include a `compose.yml` that brings up barakoCMS, Postgres and the service, with a seeded workflow that sends the first message, so `docker compose up` shows the whole loop.

**Client libraries**, one each for .NET and TypeScript, so a handler is the only code a developer writes:
- Verify the message signature and timestamp, and drop a message id already handled.
- Reply to a waiting run (#831 phase 2) or write back through the API with `Idempotency-Key` set to the message id.
- Send heartbeats and register the service on start (the services registry issue).
- Typed messages from a message type's schema.

**Teaching.**
- A tutorial in docs: "Night differential and overtime as a service", from `dotnet new` to a teacher's time out producing a journal entry and an email.
- A page on when to use a service versus a workflow step versus a module: a rule inside the write is a module; a calculation with rules the client owns is a service; formatting and sending is a workflow.
- A conformance test pack a service can run in CI: signature, duplicates, retries, timeout reply.

## Done when

- From a fresh machine with Docker, the tutorial produces a journal entry from a time out in under 15 minutes, checked by running it in CI.
- A handler written with the library passes the conformance pack, and one that ignores duplicate message ids fails it.

## Where it lives

No core change. The service starter ships in the `BarakoCMS.Templates` package beside `barakocms-module`, and the client libraries are their own packages.

Contributor guide

Open the contributing guide

Research direction

Start in the BarakoCMS.Templates package beside barakocms-module, then review the planned TypeScript starter, separate client-library packages, tutorial docs, and conformance test pack. Verify the end-to-end compose workflow, handler behavior, duplicate handling, retries, timeout replies, and CI tutorial run. Done means the fresh-machine tutorial completes in under 15 minutes and compliant handlers pass while duplicate-ignoring handlers fail.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, docker, nodejs, postgresql, typescript
Domain
api, backend, devops, documentation, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.