Chapter 4 · Design and Code
Software Design Basics: From Requirements to Modules
- Page 11 of 18
- 17 min read
Requirements say what ClinicQueue must do: patients book a slot, get a reminder, and the front desk sees the queue. They do not say how the software should be organised inside. If Farhan and Aiko simply start typing code, the first version may work, but every later change will touch everything, and two people cannot work on it at the same time without stepping on each other. Software design is the step in between: deciding the parts of the system, what each part is responsible for, and how the parts talk to each other.
The previous page, Risk Management, ended with a risk register. Several of its responses were really design decisions: "the date and time are filled in by our own code, not by the AI model" is a decision about which part of the system does what. This page gives you the vocabulary and the habits to make such decisions on purpose. It is the start of chapter 4, where planning turns into building.
What you will learn
- The two levels of design: architectural (high-level) and detailed (low-level).
- Modularity, cohesion, coupling and separation of concerns, with good and bad examples from ClinicQueue.
- A simple layered architecture for ClinicQueue (UI, API, logic, data) drawn as a text component diagram.
- How interfaces between modules work, and how to design for the changes you can expect.
- A design review checklist, and KISS, DRY and YAGNI as rules of thumb rather than laws.
From requirements to design: two levels
Design happens at two levels. Both are needed, but they answer different questions and are done at different times.
Architectural (high-level) design
The architecture is the big picture: the main parts of the system, how they communicate, where data is stored, and which external services are used. For ClinicQueue: a web front end for patients and for the front desk, a backend that holds the booking rules, a database, an SMS service and an AI model for drafting text. Architectural decisions are expensive to change later, because many other decisions depend on them. Moving from "bookings in a file" to "bookings in a database" after launch would touch almost every part of the code.
Detailed (low-level) design
Detailed design works inside one part: which functions or classes it has, what data they take and return, which rules they apply, and what happens when something fails. For the booking module: how to check that a slot is free, what to do if two patients press "Book" at the same moment, and what error message the patient sees.
| Architectural design | Detailed design | |
|---|---|---|
| Question | What are the main parts and how do they connect? | How does this one part work inside? |
| Typical output | Component diagram, list of external services, technology choices | Function and data descriptions, rules, error cases, sometimes a sketch of the code |
| When | Early, before most code; revisited when big requirements change | Just before or while building each feature |
| Cost of a mistake | High: many parts depend on it | Usually lower: limited to one part |
| ClinicQueue example | "The front end talks to the backend only through an API" | "book_slot rejects a slot in the past and a slot that is already taken" |
How much design should come before coding? A strictly sequential process (the waterfall model from Process Models: Waterfall, Incremental, RAD and Big Bang) tends to do all design up front. Agile teams usually sketch the architecture early and do detailed design story by story, because requirements will change. Both sides have a point: too little early design gives a tangle that is painful to change; too much gives detailed documents about features that are later dropped. For ClinicQueue, Lena's team spends one afternoon on the architecture before the first sprint and designs each story's details during the sprint.
Modules, cohesion and coupling
A module is a part of a program with a clear responsibility and a clear boundary: in Python, often one file or a small package. Modularity means building the system from such parts. Good modules let one person understand one part without reading everything, test it on its own, change it without breaking the rest, and let several people work at the same time.
Two ideas tell you whether your modules are good. Both were set out in the 1974 paper "Structured Design" by Stevens, Myers and Constantine, and they are still used today.
Cohesion: do the things inside belong together?
Cohesion is how closely the parts inside one module belong together. High cohesion is good: everything in the module serves one purpose. Low cohesion means the module is a drawer of unrelated things.
Example:
Low cohesion High cohesion
helpers.py booking.py free_slots, book_slot, cancel_booking
format_date() reminders.py reminders_due, send_reminder
send_sms() queue.py todays_queue, mark_arrived
is_slot_free() sms_gateway.py send_sms
backup_database() formatting.py format_date, format_time
calculate_waiting_time()On the left, a change to SMS sending, a change to date formatting and a change to backups all edit the same file, and nobody can say what helpers.py is for. On the right, each file has a purpose you can say in one sentence. A good test: if you cannot describe a module without the word "and", its cohesion is probably low.
Coupling: how much do modules depend on each other?
Coupling is how much one module depends on the inside of another. Low (loose) coupling is good: modules use each other only through a small, stable set of functions. High (tight) coupling means a change inside one module breaks others.
Example:
Tight coupling:
queue screen code runs its own query on the bookings table, and relies on the column
names "slot_start" and "status" and on status == 2 meaning "arrived".
Farhan renames a column or adds a new status -> Rina's queue screen breaks.
Loose coupling:
queue screen calls todays_queue(date) from queue.py and gets a list of
(time, patient name, doctor, arrived yes/no).
Farhan changes the table design -> he updates queue.py; the screen does not change.Some coupling is unavoidable; modules that never talk do not form a system. The goal is that they depend on what another module offers, not on how it does it. High cohesion and low coupling usually go together: when each module has one clear job, it needs to know little about the others.
Separation of concerns
A concern is one kind of thing the software must deal with: showing information, applying business rules, storing data, talking to external services. Separation of concerns means keeping each kind in its own place. A common beginner mistake in ClinicQueue would be to put the rule "a patient may hold only one booking per day" only in the browser page. The rule then lives in the display code, and a second front end (say, a page for Rina to book walk-in patients) would have to repeat it, or would forget it. Rules belong in the logic part, where every way of booking passes through them.
A layered architecture for ClinicQueue
A layered architecture is one of the simplest and most common ways to separate concerns. Each layer has one kind of job and uses only the layer directly below it. ClinicQueue uses four layers, plus adapters for the outside services.
Example:
+----------------------------------------------------------------------------------+
| UI layer (browser) |
| Patient booking pages (Aiko) Front-desk queue screen (Aiko, for Rina) |
+----------------------------------------+-----------------------------------------+
| HTTP requests and JSON responses
+----------------------------------------v-----------------------------------------+
| API layer /slots /bookings /queue /reminders |
| checks who is calling and what they may do; turns requests into calls below |
+----------------------------------------+-----------------------------------------+
| function calls
+----------------------------------------v-----------------------------------------+
| Logic layer booking queue reminders |
| clinic rules: free slots, one booking per day, who is next, when to remind |
+-----------------+----------------------+---------------------+-------------------+
| function calls | |
+-----------------v----------------+ +-v-------------+ +---v-------------------+
| Data layer | | SMS adapter | | Text-drafting adapter |
| patients, slots, bookings | | sms_gateway | | ai_drafts |
+-----------------+----------------+ +-------+-------+ +-----------+-----------+
| | |
[ Database ] [ SMS provider ] [ AI model service ]Follow one request through it. A patient presses "Book 10:30 with Dr. Rahman". The booking page (UI) sends a request to /bookings (API). The API checks the request is well formed and calls book_slot in the booking module (logic), which checks the clinic's rules and asks the data layer to save the booking. The data layer writes to the database; the answer travels back up, and the page shows "Booked". Later, the reminders module asks the SMS adapter to send a message. At no point does the page talk to the database or the SMS provider directly.
What this gives the team:
- Work can be divided: Aiko builds the UI against the API description while Farhan builds the logic and data layers.
- Rules live in one place: the patient pages and a future walk-in page both go through the same booking logic.
- Outside services are replaceable: if the clinic changes SMS provider, only
sms_gatewaychanges. - Testing is easier: Kwame and the developers can test the booking rules without a browser and without sending real SMS messages.
Layers have a cost: more files, and a small change sometimes passes through several of them. For a one-evening script that is overkill. Teams also argue about larger structures, such as splitting a system into many separately deployed services. For a five-person team building one clinic app, one application with clear layers is the simpler and safer choice; it can be split later if it ever needs to be.
Interfaces and design for change
Interfaces: the contract between modules
An interface is what a module offers to the rest of the system: the functions or endpoints, what they accept, what they return, and which errors they can give. Everything else is the module's private business. Keeping the inside hidden behind a small interface (often called information hiding) is what makes loose coupling possible.
Example:
Module: sms_gateway (used only by the reminders module)
send_sms(phone, text) -> delivery_id
phone: international format, for example "+8801000000000"
text: at most 160 characters
returns an id that can be used to ask for the delivery status
errors: InvalidPhone (bad number), ProviderUnavailable (try again later)
delivery_status(delivery_id) -> "sent" | "delivered" | "failed"
Not part of the interface: which provider is used, its web address, keys, retry rules.With this written down, Farhan can change providers, add retries or log every message without the reminders module noticing. The interface is also a good place for the details that cause bugs between people: units, formats, limits and error cases. Aiko's stand-up blocker on Project Management and the Roles in a Software Team ("the API returns times without a time zone") is exactly an interface detail that nobody had written down.
Design for change: "where will this change?"
Software that is used gets changed. You cannot predict every change, but you can ask, for each part of the design, "what is likely to change here?" and keep those things easy to change.
| Likely change | Design response |
|---|---|
| The clinic changes SMS provider (price, coverage) | All provider details stay inside sms_gateway, behind its interface |
| The AI drafting service changes, gets expensive, or must be switched off (risk register) | Drafting sits behind ai_drafts with a fixed template as fallback; the date and time come from the booking, never from the model |
| Opening hours, slot length, reminder time | Settings that Nadia's staff can change, not numbers written into the code |
| A new way to book (walk-in page at the desk) | Booking rules in the logic layer, so a new screen only needs the API |
| A second clinic one day | Not designed for now (see YAGNI below); keeping the layers clean is enough to make it possible later |
The last row matters as much as the others. Designing for every imaginable change makes the system bigger, slower to build and harder to understand. Design for changes you have a reason to expect; for the rest, keep the code clean so it is not hard to change when the time comes.
Reviewing a design
A design review checklist
A design review is a short meeting or written discussion where people other than the designer check the design before much code exists. Problems found here are cheap to fix: you change a diagram, not a hundred files. The ISO/IEC 25010:2023 quality characteristics you used for non-functional requirements (such as performance efficiency, security, maintainability and flexibility) are a good source of questions.
| Question | Why it matters |
|---|---|
| Does every requirement have a home in the design? | A requirement with no module is a requirement that will be forgotten |
| Can each module's purpose be said in one sentence? | Checks cohesion |
| Does any module use another's internals (tables, private functions)? | Checks coupling |
| Are the interfaces written down, with formats, limits and errors? | Most integration bugs live here |
| What happens when each external service fails or is slow? | SMS and AI services will fail sometimes |
| Where is personal data stored, and who can reach it? | Security; patient data |
| Are the HIGH risks in the register handled by the design? | For example, double booking is blocked by a rule in the data layer, not only in the page |
| What is likely to change, and is it easy to change? | Design for change |
| Is there a simpler design that meets the same requirements? | Complexity has a cost every day |
KISS, DRY and YAGNI: rules of thumb
Three short slogans are popular among developers. They are useful reminders, not laws, and sometimes they pull against each other.
- KISS, "keep it simple": prefer the simplest design that meets the requirements. A plain list of today's bookings sorted by time is a better queue screen than a clever real-time prediction engine nobody asked for.
- DRY, "don't repeat yourself": each piece of knowledge should live in one place. The rule "one booking per patient per day" should be written once, in the booking module. But do not merge two pieces of code only because they look alike today: if the reminder message and the receipt message happen to share a format but will change for different reasons, joining them couples two things that should be free to change separately.
- YAGNI, "you aren't gonna need it": do not build features or flexibility for needs you only imagine. Supporting many clinics, many languages and many SMS providers "just in case" would triple the work for v1.
Invented scenario:
Design review, before sprint 1.
Farhan: "Let us build a plug-in system so the clinic can choose any SMS provider."
Kwame: "YAGNI? We have one provider and no plan to change."
Lena: "But the risk register says the provider may fail or get expensive."
Outcome: no plug-in system. One small sms_gateway module with a written interface,
so switching provider later means rewriting one file, not the whole app.This is a typical resolution: YAGNI says no to a big general mechanism, and design for change says yes to a clean boundary. A clean interface is cheap now and keeps the later change cheap too.
Where this shows up at work
- Before a large feature, many teams write a short design note (one or two pages, with a diagram) and ask colleagues to review it before coding starts.
- Technical interviews often include "design a small system" questions; interviewers listen for parts, responsibilities, interfaces and trade-offs, not for one right answer.
- Code reviews often turn into design comments: "this page talks to the database directly" is a coupling comment.
- When an outside service changes its price or shuts down, teams with a clean adapter switch in days; teams with the service's details spread through the code spend weeks.
Common mistakes
- Going straight from requirements to code. The first feature works, and every later one gets harder. Fix: sketch the main parts and their interfaces first, even on one page.
- The "helpers" or "utils" module that grows forever. Low cohesion: everything changes in one file. Fix: give each function a home named after its purpose.
- Screens that talk to the database directly. Tight coupling: a table change breaks the UI, and rules get copied into every screen. Fix: go through the API and the logic layer.
- Interfaces that exist only in people's heads. Formats, units and errors are guessed differently on each side. Fix: write each interface down, including limits and error cases.
- Over-engineering "for the future". Flexible frameworks for needs nobody has delay the release and confuse the team. Fix: design for changes you have a reason to expect, and keep the rest simple and clean.
Try it yourself
- Easy: A file
clinic.pycontains:book_slot,send_sms,draw_queue_table_html,backup_databaseandcount_no_shows_last_month. Name the design problem and propose a better split into modules. - Medium: Place each item in a layer of the ClinicQueue architecture (UI, API, logic, data, or an adapter): (a) the rule "no bookings on public holidays"; (b) the button colours of the queue screen; (c) checking that the caller of
/queueis front-desk staff; (d) the SQL statement that saves a booking; (e) the code that calls the AI model service. - Hard: Nadia now wants reminders by email as well as SMS, chosen by the patient. Using the layered architecture and the
sms_gatewayinterface on this page, describe which modules change, which do not, and one new interface you would write. Then name one thing you would deliberately not build yet, and why.
Answers
- The problem is low cohesion: one module mixes booking rules, SMS sending, HTML display, database backups and reporting, so unrelated changes collide in one file and it has no single purpose. A better split:
booking.py(book_slot),sms_gateway.py(send_sms), the queue screen's own UI code (draw_queue_table_html), an operations script or module for backups (backup_database), andreports.py(count_no_shows_last_month). A good answer names cohesion (and possibly coupling, since everything importingclinic.pydepends on everything), gives each new module a one-sentence purpose, and keeps display code out of the logic. - (a) Logic layer, in the booking module: it is a clinic rule, and every way of booking must obey it. (b) UI layer. (c) API layer: it checks who is calling and what they may do. (d) Data layer. (e) An adapter (
ai_drafts), used by the reminders module in the logic layer. - Model answer: "Add a new adapter,
email_gateway, with an interface likesend_email(address, subject, text) -> delivery_idanddelivery_status(delivery_id), mirroringsms_gateway. The reminders module changes: it reads the patient's chosen channel and calls the right adapter. The data layer changes a little: patients get an email address and a 'reminder channel' field. The UI changes: the booking page asks for the channel. The booking module, the queue module, the queue screen andsms_gatewaydo not change. I would not build a general 'any channel' plug-in system yet: there are two channels and no request for more (YAGNI); if a third channel arrives, the two similar adapters will show what a shared interface should look like." A good answer lists changed and unchanged modules, keeps the channel choice in the logic layer rather than the UI, writes a concrete interface with errors or status, and justifies what is left out.
Summary
- Design turns requirements into a structure: architectural design decides the main parts and how they connect; detailed design decides how each part works inside.
- Good modules have high cohesion (one clear purpose) and low coupling (they use each other only through small interfaces); these ideas come from the 1974 "Structured Design" paper.
- Separation of concerns keeps display, rules, storage and external services apart; ClinicQueue does this with UI, API, logic and data layers plus adapters.
- Interfaces are contracts with formats, limits and errors; design for the changes you can expect, such as a new SMS provider or switching off the AI feature.
- Review designs early with a checklist; treat KISS, DRY and YAGNI as rules of thumb that sometimes need to be balanced.
Next: Data Modelling with Entity–Relationship Diagrams: designing the data layer of ClinicQueue, its patients, doctors, appointments and reminders, and how they relate.

