Chapter 03
The big ideas
Five principles that guide every design choice in Legion.
These aren’t laws or requirements. They’re design principles — the answers to questions like “should this be a central server or should every node handle it?” Every time the Legion team faced a tough choice, these five ideas were the tiebreaker.
1. Interfaces don’t implement business logic
An interface is anything you interact with directly — a phone app, a desktop window, a command-line tool. It’s the window through which you see Legion.
The rule is simple: the interface should never do the actual work. It should only:
- Collect your input (what you type, what you say)
- Start the process going
- Show you the result
The actual work — running AI models, processing data, making decisions — happens on other nodes. The interface calls them and displays what comes back.
Why does this matter? Because it means your interface can change without interrupting the flow of your work. If you switch from smartphone to laptop to a smart display, your AI assistant keeps working the same way because the intelligence lives on the orchestrator, not the screen.
2. State is shared, not per-device
When you’re having a conversation with an AI, that conversation history belongs to you, not to your phone. It belongs to your entire group (the cohort).
This means:
- Close the app on your phone? Your conversation is still there on your laptop.
- Add a new device? It sees all your previous conversations.
- Your phone dies? Nothing is lost. The data lives on the cohort, not the device.
Think of it like a shared Google Doc. The document isn’t on your laptop — it’s on Google’s server and every device sees the same thing. In Legion, the “shared doc” is your data, and instead of Google’s server, it lives on your own network.
3. Streams go through messages, not direct calls
Some things — like audio — are continuous streams of data, not one-time questions. When you speak, it’s not a single packet — it’s a flow of sound.
Instead of connecting two devices directly (device A → device B), Legion routes streams through a topic system — like a bulletin board where devices post and subscribe.
Why? Because it makes it easy to add new steps later. If tomorrow you want to add noise filtering between your voice and the AI, you just insert a new device into the stream — like adding a new station in a relay race. No one has to change their code.
4. Routing uses “who’s closest” not “who’s available”
If your phone needs to play audio, it shouldn’t just pick any device with speakers. It should pick the device at your location — the one you’re actually sitting next to.
Legion tracks this using a focus system. The phone (or any device you interact with) announces: “I’m the one the user is talking to right now.” Other devices see this and know to send their audio output there.
This is like a conference room with speakers. When someone is presenting, the audio goes to the speakers in that room — not to every speaker in every building the company owns.
5. No traditional servers
This is the big one. Everything we’ve talked about so far leads to this conclusion: Legion has no backend.
Every node is equal. Every node can do everything (at least in principle). There is no “server that everyone connects to” and no “clients that connect to the server.”
There are only peers — devices that talk to each other directly.
This doesn’t mean Legion can’t work over the internet. It can. It means the internet is just a pipe — a way for peers to find and talk to each other — not an architecture.
These rules in practice
When you read through the rest of these pages, you’ll see these five principles showing up again and again:
- The module system (The building blocks) exists because of principle #1 — capabilities live on specialist nodes, not interfaces.
- The cohort concept (The building blocks) exists because of principle #2 — state is shared.
- The pub/sub messaging (How nodes talk) exists because of principle #3 — streams need topics.
- The focus system (The building blocks) exists because of principle #4 — route to the right place.
- The entire architecture (Under the hood) exists because of principle #5 — no servers, only peers.
What comes next
If these ideas make sense, you’re ready for the details. The building blocks covers every piece of the system.