Skip to main content

Architecture Decisions

We capture architecture decisions as Architecture Decision Records (ADRs). Each ADR has a stable identifier and short title and is managed through four lifecycle states.

Lifecycle states​

  • Proposed – a draft under discussion.
  • Accepted – an approved decision and the current norm.
  • Deprecated – kept for historical context but no longer recommended for new work.
  • Superseded by ADR XXX – explicitly replaced by a newer ADR.

Workflow​

  • Proposals are created and discussed as GitLab issues until a decision is reached.
  • Once accepted, the ADR is published in this documentation repository as a durable record.
  • Any later state changes (Deprecated or Superseded) are maintained here as well.
  • Superseding ADRs must reference the identifier of the ADR they replace; the older ADR records the superseding link.

This process ensures traceability from discussion to decision, clear status visibility, and a permanent, auditable history of architectural choices.

Template​

# ADR [Number]: \<Short Title>

Date: <YYYY-MM-DD>
Status: Proposed

Decision Makers: <Name or committee, optional>

## Context

\<describe what needs to be decided and the context of the decision>

## Checked [Architecture Principles](https://docs.core.civitasconnect.digital/docs_v2/Architecture/Architecture_General/Architecture_Principles)

<please select full, partial or none according to whether the decision meets the specific architecture principle>

- [full, partial, none] Model-centric data flow
- [full, partial, none] Distributed architecture with unified user experience
- [full, partial, none] Modular design
- [full, partial, none] Integration capability through defined interfaces
- [full, partial, none] Open source as the default
- [full, partial, none] Cloud-native architecture
- [full, partial, none] Prefer standard solutions over custom development
- [full, partial, none] Self-contained deployment
- [full, partial, none] Technological consistency to ensure maintainability
- [full, partial, none] Multi-tenancy
- [full, partial, none] Security by design

(if partial, then this topic should be commented)

## Decision

\<Decision incl. reasons>

### Consequences

<describe which parts of CIVITAS/CORE are influenced by this decision and what are the effects>

### Alternatives

- \<Alternative A>: Brief explanation of why it was discarded.
- \<Alternative B>: …

## See also

\<link to external resource that are helpful or relevant for this ADR e.g.:>

- ADR 00X – \<Title>
- Ticket #1234: Link to the issue
- External specification: https://example.com/spec
- Detailed analysis: https://example.com/spec