Handbook - Architecture - Extension boundaries

Adapters

Author your own storage, bridge, auth, or harness adapter.

On this page
On this page

CloudGrid keeps external dependencies behind typed ports and public contracts. Extend those ports without changing service ownership boundaries: the frontend still talks only to the BFF, the BFF still uses message bridge contracts, storage-write is still the only telemetry mutator, and storage-read is still the only telemetry reader.

Extension points

Extension pointv1 implementationBoundary
StorageSurrealDBinternal/adapters/<database>/ in storage-read and storage-write
Message bridgeNATS JetStreamBridge ports plus AsyncAPI message contracts
Auth providerGitHub, Google, Microsoft Entra IDBFF-owned browser session provider port
Eval harnesspuristajs/harnessHTTP contract called by the AI evaluation runner
Public API clientsTypeScript helpersPublic GraphQL only
diagram
CloudGrid services storage port bridge port auth port harness adapter (HTTP) SurrealDB NATS JetStream GitHub · Google · Entra ID puristajs/harness
Mermaid diagram rendered with beautiful-mermaid.

Read more

Contribution path

Start from the relevant spec and contract before writing code. If an extension needs new fields, routes, subjects, retry behavior, or error codes, update the source spec and machine-readable contract first.

Last updated .