Chapter 5 · Foundations
Meet Atlas
The company, the data, the people, and the first slice we will actually ship. Every chapter from here builds on this one example.
5 min read
Every chapter from here builds one system. Having a single concrete example matters more than it might seem: most published material on this subject demonstrates a toy over a clean folder of documents, and the interesting problems all come from the mess that a real company has.
The company
A distributor of industrial supplies. Around 200 people, three warehouses, roughly 4,000 active customer accounts. They sell through a small inside-sales team who spend their day answering the same categories of question and looking things up in four systems.
They are deliberately unglamorous. Nothing about this problem requires a frontier use case, and the shape — several systems, real permissions, people under time pressure — is extremely common.
Who will use it
Three groups, and they may see different things. This matters from the first chapter because it determines the retrieval design.
| Who | How many | May see |
|---|---|---|
| Inside sales | 24 | Their own accounts, all product and policy documents |
| Warehouse supervisors | 9 | Inventory and fulfilment, no pricing or margin |
| Finance | 6 | Everything, including margin and credit |
A sales rep asking "what is the margin on SKU-4411" must be refused. Not because the model decides to refuse, but because the margin data is never retrieved for that person in the first place.
The data
Mapped using the inventory from the previous chapter:
| Source | Shape | Changes | Access |
|---|---|---|---|
| Policy and procedure documents | Documents | Rarely | Index nightly |
| Product specifications | Documents | Monthly | Index nightly |
| Customer contracts | Documents | Weekly | Index nightly, permission-scoped per account |
| Orders and inventory | Postgres | Constantly | Query live |
| Support tickets | API | Constantly | Call live |
| Sales email | Conversations | Constantly | Excluded from version one |
That last row is the decision from the previous chapter in practice. Sales email contains real institutional knowledge and also personal data, superseded commitments and private negotiations. It is excluded, the reason is written down, and the question can be revisited once everything else works.
The first slice
The narrowest thing worth shipping, which is the subject of chapter 7:
Inside sales can ask a question in plain language and get an answer from the policy, specification and contract documents, with a citation, scoped to the accounts they own.
No database queries. No actions. No tickets. One group of users, one source shape, read-only.
That slice is unexciting on purpose. It is also the slice that proves the three hardest things — ingestion, permission-scoped retrieval, and whether the answers are any good — without any of the machinery that makes failures hard to diagnose. Everything in sections 3 and 4 serves it.
The architecture we are heading toward
The router is the piece that keeps this affordable, for the reasons in chapter 2: most of what arrives is a question, and questions should never pay for an agent loop.
Note what is drawn at the retrieval step rather than at the model: the permission filter. That placement is the whole of the permission leak defence, and it is a one-word difference in a diagram that is very hard to correct later.
The stack
Concrete, because concrete teaches better than vendor-neutral prose:
- TypeScript on Node, because the surrounding systems are already there
- Postgres with pgvector for chunks and embeddings, because the company already runs Postgres and a second datastore is a second thing to operate
- Claude for generation, with the model named in one configuration file
⚠️ The vendor-specific parts are deliberately confined to their own chapters and one config module. Everything structural — the chunking decisions, the permission filter, the eval harness, the loop limits — is the same whichever model and vector store you pick. Where a chapter is genuinely tied to a vendor, it says so at the top.
What success looks like
Agreed before building, so it cannot be redefined afterwards:
- Coverage. 70% of questions inside sales currently asks a colleague get a correct, cited answer.
- Groundedness. Under 2% of answers contain a claim not supported by a retrieved source.
- Leakage. Zero answers containing data the asker may not see.
- Latency. Median under four seconds.
- Adoption. More than half the inside-sales team using it weekly after a month.
The third is a hard gate and the others are targets. Chapter 10 turns these into something measurable; section 9 turns them into a test suite that runs on every change.
Key points
- Atlas is a 200-person distributor with three user groups who may see different things.
- Sales email is excluded from version one, with the reason written down.
- The first slice is read-only, one user group, documents only — and it proves the three hardest things.
- The permission filter sits at retrieval, not at the model. That placement is the whole defence.
- The stack is concrete; vendor-specific parts are confined to their own chapters.