# Team Topology _Star, mesh, hub-and-spoke. Pick the shape that matches your team._ ## Overview A Mothership deployment is a set of Motherships and peers connected to them. The specific shape — one Mothership or many, where they live, who connects to which — is what we call the topology. There is no single correct answer. The right topology depends on team size, geographic distribution, network policy, and how much operational work you are willing to absorb. This page walks through the three topologies we see most often, with ASCII diagrams and the decision criteria for each. ## Star Topology One Mothership. N peers. Every peer connects to the same Mothership. This is the default and the simplest. ```text +----------+ |Mothership| +----------+ / | \ / | \ / | \ +-----+ +-----+ +-----+ |peer | |peer | |peer | |alice| | bob | |carol| +-----+ +-----+ +-----+ | +-----+ |peer | | dan | +-----+ ``` ### When to use star - **Team size up to ~100 peers.** A single well-provisioned Mothership handles this without breathing hard. - **Single geographic region.** Everyone is on roughly the same continent; round-trip latency to the Mothership is under 100ms. - **Operational simplicity is valued.** One Mothership to monitor, one backup, one cert to rotate. ### Trade-offs - Single failure domain. If the Mothership host goes down, no new peers can join and team-wide state (zones, revocations) freezes. Existing peers keep working via [offline mode](/offline-mode) and direct peer-to-peer, but the team is partially degraded. - WAN-bound. A team distributed across three continents on a single Mothership will feel the latency on every control message. ### Hardware rule of thumb for star - 1–25 peers: any always-on machine. A Raspberry Pi 4 works. - 25–100 peers: 2 cores, 4 GB RAM, SSD. A small cloud VM or Mac mini. - Details in [scaling](/scaling-mothership). ## Mesh Topology (Federated Motherships) Multiple Motherships, peered with each other. Peers connect to whichever Mothership is closest. ```text +-----------+ +-----------+ |Mothership |<------------->|Mothership | | (NYC) | federated | (Berlin) | +-----------+ +-----------+ / | \ / | \ / | \ / | \ +---+ +---+ +---+ +---+ +---+ +---+ |NYC| |NYC| |NYC| |DE | |DE | |DE | +---+ +---+ +---+ +---+ +---+ +---+ +-----------+ |Mothership | |(Singapore)| +-----------+ / | \ +---+ +---+ +---+ |SG | |SG | |SG | +---+ +---+ +---+ (also peered with NYC and Berlin) ``` Each Mothership is authoritative for the peers connected to it, but all Motherships replicate team-wide state — peer list, zones, messages, intent log — to each other. To a peer in Singapore, a teammate in Berlin looks like a remote peer on a different branch of the same tree. ### How federation works Federation is just another Mothership running `join` against another Mothership. The second Mothership uses a special "federation" join token that grants it peer-of-peers rights. Concretely: ```bash # on the Berlin Mothership aura mothership join --url https://nyc.mothership.acme:7777 \ --token \ --as-mothership ``` After this handshake, NYC and Berlin replicate WALs bidirectionally. A push from a peer in NYC is fanned out to every Berlin peer via the Berlin Mothership, and vice versa. ### When to use mesh - **Global teams (3+ regions).** Every developer connects to a nearby Mothership; cross-region traffic is once-per-change between Motherships, not once-per-peer. - **Availability requirements.** Losing one Mothership degrades one region; the others keep signing tokens and serving their peers. - **Network segmentation.** You want to separate production and staging teams but keep them able to sync when appropriate. ### Trade-offs - More operational overhead. N Motherships to monitor, back up, and rotate. - Federation adds latency on cross-region events. A zone claim in Singapore is visible in NYC after one Mothership-to-Mothership hop. - Requires careful thought about which Mothership is authoritative for what. Conflicts between Motherships are resolved by vector clocks, but loud simultaneous admin actions on different Motherships can produce confusing outcomes. ### Configuring federation ```toml [federation] enabled = true peers = [ "https://berlin.mothership.acme:7777", "https://singapore.mothership.acme:7777", ] ``` On each Mothership, list the others. The set must be symmetric — if A lists B, B must list A. An unsymmetric config will not error, but events will flow in only one direction. ## Hub-and-Spoke Topology One central Mothership (the "hub"). Regional or departmental Motherships (the "spokes"). Spokes do not federate with each other; all cross-spoke traffic goes through the hub. ```text +-----------+ | HUB | | Mothership| | (main) | +-----------+ / | \ / | \ +-------+ +-------+ +-------+ | SPOKE | | SPOKE | | SPOKE | |Mship | |Mship | |Mship | | (EU) | |(APAC) | |(ctr) | +-------+ +-------+ +-------+ / \ / \ / \ peers peers peers ``` ### When to use hub-and-spoke - **Office-plus-remote patterns.** Headquarters has a dedicated Mothership on the office LAN; remote workers each connect via a small regional Mothership or directly to the hub. - **Contractor isolation.** External contributors connect to a spoke Mothership that is federated only with the hub, never with internal spokes. The hub operator decides what replicates to the contractor spoke. - **Regulated environments.** A spoke can be configured as read-only from the hub's perspective, preventing a compromised spoke from writing upstream. ### Trade-offs - Cross-spoke latency is 2x a round trip (spoke → hub → spoke). Fine for function sync; noticeable for team messaging. - The hub is a bottleneck. If it goes down, spokes still serve their local peers but cannot exchange changes. ### Read-only spokes A spoke can be marked read-only relative to the hub: ```toml [federation] enabled = true peers = ["https://hub.mothership.acme:7777"] role = "read-only-from-hub" ``` With this, peers connected to the spoke receive changes from the hub but the spoke never pushes upstream. Useful for a "documentation Mothership" or a contractor-facing replica. ## Which Topology Should You Pick? | Your situation | Recommended topology | |---|---| | Small team (<25), one office | Star | | Medium team (25–100), one region | Star | | Medium team, two regions | Mesh (2 Motherships) | | Large team (100+), globally distributed | Mesh (per region) | | HQ + contractors who need limited access | Hub-and-spoke | | HQ + regulated subsidiary | Hub-and-spoke with read-only spoke | | "We need to try Aura in one squad" | Star, smallest possible | The general rule: **start with star, migrate to mesh when latency hurts, use hub-and-spoke only when you need the trust boundary.** Migrating from star to mesh is straightforward. Stand up a second Mothership in a new region, federate it with the first, and tell peers in that region to rejoin via the new one. The two Motherships replicate history, so the new Mothership is not starting from zero. ## Topology and Trust A point worth calling out: federation is a _trust_ relationship, not just a connectivity one. Federated Motherships share the full intent log and all function bodies that peers push. If you do not trust the operators of a remote Mothership, do not federate with it. This matters for cross-organization collaboration. Two companies who want to share a subset of code should not federate their internal Motherships — that replicates _everything_. Instead, stand up a shared Mothership on neutral infrastructure for the joint project, and have developers from both sides join it as peers. > **Gotcha.** There is currently no selective replication at the function level between federated Motherships. It is all-or-nothing per repository. If you need selective sharing, use a separate Mothership for the shared portion. ## Resilience Properties by Topology | Event | Star | Mesh | Hub-and-spoke | |---|---|---|---| | Mothership host dies | Full outage (until offline mode kicks in) | Regional degradation | Hub down: spokes isolated. Spoke down: regional outage. | | Network partition between regions | N/A (one region) | Each region keeps working, reconciles on heal | Spokes keep working, reconcile on heal | | Admin mis-revokes everyone | Team-wide | Team-wide | Team-wide | | Compromised Mothership host | Team-wide | Regional (other regions can revoke the bad one) | Limited by role (read-only spoke compromise is bounded) | ## Example: A 200-Person Team in Three Time Zones A concrete configuration we have seen work well: - **NYC Mothership.** Dedicated Linux VM, 4 cores, 8 GB RAM. Federated with Berlin and Singapore. - **Berlin Mothership.** Same spec, federated with NYC and Singapore. - **Singapore Mothership.** Same spec, federated with NYC and Berlin. - **Peers.** Each developer joins the nearest Mothership. About 80 on NYC, 70 on Berlin, 50 on Singapore. - **VPN.** Tailscale tailnet spanning all three regions and all peers. - **Daily ops.** Rotating on-call, one person per region. Cert rotation quarterly. Audit review monthly. This setup handles 200 active developers comfortably. A change pushed in Berlin is visible in NYC within about 400ms (one federation hop) and in Singapore within about 600ms (one hop). ## Next Steps - [Scale a single Mothership to its limits](/scaling-mothership) - [Configure the persistent daemon](/persistent-daemon) - [Understand peer-to-peer details](/p2p-architecture)