The metaverse service is organized around domain slices with clear boundaries and shared infrastructure. Use this pattern when refactoring large services.
Layout#
domains/<domain>/application/— use cases/orchestrators (no HTTP concerns)domain/— entities/value objects/services with invariants and pure logicinfrastructure/— adapters (persistence, external APIs, caches, queues)__tests__/— domain + application tests for the slice
adapters/— transport adapters (HTTP/WebSocket/GraphQL) that delegate to application layerplugins/— cross-cutting Fastify plugins (auth, tracing, input validation)config/— config loaders and type-safe settingsshared/— shared utilities used across domains (no cross-domain coupling)__tests__/integration/— integration tests across adapters/domains
Migration Steps for Large Services#
- Slice domains: identify 3–7 bounded contexts (e.g., auth, billing,
content). Create
domains/<domain>/folders and move pure logic there first. - Extract application layer: wrap workflows/use-cases in
application/(no HTTP types). Keep handlers thin. - Adapter isolation: move HTTP/WebSocket handlers to
adapters/and map requests to application commands/queries. - Shared plugins: reuse
services/common/server-templateandservices/libmiddleware instead of per-domain middleware copies. - Testing: mirror structure—unit tests inside each domain; integration
tests under
__tests__/integration/hitting adapters. - Contracts: keep request/response/DTO types near adapters; domain models stay internal and are not exported to transports.
- Cross-domain communication: depend on interfaces, not implementations. Compose at the application layer; avoid direct imports between domain folders.
Adoption Targets#
- Start with large multi-team services (BFF, auth, content, conversation).
- Apply incrementally: move one domain at a time, keeping existing routes delegating to new application/domain functions.
- Maintain existing tests; add adapter tests as routes are re-homed.
Definition of Done for a Migrated Domain#
- Domain logic lives in
domains/<domain>/domain/. - Use-cases live in
domains/<domain>/application/. - HTTP adapters delegate to use-cases only.
- Cross-cutting middleware uses shared plugins; no duplicate setup code.
- Domain tests are colocated; integration tests cover adapters.