Skip to content

architecture.md

Latest commit

 

History

History
158 lines (115 loc) · 3.98 KB

architecture.md

File metadata and controls

158 lines (115 loc) · 3.98 KB
Raw

Architecture

Overview

HCS Mesh v1 is intentionally smaller than the original scaffold:

  • one public runtime: platform-api
  • one background runtime: mirror-worker
  • reusable packages for domain logic, persistence, provider contracts, and HTTP wiring

This keeps the system honest. There is no gateway forwarding to placeholder services, and there are no fake durability claims backed only by in-memory state.

Core Design Choices

PostgreSQL Is The Source Of Truth

Topics, messages, checkpoints, audit logs, and mirror state are persisted in PostgreSQL. Redis is used only for rate limiting when enabled.

Why:

  • it makes replay and checkpoint semantics durable
  • it keeps the v1 platform consistent with its docs
  • it reduces the architectural gap between local Compose and a real deployment

Mock Hedera Is A Provider, Not A Hidden Shortcut

The mock provider sits behind @hcs-mesh/hedera-port and is implemented by @hcs-mesh/hedera-mock.

Why:

  • the rest of the system depends on a provider contract, not on ad hoc sequence generation
  • a future testnet adapter can plug in without rewriting publish and mirror use cases
  • the repo stays honest that real Hedera integration is not shipped yet

Library-First Before Runtime-First

The shared packages hold the meaningful logic:

  • auth
  • domain validation
  • publish flow
  • replay flow
  • mirror polling
  • repository contracts
  • OpenAPI-backed route registration

The apps only compose those packages with concrete adapters.

Why:

  • reusable code is easier to test
  • runtime entrypoints stay thin and auditable
  • open-source contributors can reason about the behavior without tracing through many HTTP hops

Runtime Topology

flowchart LR
    User[Clients / Dashboard] --> Nginx[Nginx]
    Nginx --> API[platform-api]
    API --> PG[(PostgreSQL)]
    API --> Redis[(Redis)]
    Worker[mirror-worker] --> PG
    Worker --> Provider[Mock Hedera Provider]
    API --> Provider
    Dashboard[admin-dashboard] --> API
    Prometheus --> API
    Prometheus --> Worker
    Grafana --> Prometheus
Loading

Publish Flow

sequenceDiagram
    participant C as Client
    participant A as platform-api
    participant P as Mock Hedera Provider
    participant DB as PostgreSQL

    C->>A: POST /v1/topics/:topicId/messages
    A->>A: verify JWT + scopes
    A->>A: validate payload + rate limit + idempotency
    A->>P: publishMessage()
    P-->>A: sequence + topic sequence + consensus timestamp
    A->>DB: insert canonical message
    A-->>C: accepted message DTO
Loading

Replay Flow

sequenceDiagram
    participant C as Client
    participant A as platform-api
    participant DB as PostgreSQL

    C->>A: GET /v1/topics/:topicId/messages
    A->>A: verify JWT + scopes
    A->>DB: query persisted messages by sequence or consensus timestamp
    A->>DB: update checkpoint when consumerGroup is supplied
    A-->>C: ordered replay batch
Loading

Mirror Flow

sequenceDiagram
    participant W as mirror-worker
    participant P as Mock Hedera Provider
    participant DB as PostgreSQL

    W->>DB: read mirror_state
    W->>P: fetchMirrorEvents(afterSequence)
    P-->>W: ordered mirrored events
    W->>DB: mark messages mirrored
    W->>DB: update mirror_state
Loading

Delivery Semantics

The stable v1 surface supports:

  • monotonic sequence ordering
  • idempotent publish reuse when the same topic and idempotency key are reused
  • replay by sequence
  • replay by consensus timestamp
  • at-least-once SSE streaming

It does not claim:

  • exactly-once delivery
  • dead-letter queues
  • retry queues
  • WebSocket fan-out
  • HTS-enforced access control

Operational Surface

Both runtimes expose:

  • /health/live
  • /health/ready
  • /info
  • /metrics

platform-api also exposes:

  • /docs
  • /openapi.json

Extension Path

The cleanest next production steps are:

  1. swap the mock provider for a real Hedera adapter
  2. replace bootstrap token issuance with a real identity provider
  3. widen CI to run richer Postgres and Redis integration suites