Final assignment

What you will be able to do

Write your own architecture and cost proposal for a small multi-tenant document assistant, from requirements to an operating plan. You use the design pack of this course, but every input is yours: the tenants, their demand, the targets and the decisions. A reviewer must be able to check each number, follow each flow and see what you would do when something fails or grows.

Before you startWhat to know and to have readyAbout 180 minutes

• You completed Modules 1 to 6. Each part below names the lessons that it uses.
• You do not need the case studies for this assignment. The certificate asks for at least one of them: Cost and capacity plan from real demand data or Design review of an open document-question service. Both use the same pack for a new situation, so either one is good practice for this assignment.
• The pack: your folder design-pack at the end of Module 6, or the snapshot end-of-m06 (see the snapshots). Copy it to a new folder, for example my-proposal, so that your course pack stays as it is. Make a new virtual environment in the new folder, as in Set up the design pack.
• Python 3.12 or newer, as in the course. No account, no model call and no money are needed. You reuse the course’s measured values and price list; you do not measure new ones.
• You can work in more than one session. Run python -m pytest -q and python -m costmodel check after each part.

The situation

Choose the tenants of your assistant. You have two options:

• Your own case: a small group of organisations that would share one document assistant. Examples are three schools of a district, the branches of a small firm, or a few shops that use the same help-desk tool. Each tenant has its own documents and its own users, and no tenant may see another tenant’s documents or answers.
• The course’s brief, Willowmere Libraries (constructed for this assignment): three town libraries share one assistant. Each library uploads its own documents: lending rules, room booking rules and the guides to its events. Library staff ask questions at the desk, and members ask on each library’s website. The largest library has about 12 staff and 900 visitors on a busy day. The two small ones have 3 staff each and about 150 visitors. A fourth library may join next year. Every number in this brief is invented: treat each one as an assumption and give it a range.

Whichever you choose, write two sentences at the top of your proposal: who the tenants are, and what decision the proposal supports. For example: “Build one assistant for the three libraries. What does it cost per library, and what must we watch?”

Part 1: measurable requirements

Uses Users and workflows, Quality attributes and Demand assumptions.

1. Rewrite requirements.md for your tenants: the people, their main journeys (at least four), and what is out of scope, with the reason for each item.
2. Write the quality attributes as targets, each with a way to measure it. Cover latency (an SLO with a percentile), availability, privacy between tenants, auditability, maintainability, recovery (RTO and RPO) and the budget. Say who agreed each target, or that it is your assumption.
3. Rewrite demand.toml for your tenants: staff, customers or members, questions per person, documents, document changes and growth. Give each one a range (low, base, high) and its evidence, marked verified: or assumed:. With the Willowmere brief, almost everything is assumed:; say why each range is as wide as it is.
4. Run python -m costmodel demand and python -m costmodel demand --month 12. Explain the busiest hour and the busiest minute that the pack computes. Say where the peak shape comes from: if you keep the course’s values, say that they were measured on another workload.

Part 2: coherent data and request flows

Uses Service boundaries, Data and identity flows and Simplicity and evolution.

1. Update architecture/components.toml and the container diagram: each part with one job, one owner and the data it keeps. If your design keeps the course’s eight parts, say why they fit your tenants.
2. Write the request flow of one question and the ingestion sequence of one document, with the measured time of each step from measured.toml.
3. Write the data and identity flow. Show where the tenant travels: the token, the database transaction, the cache key, the job row and the file path. Trace one question of one tenant and one document of another tenant, with every value visible, as in the tiny example of Data and identity flows.
4. Run python -m costmodel components. Every component must be on the diagram.

Part 3: a transparent cost worksheet

Uses Workload arithmetic, Cost model, Unit economics, Model routing, Caching and batching and Build versus buy.

1. Check design.toml: the model, the cache hit share, the replicas and the database size. Change each value that does not fit your tenants, and write its reason.
2. Run workload, costs, units, scenarios and sensitivity, for the base case and the high case. Then run python -m costmodel export, and keep costs.csv as your worksheet.
3. Label every number that you quote: measured, price or assumption. Write “Prices change: check the current page” next to the costs.
4. Answer the three questions that Tomás asked in the course, for your tenants, with numbers. How many requests are in flight at the busiest minute? What does one question cost, variable only and all-in, and why do the two differ? If usage doubles, does the cost per tenant double?
5. Recompute one line of the cost table by hand from its inputs, for example the answer tokens or the database server. Show that it equals the pack’s line.

Part 4: trade-offs, failures and the operating plan

Uses Failure scenarios, Recovery objectives, Growth plan, Architecture decisions, Stakeholder presentation and Implementation roadmap.

1. Compare at least two designs under one workload, one quality check and one price list, as in the module practice of Build versus buy. Include the people’s time where it differs. Say which quality evidence you have: the course’s routing result was measured on another question set.
2. Write decisions/failure-modes.md for your design: at least five failures. Give each one what users see, a detection signal with a line, a mitigation, one owner and the recovery. Name the single point of failure and a proportionate mitigation, with its price.
3. Put your recovery targets and step times in design.toml, and run python -m costmodel recovery. Say which numbers a restore test must measure.
4. Run python -m costmodel growth and python -m costmodel growth --scenario high. Write the growth steps, each with its signal and line, and say which line is crossed first, and when.
5. Write at least three decision records. Each one has the options that lost, a cost and a revisit trigger that someone can read today.
6. Write decisions/roadmap.md: a first usable release with a done-when line, the validation work ranked by what it could change, and later steps that each wait for a signal.
7. Write decisions/presentation-outline.md: a ten-minute walkthrough for your tenants’ owners. Use rounded numbers with their ranges and kinds, the risks and one unresolved assumption.
8. Run python -m costmodel check. It must print Design pack check: 9 of 9 passed.

Common mistake

The tests fail after you change the inputs

Symptom: python -m pytest -q fails after you rewrite demand.toml or design.toml, for example in test_the_pack_demand_counts_verified_and_assumed or in the growth tests.

Cause: some of the course’s tests check Larkfield’s own results, such as how many demand values are verified, or which signal comes first. Your tenants give other results. The tests that check a rule, such as “concurrency is arrival rate × time in the system”, must still pass.

Fix: change each failing test so that it checks your own result, and say why in one line. Do not delete a test that checks a rule. If a rule test fails, your input breaks the model: read the message and fix the input.

What to submit

Your proposal folder (without .venv), with requirements.md, demand.toml, design.toml, architecture/, decisions/, costs.csv, the tests and PROPOSAL.md:

# <your tenants>: architecture and cost proposal
## The decision                (two sentences: the tenants and what the proposal supports)
## Requirements                (journeys, out of scope, quality attributes with targets and how measured,
                                demand ranges with verified and assumed values)
## Architecture and flows      (container diagram, request flow, ingestion sequence, where the tenant travels)
## Cost worksheet              (workload, cost by driver, unit costs, scenarios, sensitivity, one line by hand,
                                every number labelled measured, price or assumption)
## Trade-offs                  (designs compared under one workload, decision records)
## Failure and recovery        (failure table, single point of failure, RTO and RPO, the restore test)
## Growth and operating plan   (signals and lines, the first limit, the roadmap)
## Assumptions and limits      (the assumption that would change the recommendation; what is not measured)

How it is marked

A reviewer marks each required item demonstrated, partially demonstrated or not yet demonstrated, with a concrete reason. To complete the course, all four must be demonstrated. You can improve an item and submit it again.

Required item	Demonstrated	Partially demonstrated, for example	Not yet demonstrated, for example
Measurable requirements	The journeys and the out-of-scope list fit the tenants. Each quality attribute has a target, a period and a way to measure it. Demand is a range per tenant, and each value says verified or assumed, with a reason.	Targets exist, but one has no way to measure it (“fast”). Or demand is a single number without a range.	Services are chosen before the journeys. Or there are no targets, only adjectives.
Coherent data and request flows	Every part on the diagram has one job and one owner. The request flow and the ingestion sequence use the same parts and the measured times. The tenant travels with every flow: token, transaction, cache key, job and file path.	The flows exist, but the cache key or the background job does not carry the tenant. Or a part appears in a flow but not on the diagram.	No flow shows how a tenant’s data stays separate. Or the flows contradict the diagram.
Transparent cost worksheet	The pack’s outputs and costs.csv give the cost by driver, per question and per tenant, in three scenarios, with sensitivity. Every number is labelled measured, price or assumption. One line is recomputed by hand and matches. Tomás’s three questions are answered with numbers.	The costs are right, but some numbers have no kind. Or only the base case is shown.	A cost per question without its volume and fixed share. Or a number that the reviewer cannot trace to an input.
Trade-off and failure analysis	Designs are compared under one workload, quality check and price list, with people’s time. The failure table has owners, signals and recovery, and the single point of failure has a proportionate mitigation with its price. RTO and RPO come from the pack, and the restore test is planned. The growth plan names the first limit. Each decision record has a revisit trigger, the roadmap links every record, and check prints 9 of 9.	The table has failures, but some owners are “the team”, or some signals are complaints. Or a decision record has no trigger that someone can read.	No failure analysis. Or the design adds services or high availability with no number that justifies them.

Whatever else is strong, the proposal is not complete while a flow lets one tenant’s answer reach another tenant, or while a cost is shown without its assumptions. A neat diagram does not make up for a cache key without the tenant. A precise total does not make up for a hidden assumption.

The course’s results can help you judge yours, but they are not targets. For Larkfield’s two shops, the base case cost US$51.90 a month, 87% of it fixed. Twice the usage added 13%, and 0.58 requests were in flight at the busiest minute. The first limit was the provider quota, already in month 0 of the high case. Your tenants are different, so your numbers will be too.

AI assistants

You may use an AI assistant to practise, to explain an output or to suggest a failure that you missed. Check each suggestion, and be ready to explain your final work. Every number in your proposal comes from the pack’s commands or from an input that you wrote and labelled. An assistant may not invent a price, a measurement or an “industry average”. Mark in your report the decisions that are your own, and the suggestions that you rejected, with the reason.

Recap

In this course, you turned a request for “an AI assistant for several shops” into a proposal that others can check:

• Requirements first: journeys, measurable targets and demand as ranges, each number verified or assumed.
• A simple, traced architecture: one modular application and one database, with the tenant on every flow.
• Cost with its reasons: workload arithmetic, a cost table by driver, unit economics and sensitivity, from measured times, list prices and stated assumptions.
• Options measured, not guessed: the strong model, the cache, batching, and building or buying, each with a number.
• Failure and growth planned: owners, recovery targets, a tested restore and signals with lines.
• Decisions written down: records with revisit triggers, a walkthrough with one open question, and a roadmap that starts small.

If you have not done one yet, choose a case study for the certificate: Cost and capacity plan from real demand data or Design review of an open document-question service.