The Federated Masterclass

Go beyond simple multi-tenancy. Orchestrate a global empire of data silos with real-time synchronization and parallel read aggregation.

Deep Dive: The Dealership Scenario

Imagine a car—Car ABC—owned by Customer X. Customer X regularly visits Dealership A (Home), but today they are 1,000 miles away and visit Dealership B (Guest) for an emergency repair.

Without Federation

Dealership B creates a record. Dealership A knows nothing about it. When the car returns home, the service history is fragmented. The "Single Source of Truth" is broken.

With GO-DUCK Federation

Dealership B saves the record. GO-DUCK automatically broadcasts this to Dealership A in the background. Both databases now hold the complete, unified history of the car.

Architectural Control: The Annotations

1. Standard Multi-Tenancy

entity DealershipSettings { ... }

Behavior: Stored in the tenant's primary database only. No synchronization. High performance, zero overhead.

Use Case: Data that belongs to a specific site, like internal employee lists or site colors.

2. Federated Multi-Tenancy

@Federated entity ServiceHistory { ... }

Behavior: Triggers the Saga/Outbox Engine. Writes are broadcast to all authorized silos. Reads are aggregated in parallel.

Use Case: Critical data that must be "Everywhere," like car health, global inventory, or customer profiles.

Triple-Identity Registry: Opaque Decoupling

To prevent ID Enumeration and protect physical infrastructure paths, GO-DUCK implements a sophisticated 3-layer identity registry. This ensures that guessable database names are never leaked to the client.

1

Identity Layer

Keycloak Realm Role (e.g. dealer_tokyo). This is the source of truth for authorization.

2

Opaque Layer

Randomly generated UUID (e.g. bc72-a180...) exposed via the X-Tenant-ID header.

3

Physical Layer

The actual database name (e.g. dealership_silo_japan_prod). Only the server knows this link.

The Dual-Path Orchestrator

GO-DUCK doesn't force you into one model. Our generated middleware and controllers detect your GDL annotations and switch behavior in real-time.

01

Silo-Connection-Cache

Prevents connection exhaustion across 100+ silos using a singleton-based cache. DB/Mongo clients are lazily initialized and kept warm.

02

Parallel Read Harvest

When you query a @Federated entity, GO-DUCK launches simultaneous Go-routines to every database you own, stitching the global picture together in milliseconds.

03

Transactional Atomic Broadcast

A write to one silo is a write to all. Using the Outbox pattern, we guarantee that even if Dealership A is offline, Dealership B's updates will eventually arrive safely.

04

Precision Harvesting

Pass a comma-separated list of UUIDs in the X-Tenant-ID header. The Harvester reduces its fan-out to ONLY these silos for surgical efficiency.

Elite FAQ

What if I assigned multiple DBs to a role but forgot @Federated?

GO-DUCK will only use your Primary/Default database. It will not harvest data from the other assigned silos. You must use the annotation to unlock aggregation.

Is there a performance hit for @Federated?

Reads use parallel goroutines, making them extremely fast even across silos. Writes include one extra row in the Outbox table—a small price for global consistency.