HCS Mesh is a library-first distributed messaging platform for building durable publish-subscribe workflows with Hedera-inspired consensus semantics. The repository is organized as reusable TypeScript packages plus a thin runnable stack that proves the packages in a realistic local deployment.
Version 0.1.x is intentionally honest about scope. It ships a durable platform-api, a background mirror-worker, an example admin dashboard, PostgreSQL-backed replay and checkpoint state, and a strict mock Hedera provider abstraction. It does not pretend that unimplemented platform features are production-ready.
| Area | Status in v0.1.x |
|---|---|
| Runtime topology | Stable for local and portfolio use |
| Storage model | PostgreSQL is the source of truth |
| Streaming transport | SSE only |
| Delivery model | At-least-once with idempotent publish handling |
| Hedera integration | Mock provider only |
| Authentication | JWT with scope enforcement |
| Operations | Health, readiness, metrics, OpenAPI, Compose boot |
Most messaging demos stop at toy HTTP handlers or overstate what a prototype actually guarantees. HCS Mesh takes the opposite approach:
- shared packages own the real logic, not service entrypoints
- persisted state backs replay, checkpoints, mirror status, and idempotency
- public APIs are explicit and documented
- unsupported features stay out of the stable surface until they exist
That makes the repository useful both as a portfolio-quality systems project and as a clean starting point for deeper Hedera integration work.
flowchart LR
Client[Clients and Dashboard] --> Nginx[Nginx]
Nginx --> API[platform-api]
API --> PG[(PostgreSQL)]
API --> Redis[(Redis rate limiting)]
API --> Provider[Mock Hedera Provider]
Worker[mirror-worker] --> Provider
Worker --> PG
Dashboard[admin-dashboard] --> API
Prometheus --> API
Prometheus --> Worker
Grafana --> Prometheus
platform-apiexposes the stable public API for auth, topics, publish, replay, subscriptions, checkpoints, admin snapshot, health, metrics, and OpenAPI.mirror-workerpolls the provider mirror surface, records mirror progress, and updates read-model status.admin-dashboardis an example application that consumes only documented public APIs.
packages/contractscontains stable HTTP DTOs and wire contracts.packages/corecontains domain models, use cases, auth, ports, errors, and delivery semantics.packages/http-apicontains Fastify route registration, schemas, auth middleware, error mapping, and OpenAPI generation.packages/persistence-postgrescontains durable repositories and SQL migrations.packages/persistence-memorycontains test-only in-memory adapters.packages/hedera-portdefines the provider contract.packages/hedera-mockimplements the mock consensus and mirror provider.
More detail is available in docs/architecture.md and docs/design-notes.md.
- Durable topics, canonical messages, checkpoints, audit events, and mirror state in PostgreSQL
- Replay by sequence number
- Replay by consensus timestamp
- Idempotent publish handling keyed by topic and idempotency key
- Scope-protected JWT authentication for mutating and admin routes
- SSE topic streaming with at-least-once delivery
- OpenAPI-backed request and response validation
- Health, readiness, metrics, and basic benchmark tooling
- Zero-touch local boot with migrations through Docker Compose
These items are not part of the stable implemented surface in 0.1.x:
- real Hedera SDK integration
- OAuth, RBAC, and API key management
- HTS token gating and NFT-based permissions
- JSON-RPC relay flows
- WebSocket streaming
- dead-letter queues and retry queues
- exactly-once delivery claims
They belong in roadmap or design documentation until they are implemented.
Public routes exposed by platform-api:
POST /v1/auth/tokenPOST /v1/auth/verifyGET /v1/topicsPOST /v1/topicsGET /v1/topics/:topicIdPOST /v1/topics/:topicId/messagesGET /v1/topics/:topicId/messagesPOST /v1/subscriptionsGET /v1/subscriptions/:consumerGroup/checkpoints/:topicIdGET /v1/topics/:topicId/streamGET /v1/admin/snapshot
Operational endpoints:
GET /health/liveGET /health/readyGET /infoGET /metricsGET /docsGET /openapi.json
The full request and response reference lives in docs/api-reference.md.
- Docker with Compose support
- Node.js
22+for local non-container workflows - npm
10+
docker compose up --buildThe default stack starts:
- PostgreSQL
- Redis
- one-shot migrator
platform-apimirror-workeradmin-dashboard- Nginx
- Prometheus
- Grafana
| Surface | URL |
|---|---|
| Dashboard | http://localhost:8080 |
| API | http://localhost:4111 |
| OpenAPI UI | http://localhost:8080/docs/ |
| OpenAPI JSON | http://localhost:4111/openapi.json |
| Prometheus | http://localhost:9090 |
| Grafana | http://localhost:3001 |
Local Compose enables ALLOW_INSECURE_TOKEN_ISSUANCE=true so the dashboard, smoke test, and API examples work without external identity infrastructure.
This route is for bootstrap and demo use only. Real deployments should:
- set
ALLOW_INSECURE_TOKEN_ISSUANCE=false - provide a real
JWT_SECRET - issue tokens from an external identity provider
Issue a bootstrap token:
curl -X POST http://localhost:4111/v1/auth/token \
-H "content-type: application/json" \
-d '{
"subject":"local-admin",
"scopes":["admin:read","topics:read","topics:write","messages:read","messages:write"]
}'Create a topic:
curl -X POST http://localhost:4111/v1/topics \
-H "content-type: application/json" \
-H "authorization: Bearer <token>" \
-d '{
"name":"orders",
"acl":{"publishers":["checkout"],"subscribers":["orders-projection"]}
}'Publish a message:
curl -X POST http://localhost:4111/v1/topics/orders/messages \
-H "content-type: application/json" \
-H "authorization: Bearer <token>" \
-d '{
"publisherId":"checkout",
"idempotencyKey":"order-123-created",
"payload":{"orderId":"123","status":"CREATED"}
}'Replay persisted messages:
curl "http://localhost:4111/v1/topics/orders/messages?afterSequence=0&consumerGroup=orders-projection" \
-H "authorization: Bearer <token>"Install dependencies:
npm installCommon commands:
| Command | Purpose |
|---|---|
npm run build |
Build all packages and apps |
npm run typecheck |
Run TypeScript project-reference checks |
npm run lint |
Lint workspaces |
npm run test |
Run unit and integration tests |
npm run audit |
Run production dependency audit |
npm run benchmark |
Run the baseline publish and replay harness |
npm run smoke |
Exercise the Compose stack end to end |
npm run migrate |
Apply PostgreSQL schema migrations |
- PostgreSQL is the only system of record.
- Redis is used only for rate limiting when enabled.
- SSE is the only stable streaming transport in v1.
- Readiness checks cover PostgreSQL, Redis when configured, and provider readiness.
- The mirror path is modeled separately so provider lag and replay behavior remain observable.
The deployment model and environment variables are documented in docs/deployment.md.
- docs/architecture.md
- docs/api-reference.md
- docs/deployment.md
- docs/design-notes.md
- docs/benchmarks.md
- docs/security-notes.md
The repository is designed to meet a professional open-source baseline for a pre-1.0 infrastructure project:
- typed package boundaries with TypeScript project references
- durable persistence for core messaging paths
- schema-validated HTTP APIs
- scope-enforced authentication
- automated tests, smoke checks, and build verification
- docs that distinguish implemented behavior from roadmap intent
The next meaningful production steps are:
- add a real Hedera adapter behind
@hcs-mesh/hedera-port - replace bootstrap token issuance with a real identity flow
- expand load, chaos, and mirror-lag testing
- deepen operational dashboards and tracing
- introduce advanced authorization models only when fully implemented