Building Block View
Static structure and decomposition of the system
This section describes the static decomposition of the Fr[ae]ym system into building blocks.
System as a whole
Fr[ae]ym is a multi-service system. The main building blocks visible to users are the six microservices and the client SDKs.
Black-box (external view):
- Sync — Distributed locking (read/write, hierarchical, multi-tenant, per-application).
- Streams — Event sourcing and messaging; publish, subscribe, query events; consumer groups.
- Projections — Schema-defined projections over events; GraphQL API.
- CRUD — Event-sourced CRUD with GraphQL API; file storage via S3-compatible storage.
- Auth — User management, authentication and authorization (OAuth2-like); users, roles, permissions; multi-tenancy.
- Deployments — Schema deployment lifecycle (create, activate, confirm, rollback) for Projections and CRUD; updates Auth permissions.
SDKs (this repo):
- Go:
sdk/go/sync,sdk/go/streams,sdk/go/projections,sdk/go/crud,sdk/go/auth,sdk/go/deployments. - JavaScript:
sdk/js/sync,sdk/js/streams,sdk/js/projections,sdk/js/crud,sdk/js/auth,sdk/js/deployments; plussdk/js/graphql,sdk/js/react,sdk/js/protowhere used.
Repository layout
Decomposition of the repository:
| Building block | Path | Responsibility |
|---|---|---|
| Sync service | cmd/sync, service/sync/ | Entrypoint and Sync implementation (infrastructure, use cases, controllers). |
| Streams service | cmd/streams, service/streams/ | Event storage, subscriptions, routing, GraphQL/gRPC. |
| Projections service | cmd/projections, service/projections/ | Projection definitions, transformation, GraphQL API. |
| CRUD service | cmd/crud, service/crud/ | CRUD types, mutations, files (S3-compatible storage), GraphQL API. |
| Auth service | cmd/auth, service/auth/ | Users, sessions, tokens, roles, permissions; GraphQL management API. |
| Deployments service | cmd/deployments, service/deployments/ | Schema validation, deployment state, application to Projections/CRUD. |
| Internal shared code | internal/ | DB pool, migrations, GraphQL wiring, Fiber, utilities (image, JWT, etc.). |
| SDKs | sdk/*language*/ | SDK libraries for each service. |
| Helm charts | charts/ | Kubernetes deployment and configuration. |
| Docs | docs/ | Next.js + Fumadocs site; content in docs/content/docs/. |
| E2E tests | e2e-tests/ | End-to-end tests (e.g. streams, projections, auth). |
Service-internal structure
Each service follows a similar layered / hexagonal style:
cmd/<service>/— Command entry points for all services.service/<name>/infrastructure/— Router (HTTP/gRPC), datastore (Postgres, migrations), ...service/<name>/controller/— GraphQL, gRPC (and other) entrypoints.service/<name>/service/— Application logic.service/<name>/repository/— Data access.service/<name>/domain/— Domain models and events.service/<name>/dto/— Data transfer objects.service/<name>/usecase/— Use case orchestration.
Dependency injection is done with Wire (wire.go, wire_gen.go).
Dependencies between building blocks
TODO: Add a chart that visualizes the data flow between building blocks.