Services: starters, client libraries and a tutorial, so a message handling service takes 15 minutes
- 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
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