Topologies
The NGSI-LD specification doesn't prescribe an architecture. It describes three prototypes, centralised, distributed and federated, expects real systems to mix them, and requires the API to serve all of them. Andromeda serves every one with the same binary. What changes from one topology to the next is how many brokers you run and what you register in them.
Choosing one
Start with a single broker and move on only when data has to stay where it is. Moving later costs little, because registering a source adds to what the broker answers with and leaves the entities it already holds alone.
Split entities is not a shape of its own. Every distributed, federated or hierarchical setup decides whether a source holds whole entities or only some attributes of entities that other sources also hold, and that choice sets how much work a query costs.
Side by side
Every Andromeda broker has a PostgreSQL server of its own, so a deployment needs as many databases as it runs brokers.
| Topology | Brokers | Where the data lives | Sources run by |
|---|---|---|---|
| Single broker | 1 | In the broker | No sources |
| Distributed | 1 | In the broker and the sources | You |
| Federated | 1, plus 1 per domain | In the domains | Other teams |
| Hierarchical | 1 per level and domain | Mostly at the lowest level | Each level's own team |
How brokers are joined
Every topology beyond a single broker is built from one thing, a registration. A registration tells a broker that another system holds some entities and attributes, and where to reach it. The broker keeps its registrations itself, so there is no separate registry to run. The Distributed guide shows how to write them, and Distributed operations describes what the broker does with them.
A broker that holds registrations forwards each request to the sources it matches and merges their answers with its own data. A source that fails becomes a warning on the answer, and the request still succeeds. The system at the other end needs nothing special. It serves the ordinary NGSI-LD API and doesn't have to be Andromeda.
The examples
Each topology page ends with an example deployment, a Docker Compose file you can run as it stands, followed by the requests that register the sources and query through them. The files follow the Docker page, with the same images, the same .env holding the database password and docker compose up -d to start. Where one file runs several brokers, a suffix names the domain, as in andromeda-parks, postgresql-parks and postgresql-parks-data. The highlighted lines hold the federation settings, and the stand-ins for your own services where a page has any.
The domains of the federated and hierarchical examples are meant to be independent, which is why each one keeps its own database. The examples publish no database port, and publish a broker's port only where a client outside Compose needs it. Security describes what to put in front of a broker that clients reach.
Everything else about a deployment, from sizing to TLS and the proxy in front, works the same in every topology. Choosing a setup goes through it, and the Deployment planner builds the configuration for one broker.