majiayu000 Skill: Create BFF Layer
This skill teaches you how to create a Backend for Frontend (BFF) layer following architectural patterns. A BFF is a client-specific adapter that aggregates data from multiple bounded contexts and shapes responses for specific client surfaces.
A properly designed BFF enables clean separation between domain APIs and client needs. It aggregates calls, transforms responses, and handles client-specific concerns. The BFF remains stateless and never contains domain logic - it lives in Presentation and Adapter layers only.
Prerequisites
- Understanding of Clean Architecture and DDD concepts
- Multiple bounded contexts already implemented with public APIs
- Clear understanding of what the client surface needs
Overview
You will: define client requirements, create bounded context clients, implement BFF aggregation, add response shaping, implement caching, create error handling, and test independently.
Step 1: Define Client Requirements
Create an OpenAPI contract that specifies the aggregated endpoints.
# contracts/openapi.yaml
openapi: 3.0.3
info:
title: Mobile Home BFF API
version: 1.0.0
paths:
/home/summary:
get:
summary: Get home energy summary
operationId: getHomeSummary
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/HomeSummaryResponse'
components:
schemas:
HomeSummaryResponse:
type: object
properties:
facility_name:
type: string
total_assets:
type: integer
current_consumption_kw:
type: number
The contract defines client-specific shapes that aggregate data from multiple bounded contexts.
Step 2: Create Backend Service Clients
Create client interfaces for each bounded context your BFF will call.
// clients/interfaces
// FacilityClient communicates with the Facility bounded context.
INTERFACE FacilityClient
METHOD GetUserFacility(ctx: Context, userID: String) RETURNS Result<Facility, Error>
END INTERFACE
// AssetClient communicates with the Asset bounded context.
INTERFACE AssetClient
METHOD GetFacilityAssets(ctx: Context, facilityID: String) RETURNS Result<List<Asset>, Error>
END INTERFACE
// IntelligenceClient communicates with the Intelligence bounded context.
INTERFACE IntelligenceClient
METHOD GetCurrentSchedule(ctx: Context, facilityID: String) RETURNS Result<Schedule, Error>
END INTERFACE
TYPE Facility
id: String
name: String
address: String
END TYPE
TYPE Asset
id: String
name: String
state: String
currentLoadKW: Float
END TYPE
TYPE Schedule
nextActionTime: String
nextActionDesc: String
expectedSavingsKWh: Float
END TYPE
// clients/facility_client
TYPE HTTPFacilityClient
baseURL: String
httpClient: HttpClient
END TYPE
CONSTRUCTOR NewHTTPFacilityClient(baseURL: String, client: HttpClient) RETURNS HTTPFacilityClient
RETURN HTTPFacilityClient{baseURL: baseURL, httpClient: client}
END CONSTRUCTOR
METHOD HTTPFacilityClient.GetUserFacility(ctx: Context, userID: String) RETURNS Result<Facility, Error>
url = this.baseURL + "/users/" + userID + "/facility"
request = NewHttpRequest(ctx, "GET", url)
response = this.httpClient.Do(request)
IF response.IsError() THEN
RETURN Error("failed to call facility service: " + response.Error())
END IF
DEFER response.Body.Close()
IF response.StatusCode == 404 THEN
RETURN Error(ErrFacilityNotFound)
END IF
facility = Deserialize<Facility>(response.Body)
RETURN Ok(facility.Value())
END METHOD
Each client calls a single bounded context's public API. The BFF never accesses databases directly.
Step 3: Implement BFF Handler with Aggregation
Create the BFF handler that orchestrates calls to multiple bounded contexts.
// handlers/dto
// HomeSummaryResponse is the client-specific response shape.
TYPE HomeSummaryResponse
facilityName: String
totalAssets: Integer
assetsOnline: Integer
currentConsumptionKW: Float
nextOptimization: OptimizationPreview // Optional
lastUpdated: DateTime
END TYPE
TYPE OptimizationPreview
scheduledAt: DateTime
action: String
expectedSavingsKWh: Float
END TYPE
// handlers/home_bff
// HomeBFFHandler aggregates data from multiple bounded contexts.
// It contains NO domain logic - only orchestration and response shaping.
TYPE HomeBFFHandler
facilityClient: FacilityClient
assetClient: AssetClient
intelligenceClient: IntelligenceClient
END TYPE
CONSTRUCTOR NewHomeBFFHandler(
f: FacilityClient,
a: AssetClient,
i: IntelligenceClient
) RETURNS HomeBFFHandler
RETURN HomeBFFHandler{
facilityClient: f,
assetClient: a,
intelligenceClient: i
}
END CONSTRUCTOR
// GetHomeSummary aggregates data - pure orchestration, no business rules.
METHOD HomeBFFHandler.GetHomeSummary(ctx: Context, userID: String) RETURNS Result<HomeSummaryResponse, Error>
// Call Facility bounded context
facility = this.facilityClient.GetUserFacility(ctx, userID)
IF facility.IsError() THEN
RETURN Error("failed to get facility: " + facility.Error())
END IF
// Call Asset bounded context
assets = this.assetClient.GetFacilityAssets(ctx, facility.Value().id)
IF assets.IsError() THEN
RETURN Error("failed to get assets: " + assets.Error())
END IF
// Call Intelligence bounded context (optional - don't fail if unavailable)
schedule = this.intelligenceClient.GetCurrentSchedule(ctx, facility.Value().id)
// Ignore error for optional data
// Aggregate and shape response - NO business logic here
RETURN Ok(this.shapeResponse(facility.Value(), assets.Value(), schedule.ValueOrNil()))
END METHOD
METHOD HomeBFFHandler.shapeResponse(
facility: Facility,
assets: List<Asset>,
schedule: Schedule
) RETURNS HomeSummaryResponse
assetsOnline = 0
totalConsumption = 0.0
FOR EACH asset IN assets DO
IF asset.state == "online" THEN
assetsOnline = assetsOnline + 1
END IF
totalConsumption = totalConsumption + asset.currentLoadKW
END FOR
response = HomeSummaryResponse{
facilityName: facility.name,
totalAssets: assets.Length(),
assetsOnline: assetsOnline,
currentConsumptionKW: totalConsumption,
lastUpdated: DateTime.Now().ToUTC()
}
IF schedule != NULL THEN
scheduledAt = DateTime.Parse(schedule.nextActionTime)
response.nextOptimization = OptimizationPreview{
scheduledAt: scheduledAt,
action: schedule.nextActionDesc,
expectedSavingsKWh: schedule.expectedSavingsKWh
}
END IF
RETURN response
END METHOD
The handler only orchestrates and shapes. No if asset.Load > threshold style decisions.
Step 4: Add Optional Caching
For performance, add caching. This is technical caching, not domain state storage.
// cache/cache
TYPE Cache
client: CacheClient
ttl: Duration
END TYPE
CONSTRUCTOR NewCache(client: CacheClient, ttl: Duration) RETURNS Cache
RETURN Cache{client: client, ttl: ttl}
END CONSTRUCTOR
METHOD Cache.Get(ctx: Context, key: String, dest: Any) RETURNS Result<Any, Error>
val = this.client.Get(ctx, key)
IF val.IsError() THEN
RETURN val.Error()
END IF
RETURN Deserialize(val.Value(), dest)
END METHOD
METHOD Cache.Set(ctx: Context, key: String, value: Any) RETURNS Result<Void, Error>
data = Serialize(value)
RETURN this.client.Set(ctx, key, data, this.ttl)
END METHOD
FUNCTION HomeSummaryKey(userID: String) RETURNS String
RETURN "bff:home:summary:" + userID
END FUNCTION
Step 5: Implement Error Handling
Translate domain errors to client-friendly responses.
// clients/errors
CONSTANT ErrFacilityNotFound = "facility not found"
CONSTANT ErrServiceUnavailable = "service unavailable"
CONSTANT ErrUnauthorized = "unauthorized"
// handlers/errors
TYPE ErrorResponse
error: String
code: String
message: String
END TYPE
FUNCTION MapErrorToHTTPStatus(err: Error) RETURNS Integer
SWITCH err
CASE ErrFacilityNotFound:
RETURN 404
CASE ErrUnauthorized:
RETURN 401
DEFAULT:
RETURN 500
END SWITCH
END FUNCTION
FUNCTION MapErrorToResponse(err: Error) RETURNS ErrorResponse
SWITCH err
CASE ErrFacilityNotFound:
RETURN ErrorResponse{
error: "not_found",
code: "FACILITY_NOT_FOUND",
message: "No facility associated with your account"
}
DEFAULT:
RETURN ErrorResponse{
error: "internal_error",
code: "INTERNAL_ERROR",
message: "Something went wrong"
}
END SWITCH
END FUNCTION
Step 6: Create Entry Point
Set up dependency injection in the handler.
// cmd/api/main
GLOBAL bffHandler: HomeBFFHandler
FUNCTION init()
httpClient = NewHttpClient(timeout: 10 seconds)
bffHandler = NewHomeBFFHandler(
NewHTTPFacilityClient(GetEnv("FACILITY_SERVICE_URL"), httpClient),
NewHTTPAssetClient(GetEnv("ASSET_SERVICE_URL"), httpClient),
NewHTTPIntelligenceClient(GetEnv("INTELLIGENCE_SERVICE_URL"), httpClient)
)
END FUNCTION
FUNCTION main()
StartServer(handle)
END FUNCTION
FUNCTION handle(ctx: Context, request: HttpRequest) RETURNS HttpResponse
userID = request.Context.Authorizer["sub"]
IF userID == NULL THEN
RETURN HttpResponse{StatusCode: 401}
END IF
response = bffHandler.GetHomeSummary(ctx, userID)
IF response.IsError() THEN
RETURN HttpResponse{StatusCode: MapErrorToHTTPStatus(response.Error())}
END IF
RETURN JsonResponse(200, response.Value())
END FUNCTION
Step 7: Test BFF Independently
Create tests that mock the bounded context clients.
// handlers/home_bff_test
TYPE MockFacilityClient
mock: Mock
END TYPE
METHOD MockFacilityClient.GetUserFacility(ctx: Context, userID: String) RETURNS Result<Facility, Error>
args = this.mock.Called(ctx, userID)
IF args.Get(0) == NULL THEN
RETURN Error(args.Error(1))
END IF
RETURN Ok(args.Get(0) AS Facility)
END METHOD
TYPE MockAssetClient
mock: Mock
END TYPE
METHOD MockAssetClient.GetFacilityAssets(ctx: Context, facilityID: String) RETURNS Result<List<Asset>, Error>
args = this.mock.Called(ctx, facilityID)
IF args.Get(0) == NULL THEN
RETURN Error(args.Error(1))
END IF
RETURN Ok(args.Get(0) AS List<Asset>)
END METHOD
TYPE MockIntelligenceClient
mock: Mock
END TYPE
METHOD MockIntelligenceClient.GetCurrentSchedule(ctx: Context, facilityID: String) RETURNS Result<Schedule, Error>
args = this.mock.Called(ctx, facilityID)
IF args.Get(0) == NULL THEN
RETURN Error(args.Error(1))
END IF
RETURN Ok(args.Get(0) AS Schedule)
END METHOD
TEST GetHomeSummary_Success
ctx = NewContext()
facilityMock = NEW MockFacilityClient()
assetMock = NEW MockAssetClient()
intelligenceMock = NEW MockIntelligenceClient()
facilityMock.mock.On("GetUserFacility", ctx, "user-123").Return(
Facility{id: "f-1", name: "Home"},
NULL
)
assetMock.mock.On("GetFacilityAssets", ctx, "f-1").Return(
[
Asset{id: "a-1", state: "online", currentLoadKW: 5.0},
Asset{id: "a-2", state: "online", currentLoadKW: 7.5}
],
NULL
)
intelligenceMock.mock.On("GetCurrentSchedule", ctx, "f-1").Return(
Schedule{nextActionDesc: "Charge"},
NULL
)
handler = NewHomeBFFHandler(facilityMock, assetMock, intelligenceMock)
response = handler.GetHomeSummary(ctx, "user-123")
ASSERT response.IsOk()
ASSERT response.Value().facilityName == "Home"
ASSERT response.Value().totalAssets == 2
ASSERT response.Value().currentConsumptionKW == 12.5
END TEST
TEST GetHomeSummary_FacilityNotFound
ctx = NewContext()
facilityMock = NEW MockFacilityClient()
assetMock = NEW MockAssetClient()
intelligenceMock = NEW MockIntelligenceClient()
facilityMock.mock.On("GetUserFacility", ctx, "unknown").Return(
NULL,
Error(ErrFacilityNotFound)
)
handler = NewHomeBFFHandler(facilityMock, assetMock, intelligenceMock)
response = handler.GetHomeSummary(ctx, "unknown")
ASSERT response.IsError()
ASSERT response.Error().Contains(ErrFacilityNotFound)
END TEST
Verification Checklist
After creating your BFF layer, verify:
- BFF has no domain logic (no business rules, no invariant checks)
- BFF only calls public bounded context APIs
- BFF does not access any database directly
- BFF is stateless (caching is for performance only)
- BFF does not emit domain events
- BFF does not own domain models (uses view DTOs only)
- Response shapes are client-specific, not domain shapes
- Error handling translates domain errors to client-friendly responses
- Each bounded context client is independently testable
- BFF handler can be tested with mocked clients
- OpenAPI contract matches implementation
- Caching has appropriate TTL and invalidation strategy