Architecture decision records
An architecture decision record (ADR) captures one significant decision: the situation that called for it, what was decided, what follows from it, and which alternatives were rejected and why. Astela keeps its ADRs in this folder so that the reasoning behind the architecture is versioned and reviewed together with the code. ADR 0001 describes when an ADR is needed and how records are changed or superseded.
The architecture documents describe how the system works; the ADRs explain why it is built that way. The roadmap shows when the decided pieces arrive, and WORKFLOW.md defines how changes, including new ADRs, are reviewed and merged.
Template
Section titled “Template”Every ADR is a Markdown file named NNNN-short-title.md, written in English, with these sections:
# NNNN. Title in sentence case
## Status
Proposed, Accepted, Deprecated, or Superseded by ADR NNNN.
## Date
The date of the decision in ISO format (YYYY-MM-DD).
## Context
The forces at play: requirements, constraints, facts and measurements that make a decision necessary.
## Decision
What is decided, stated in the present tense and concretely enough to implement and review.
## Consequences
The expected positive and negative results, as bullet points.
## Alternatives considered
Each rejected option as a bullet point with a short reason.| ADR | Title |
|---|---|
| 0001 | Record architecture decisions |
| 0002 | Electron and the WebContentsView model |
| 0003 | Packaging with electron-builder |
| 0004 | TypeScript toolchain and build |
| 0005 | UI with Lit web components |
| 0006 | Dependency injection container |
| 0007 | IPC contracts and validation |
| 0008 | Internal pages via the app:// protocol |
| 0009 | Storage with node:sqlite |
| 0010 | Module system and lazy loading |
| 0011 | Settings schema as single source |
| 0012 | Policy providers per OS |
| 0013 | Theme system and design tokens |
| 0014 | Update architecture with a signed feed |
| 0015 | Linux package repositories |
| 0016 | Release pipeline without bot commits |
| 0017 | Performance budgets in CI |
| 0018 | Content blocker engine |
| 0019 | License: MPL-2.0 |
| 0020 | Documentation site and API docs |
| 0021 | Repository layout, linting and architecture rules |
| 0022 | Test strategy |
| 0023 | Internationalization |
| 0024 | Icons and typography |
| 0025 | Read policies while Electron starts |
| 0026 | Internal pages share tabs with web pages |
| 0027 | Content blocker with the default lists of uBlock Origin |
| 0028 | Content blocker rules through a frame preload |
| 0029 | Import from other browsers in the data service |
| 0030 | Default browser and links from other apps |
| 0031 | Scriptlets in their own scope and world |
| 0032 | Replacement resources over a scheme of their own |
| 0033 | Procedural and popup filters, and exceptions per domain |
| 0034 | Overlay view for popovers and prompts |
| 0035 | Optional lists for cookie notices and annoyances |
| 0036 | Problem pages drawn by the shell |
| 0037 | Policies read without blocking on every start |
| 0038 | Site permissions asked in the overlay |
| 0039 | Downloads without a question, and a list in the profile |
| 0040 | Tabs and popups that keep their opener |
| 0041 | Private windows with a session in memory |