Service Extension
Overview
Service Extension in Oblax lets you add custom backend logic beyond what the standard modules provide. While modules like Forms and Bookmarks handle common CRUD patterns, service extension gives you the tools to build domain-specific microservices, custom API endpoints, and automated workflows that plug directly into the platform’s infrastructure.
Service extension is powered by the obxfw CLI — a code-generation tool that scaffolds shared packages and microservices from declarative JSON configuration. You define your domain model, persistence layer, and service type in a config file, and obxfw generates production-ready Go source files.
When to Use Service Extension
Use service extension when you need:
- Custom domain logic that does not fit the standard module patterns
- A dedicated microservice for a specific business domain
- Custom API endpoints that proxy to downstream gRPC services
- Async consumers that process messages from RabbitMQ
- Shared domain libraries used across multiple services
Package and Service Types
Packages
A package is a reusable domain library that lives under pkg/go/<name>. It defines the domain model struct, service and persistence interfaces, and a gRPC client. Packages do not contain a main function — they are imported by services.
cd pkg/go
obxfw package init widgetThis creates a package directory with an obx_package.json config file. Edit the config to define your fields, persistence targets, and gRPC settings, then build:
cd widget
obxfw package buildServices
A service is a standalone microservice with a main package. Three types are supported:
| Type | Flag | Purpose |
|---|---|---|
| REST | --rest | BFF (Backend for Frontend) services that expose a Fiber HTTP API and proxy to gRPC DOM services |
| gRPC | --grpc | DOM (Domain) services that implement business logic and own a persistence layer |
| Async | --async | RabbitMQ consumer services that process messages and call downstream gRPC services |
cd services
obxfw service init widget --rest
obxfw service init widget --grpc
obxfw service init widget --asyncGenerated Files
Package Build Output
| File | Description |
|---|---|
<name>.go | Domain model with struct, interfaces, constructors, and validators |
service.go | Concrete service implementation delegating to a persistence store |
persistence.sql.go | MySQL persistence with CRUD operations (conditional) |
persistence.redis.go | Redis persistence with JSON-serialized key-value storage (conditional) |
client.grpc.go | gRPC client connecting to the downstream DOM service |
schema.hcl | Atlas HCL schema for the MySQL table (conditional) |
smthn.proto | Protobuf 3 definition for the gRPC service |
REST Service Build Output
| File | Description |
|---|---|
main.go | Fiber application entry point with route registration |
handlers/handler.go | Handler struct with gRPC client fields |
handlers/<package_name>.go | Per-remote CRUD handler methods |
gRPC Service Build Output
| File | Description |
|---|---|
main.go | Entry point with gRPC server and RabbitMQ subscriber |
handlers/handler.go | Handler implementing the full gRPC interface |
handlers/<name>.go | gRPC handler methods for all CRUD operations |
handlers/async.go | RabbitMQ message handler for rollback operations |
Where to next
| Section | Description |
|---|---|
| Modules | Understand the standard modules before building custom services |
| Flux Events and Scripts | Use event-driven scripts as an alternative to custom services |
| Storage | Handle file uploads and generated content in custom services |