Users and workflows

What you will be able to do

Write down who uses the shared document assistant, what each person does with it, and what it will not do. Do it before anyone chooses a server or a service. A design that starts from services answers questions nobody asked and misses the ones that matter.

Before you startWhat to know and to have readyAbout 50 minutes

What you need to know

• The design pack and its three kinds of numbers, from Set up the design pack.
• The document assistant: search, then an answer with citations, from What RAG is in RAG: Building AI That Uses Your Data.
• Staff-only documents and why a customer must never see them, from Permissions and isolation in the RAG course.
• Tenants: several shops share one system, and each shop sees only its own data, from Authentication, Permissions and Multi-Tenant Applications.

What you need on your computer

• Your folder design-pack from the last lesson, open in VS Code. You edit requirements.md, a Markdown file. No command runs in this lesson.

An architect visits a family

An architect is asked to design a house. She does not start with the number of floors or the brand of the lift. She starts with a visit. Who lives here? A couple, two children, and a grandmother who cannot climb stairs. What does each person do on a normal day? The grandmother cooks for everyone. The children do homework in the evening. One parent works from home and has video calls.

From these few facts, a design follows. The grandmother needs a bedroom and the kitchen on the ground floor. The home office needs a door that closes. And the architect writes down what the house will not have: no swimming pool, no guest wing. Then nobody is surprised, and nobody pays for rooms that nobody uses.

An architect who starts from “three floors and a lift” may build a fine house. But it is a house for somebody else.

The problem: services before behaviour

Tomás has a plan for the shared assistant: “We need Kubernetes and a vector database service. Then we can grow to any size.” Both are real tools. Kubernetes runs many copies of an application on many servers. A vector database service is a hosted database for the search vectors. But Tomás chose them before anybody said who uses the assistant, or what they do with it.

Here is what that costs, with a fact from the RAG course. Six of Larkfield’s 36 documents are staff-only, such as the refund approval limits and the staff discount. Grace’s 67 test questions include 7 questions about staff-only facts. Customers will use the assistant too, on the shop’s website. Tomás’s plan does not say who asks. So nothing in it stops a customer from receiving a staff-only answer.

No service fixes that by being bigger. The fix comes from one sentence about behaviour: “A customer gets answers from public documents only.” A design must know that sentence before it chooses any service. The same is true for the 8 test questions that the documents cannot answer. Somebody must decide what the assistant says then.

The idea: functional requirements, written as journeys

A functional requirement says what the system must do: a behaviour that a person can see. “A customer gets answers from public documents only” is one. It does not say how the system does it. Compare it with a quality attribute, which says how well the system does it: how fast, how available, how private. The next lesson is about quality attributes.

Functional requirements are easy to write badly, as a long list of features. A clearer way is to write them as journeys. A journey is one thing that one kind of person does with the system, from start to end, in their own words. Some teams call it a workflow or a user story. Each journey has four parts:

• Who: a person or a role, such as “help-desk agent”.
• When: the situation that starts it, such as “while helping a customer”.
• What: the action, such as “asks a question”.
• Done: what the person sees when it works, such as “an answer with citations, in a few seconds”.

The last part matters most. “Done” turns a wish into something that you can check. You can watch an agent and say: yes, she got an answer with citations; no, she did not.

A journey also leaves things out, on purpose. It does not name a database, a model or a server. Those choices come later, in Module 2, and each one must serve a journey. Keep journeys short: about five for a small product. Each journey has a short ID, J1 to J5, so that later files can point to it.

Two more parts finish the picture. The problem statement has three or four sentences. It says who has the problem, what goes wrong today and what must be true when it is solved. The out-of-scope list says what the system will not do. Out of scope does not mean “never”. It means “not in this design, so do not expect it and do not pay for it”.

A tiny example: one journey, three versions

Here is the same journey written three ways. Read each one and ask: could Grace check it?

Version	Text	Can you check it?
A feature	“The assistant uses hybrid search and a reranker.”	No. It names a solution. It does not say who it helps or what “working” looks like.
A wish	“Agents get good answers.”	Barely. Which agents? When? What is “good”?
A journey	“J1. Who: a help-desk agent. When: while helping a customer. What: asks a question. Done: an answer with citations to the shop’s documents, in a few seconds.”	Yes. Watch one agent with one customer.

The journey is not longer by much. But each part removes a question. “With citations” tells Amira that the answer must carry its sources. “The shop’s documents” tells Kwame that each shop’s search covers only its own documents. “In a few seconds” is still vague, on purpose: the next lesson turns it into a number that Grace agrees to.

Larkfield’s problem and journeys

Kwame starts the file requirements.md with the problem statement. He writes it with Omar, in words that a person who is not an engineer can read:

Larkfield’s help desk has an assistant that answers questions from Larkfield’s own documents, with citations. Bramble Books wants the same assistant for its own documents, and two more shops may join next year. Today every shop would need its own copy. We need one assistant that several shops (tenants) share. Each shop must see only its own documents, at a cost per shop that Omar can put in a price.

Each sentence does a job. The first says what exists today. The second says who wants more. The third says what goes wrong: one copy per shop. The fourth says what must be true: one shared assistant, each shop apart, and a cost per shop.

Then Kwame visits the people, as the architect visited the family. Grace describes her agents’ day. Ines describes Bramble Books, where she and one helper do everything. Mei describes how documents change. From these talks come five journeys:

Who	Journey	What “done” looks like
Help-desk agent (Grace’s team)	J1: asks a question while helping a customer	an answer with citations to the shop’s documents, in a few seconds
Customer on the shop’s website	J2: asks a question before writing a ticket	an answer from public documents only, or “the documents do not say”
Shop owner or editor (Ines, Mei)	J3: uploads a new or changed document	the document is searchable in minutes, with a short summary; the old version stays for audits
Shop owner	J4: sees what the assistant answered	every answer with its question, citations and document versions
Kwame and Amira	J5: add a new shop	a new tenant with its own documents and users, without a code change

Five journeys, five kinds of person. Each arrow is something a person does; each result box is what that person sees when it works.

Text description of the diagram

On the left are five kinds of person. Each has an arrow to the shared document assistant in the middle, labelled with its journey. The help-desk agent asks while helping a customer (J1). The customer on the shop’s website asks before writing a ticket (J2). The shop editor uploads a new or changed document (J3). The shop owner checks what was answered (J4). Kwame and Amira add a new shop (J5). On the right are the five results, one per journey. J1 gives an answer with citations in a few seconds. J2 gives an answer from public documents only, or “the documents do not say”. J3 makes a document searchable in minutes, with the old version kept. J4 shows every answer with its question, citations and document versions. J5 gives a new tenant without a code change. The phone version shows the five journeys and one box for all the results.

Look at what the five journeys already tell the design, before any service:

• Two kinds of asker. Agents (J1) see staff and public documents. Customers (J2) see public documents only. So every question must carry who asks, and the search must filter by it. That is the staff-only problem, solved by a sentence.
• An honest “no”. J2’s “or the documents do not say” covers the 8 test questions that the documents cannot answer. The assistant must say so, not guess.
• Two kinds of work. J1 and J2 are questions: a person waits for the answer. J3 is an upload: the person can wait minutes. Module 2 uses this difference to split the work.
• Versions. J3 keeps old versions, and J4 shows which version an answer used. So a new version does not delete the old one. Ines needs this for her supplier contracts.
• Tenants are data, not code. J5 says “without a code change”. So a new shop is a few rows in a database, not a new copy of the program.

Notice also who is not on the list. Priya, Omar and Mei have other jobs in the proposal, but they are not users of the assistant in these journeys. A journey list is about the people who use the product, not everybody in the project.

What is out of scope

Next, Kwame writes what the assistant will not do. Each line comes from a question somebody asked in the talks:

• Answers from the internet or from general knowledge: the assistant uses only the shop’s documents.
• Actions (refunds, order changes): the assistant answers; people act.
• Shops sharing documents with each other.
• Languages other than English and French.
• A mobile app.

The line around the design. Everything in the red box is a question somebody asked, answered once with 'not in this design'.

Text description of the diagram

The left box lists what is in scope. The assistant answers from the shop’s own documents, with citations. It keeps each shop’s documents and answers apart. It takes new and changed documents and keeps the old versions. It keeps every answer for audits. The right box, in red, lists what is out of scope. The assistant does not answer from the internet or from general knowledge. It does not act, for example with refunds or order changes. Shops do not share documents. It speaks only English and French. There is no mobile app.

Each line saves work and risk. “People act” means that the assistant never needs permission to change an order, which removes a whole class of security problems. “Only the shop’s documents” means that a citation is always possible. “No sharing between shops” keeps the tenant rule simple: no exceptions. And each line saves money, because nobody designs, builds or runs it.

Tomás asks: “But what if a shop wants a mobile app next year?” Kwame answers: “Then we decide next year, with next year’s numbers. Today it is out of scope, and the proposal says so.” Out of scope is a decision, written down, that you can change later on purpose.

Guided practice: write the first half of requirements.md

You fill in the first part of requirements.md in your pack: the owner line, the problem, the journeys and out of scope. The next lesson adds the quality attributes.

1. Open requirements.md in VS Code. It is a template: each <…> is a place to fill in.
2. In the line Owner:, write Kwame (solution architect). In Reviewed with:, write Omar (product), Grace (Larkfield support) and Ines (Bramble Books).
3. Under Problem, delete the placeholder. Write the problem statement in your own words, in four sentences or fewer. Say who has the problem, what goes wrong today and what must be true.
4. Under Users and journeys, write J1 from the table above. Check the four parts: who, when, what and done.
5. Write J2. Make sure that its “done” says what happens when the documents do not answer the question.
6. Write J3, J4 and J5.
7. Under Out of scope, write the five lines. Add a reason after a colon where the reason is not obvious.
8. Read each journey’s “done” out loud. If you cannot picture somebody checking it, make it more concrete.
9. Save the file. Compare it with requirements.md in the labs folder C26/snapshots/end-of-m01.

Your words will differ from Kwame’s, and that is fine. Check that the same facts are there: two kinds of asker, an honest “no”, document versions, answers kept for audits, and new shops without code. The snapshot’s file also has the quality attributes; you write those in the next lesson.

When to write journeys

Write them first, before any architecture, every time a system has more than one kind of user. They are cheap: one page, a few talks. They are also the only way to find rules like “customers see public documents only” before a customer finds them for you.

Do not write a journey for every button. Five to eight journeys cover a small product. If you have thirty, some are features of one journey, and the list hides the important ones. Do not write journeys for internal parts either. “The worker embeds a chunk” is a step inside the system, not something a person does.

Journeys have a cost: they need the people. Kwame cannot write J2 well without Grace, who knows what customers ask, or J3 without Mei, who knows how documents change. A journey that the architect invents alone is an assumption, and it should be labelled as one.

Common mistakes

Common mistake

A journey that is a solution

Symptom: a journey names a tool or a technique, such as “J6: the system stores vectors in an HNSW index”. Nobody can say who it helps. Nobody outside the team can check it.

Cause: the writer started from the design, not from a person. This is Tomás’s mistake in a smaller form: services before behaviour.

Fix: ask “who notices if this works, and what do they see?” Perhaps the answer is “an agent gets an answer in a few seconds”. That is J1, already written, and the index is one possible way to meet it. Move the tool to the architecture, in Module 2. If nobody notices, the line does not belong in the requirements.

Common mistake

No out-of-scope list

Symptom: after the first demo, Ines asks: “Can it issue the refund too? The customer asked for one.” Nobody wrote that it cannot, so each person assumed something different. Ines thought it was coming; Amira never planned it.

Cause: the requirements say only what the system does. Everything else is open, so every reader fills the gap with their own wish.

Fix: write the out-of-scope list, and review it with the users, as Kwame did. “Actions: the assistant answers; people act” closes the question before the demo. If Ines still wants refunds, it becomes a decision with its own cost, not a surprise.

Your turn: Priya’s journey

Change one condition: a new kind of person. Priya, the data scientist, says: “Before any change to the model or the prompt, I run the evaluation set. If the share of correct answers falls, the change does not ship.” Should this be a journey? If yes, write it with its four parts. Does it change the out-of-scope list?

Show a possible answer

Yes. Priya uses the system, and she notices if it works. One way to write it:

Who	Journey	What “done” looks like
Priya, data scientist	J6: checks a model or prompt change before it ships	the evaluation set’s result next to the last one; the change is blocked if correct answers fall

It adds a behaviour: the system must run a fixed set of questions on demand, and keep each result. It does not change the out-of-scope list. It does connect to the next lesson: “correct answers fall” needs a target, such as “at least 85% correct”. The pack’s requirements.md does not add J6 as a journey. It puts Priya’s check in the quality attributes, as the way to measure answer quality. Both are reasonable; the important part is that the check is written down.

Knowledge check

Check your understanding

Which of these are functional requirements, and which are not? (a) A customer gets answers from public documents only. (b) 95% of answers arrive in 6 seconds or less. (c) Use a vector database service. (d) A shop owner can see every answer with its citations.

Show the answer

(a) and (d) are functional requirements: each one is a behaviour that a person can see, and neither says how it is built. (b) is a quality attribute: it says how well (how fast) the system answers. The next lesson turns words like “fast” into targets like this one. (c) is neither: it is a design choice. It belongs in the architecture, and only if it serves a journey better than the other options.

Check your understanding

Predict: Kwame forgets J2's rule 'public documents only' and writes 'J2: a customer asks a question; done: an answer with citations'. Using the RAG course's facts, what goes wrong, and when would the team find out?

Show the answer

The design would let a customer’s search include staff-only documents. Six of the 36 documents are staff-only. Seven of Grace’s 67 test questions are about staff-only facts, so the problem is not rare. Nothing in the architecture would filter by who asks, because no requirement asked for it. The team would find out late: in testing if they are lucky, or when a customer reads the refund approval limits. Adding the filter then means changing the search, the requests and the tests. One sentence in the journey would have prevented it.

Check your understanding

Practical check: what does your requirements.md contain after this lesson? Name the sections and one fact from each that the design must respect.

Show the answer

• Owner and reviewers: Kwame, reviewed with Omar, Grace and Ines.
• Problem: one assistant that several shops share, each shop sees only its own documents, at a cost per shop.
• Users and journeys: J1 to J5, each with who, journey and “done”. For example, J2: a customer gets public documents only, or “the documents do not say”.
• Out of scope: five lines. For example, “Actions: the assistant answers; people act”.

The Quality attributes and Verified and assumed sections are still placeholders. The next two lessons fill them.

Recap

• Start from people, not services. “Kubernetes and a vector database service” says nothing about the 7 staff-only questions; “a customer gets public documents only” does.
• A functional requirement says what the system must do, as a behaviour a person can see. Write them as journeys: who, when, what, and what “done” looks like.
• Larkfield’s assistant has five journeys: agents ask (J1), customers ask (J2), editors upload (J3), owners check (J4), and the team adds a shop without code (J5).
• The journeys already shape the design: two kinds of asker, an honest “no”, two kinds of work, document versions, and tenants as data.
• The out-of-scope list closes questions before they become surprises: no internet answers, no actions, no sharing between shops, two languages, no mobile app.

Next, you turn “in a few seconds”, “always on”, “private” and “cheap” into targets that you can measure.

Next: Quality attributes