Secure Software Architecture - Courses - Institute of Computer Science

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

update the starter architecture document in /docs/architecture.adoc using the work from Weeks 1-3;
link to /docs/drivers.adoc, /docs/quality_attributes.adoc, /docs/qa_scenarios.adoc, /docs/security_goals.adoc, and /risk/risk_register.adoc;
check the proposed structure against /docs/ownership_sketch.adoc and /docs/iteration_plan.adoc; update them if design choices change the earlier assumptions;
create /docs/glossary.adoc for 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;
update the existing ADR index in /adrs/README.adoc and use /adrs/ADR-0001-template.adoc to write the first two real ADRs under /adrs/.

Deliverables due before Checkpoint 1

/docs/architecture.adoc with purpose, drivers, context, containers, and open questions;
/docs/glossary.adoc;
/diagrams/c4-context.* with a readable export and its editable source;
/diagrams/c4-container.* with a readable export and its editable source;
/adrs/ADR-0001-*.adoc for the diagramming/documentation approach;
/adrs/ADR-0002-*.adoc for the first data ownership or major structural decision;
updated /adrs/README.adoc linking to both ADRs;
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: summarize business goals, quality attributes, constraints, and assumptions, linking to the existing requirement files;
explain which design choices address the top drivers, quality attribute scenarios, security goals, and risks; record gaps that still need validation;
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.

For Week 4, complete the executive summary, architectural drivers, context, and container sections. Later sections may remain placeholders with explicit open questions. Detailed component views, API specifications, threat modeling, deployment, and operations plans are not due at this checkpoint.

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 consistent with the Week 3 security goals and assumptions;
labeled relationships stating how actors and external systems interact with the portal.

C4 container diagram should show

the chosen applications and data stores, with their responsibilities;
relevant external systems and the system boundary;
labeled relationships stating the interaction or data exchanged, and protocol where already decided;
known trust boundaries where relevant.

In the diagram and supporting text, explain where the in-scope portal capabilities are handled: identity and access control, case workflows, documents and signing, notifications, auditing/transparency, and external integrations. These responsibilities may share a container. Separate services, an API gateway, and microservices are design choices, not requirements. Keep internal components and mechanisms in the supporting text rather than mixing them into the container view.

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 Week 3 scenarios and security goals does the proposed structure support, and what remains unvalidated?
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;
relationships should be labeled and each diagram should use one C4 level of abstraction;
the architecture should trace back to earlier requirements and risks, with consistent data and organizational ownership assumptions;
ADRs should describe real decisions, alternatives, consequences, and links to drivers or risks.

Secure Software Architecture 2026/27 fall