Week 4: documentation baseline, C4, and ADRs
Goal: create the first coherent architecture baseline that can be reviewed at Checkpoint 1.
In the practical session
- start the architecture document in
/docs/architecture.adoc; - create
/docs/glossary.adocfor key terms and stable component names; - create and export a C4 context diagram;
- create and export a C4 container diagram;
- describe each container's responsibility in text;
- check that diagrams, drivers, and risks use consistent names;
- create the ADR log and write the first two ADRs under
/adrs/.
Deliverables due before Checkpoint 1
/docs/architecture.adocwith purpose, drivers, context, containers, and open questions;/docs/glossary.adoc;/diagrams/c4-context.*with editable source if available;/diagrams/c4-container.*with editable source if available;/adrs/ADR-0001-*.adocfor the diagramming/documentation approach;/adrs/ADR-0002-*.adocfor the first data ownership or major structural decision;- updated
/risk/risk_register.adoc.
Minimum expected content in architecture.adoc
- executive summary: what the system is, who it is for, and the top architectural drivers;
- architectural drivers: business goals, quality attributes, constraints, and assumptions;
- C4 context view with explanatory text;
- C4 container view with explanatory text;
- responsibility list for every container;
- initial data ownership overview;
- current open questions and known inconsistencies.
C4 context diagram should show
- citizens/residents;
- administrators/helpdesk;
- auditors or oversight role;
- external service providers/agencies;
- external identity provider;
- external registries or back-end systems;
- the Citizen Services Portal as the system under design;
- high-level trust boundaries where they are already known.
C4 container diagram should show
- main user-facing application(s);
- API gateway or external API surface, if used;
- identity/session/access-control related component or service;
- workflow/case-management container;
- document handling container or storage;
- audit log / transparency mechanism;
- main data stores;
- integration/adapters for external organizations.
Minimum expected ADR quality
- ADRs use the course ADR template;
- each ADR states context, decision, alternatives, consequences, and follow-up actions;
- consequences include at least one negative consequence or risk;
- ADRs link back to drivers or risks where relevant.
Questions to answer
- Does the context diagram make the system boundary clear?
- Does the container diagram explain responsibilities rather than only technology choices?
- Which data belongs to which container or external system?
- Which design choice is important enough to deserve an ADR?
- Where do diagrams, risks, and drivers currently disagree?
Quality bar
- diagrams should be readable without narration;
- system boundaries and trust boundaries should be visible where relevant;
- every container should have a clear responsibility;
- ADRs should describe real decisions, alternatives, consequences, and links to drivers or risks.