11. Risks and Technical Debt¶

Help: A list of identified technical risks or technical debts, ordered by priority. The term "risk management" is already used in project management (a]though often with different focus). In our context, we highlight risks and technical debt related to architecture and development.

Motivation: "Risk management is project management for grown-ups" (Tim Lister, Atlantic Systems Guild).

This should be your wake-up call: What could go wrong? What keeps you awake at night? What could derail the project or make the architecture fail? Documenting risks and technical debt is the first step toward managing them.

Form: List of risks and/or technical debt, probably including suggested measures to minimize, mitigate, or avoid risks, or reduce technical debt.

11.1 Risks¶

Help: Identify and document technical risks that could threaten the success of the project or the quality of the architecture. For each risk, assess likelihood and impact, and propose mitigation strategies.

ID	Risk	Likelihood	Impact	Mitigation Strategy	Owner	Status
R-01	\<e.g., Third-party API becomes unavailable>	\<Medium>	\<High>	\<Implement circuit breaker, cache responses, define SLA with provider>	\<Architect>	\<Open>
R-02	\<e.g., Performance degrades under peak load>	\<Medium>	\<High>	\<Load testing, auto-scaling, caching strategy>	\<Tech Lead>	\<Open>
R-03	\<e.g., Key team member leaves>	\<Low>	\<High>	\<Knowledge sharing, documentation, pair programming>	\<Manager>	\<Open>
R-04	\<e.g., Security vulnerability in dependencies>	\<High>	\<High>	\<Automated dependency scanning, regular updates>	\<Security Lead>	\<Open>
R-05	\<e.g., Data migration fails>	\<Low>	\<Critical>	\<Rehearsal migrations, rollback plan, data validation>	\<Data Engineer>	\<Open>
R-06	\<e.g., Cloud provider lock-in>	\<Medium>	\<Medium>	\<Abstract cloud services behind interfaces, use Terraform>	\<Architect>	\<Open>

Risk Matrix¶

                    Impact
                Low    Medium    High    Critical
Likelihood  ┌────────┬─────────┬────────┬──────────┐
            │        │         │        │          │
  High      │        │         │ R-04   │          │
            │        │         │        │          │
  Medium    │        │ R-06    │ R-01   │          │
            │        │         │ R-02   │          │
  Low       │        │         │ R-03   │ R-05     │
            │        │         │        │          │
            └────────┴─────────┴────────┴──────────┘

11.2 Technical Debt¶

Help: Document known technical debt -- shortcuts, workarounds, or suboptimal solutions that were accepted for pragmatic reasons but should be addressed in the future. Track the reason the debt was incurred, its impact, and a plan for resolution.

ID	Description	Category	Incurred Date	Reason	Impact	Remediation Plan	Priority	Estimated Effort
TD-01	\<e.g., Shared database between Service A and Service B>	\<Architecture>	\<YYYY-MM-DD>	\<Timeline pressure for MVP>	\<Tight coupling, deployment dependency>	\<Introduce API layer, migrate to separate databases>	\<High>	\<3 sprints>
TD-02	\<e.g., Missing integration tests for payment flow>	\<Testing>	\<YYYY-MM-DD>	\<Team capacity>	\<Regression risk in critical path>	\<Add Testcontainers-based integration tests>	\<High>	\<1 sprint>
TD-03	\<e.g., Hardcoded configuration values>	\<Code Quality>	\<YYYY-MM-DD>	\<Prototype carried to production>	\<Deployment inflexibility>	\<Move to config service / environment variables>	\<Medium>	\<0.5 sprint>
TD-04	\<e.g., No structured logging in legacy service>	\<Observability>	\<YYYY-MM-DD>	\<Legacy codebase>	\<Difficult debugging, no correlation>	\<Implement structured JSON logging>	\<Medium>	\<1 sprint>
TD-05	\<e.g., Outdated API documentation>	\<Documentation>	\<YYYY-MM-DD>	\<Documentation not in CI pipeline>	\<Developer confusion, integration errors>	\<Generate docs from OpenAPI specs in CI>	\<Low>	\<0.5 sprint>

Technical Debt Categories¶

Category	Description	Examples
Architecture	Structural issues in system design	Tight coupling, missing abstractions, shared databases
Code Quality	Code-level issues affecting maintainability	Duplication, complexity, lack of patterns
Testing	Gaps in test coverage or test quality	Missing tests, flaky tests, no performance tests
Infrastructure	Issues in deployment, CI/CD, or operations	Manual deployments, missing monitoring, no IaC
Documentation	Missing or outdated documentation	Stale API docs, missing runbooks, no onboarding guide
Security	Known security gaps or compliance issues	Unpatched dependencies, weak authentication
Observability	Gaps in monitoring, logging, or tracing	No distributed tracing, unstructured logs

11.3 Tracking and Review¶

Help: Define how risks and technical debt will be tracked and reviewed over time.

Process	Frequency	Participants	Output
\<Risk Review>	\<Monthly>	\<Architect, Tech Lead, Product Owner>	\<Updated risk register>
\<Technical Debt Review>	\<Per sprint planning>	\<Tech Lead, Development Team>	\<Prioritized remediation backlog>
\<Architecture Assessment>	\<Quarterly>	\<Architecture Review Board>	\<Architecture fitness report>

Based on the arc42 architecture template (https://arc42.org).
Created by Dr. Peter Hruschka and Dr. Gernot Starke.
Licensed under CC BY-SA 4.0.