ADR-0005-approved-technologies-and-engineering-standards.md

# ADR-0005: Approved technologies and engineering standards

Date: 2026-05-04  
Status: Accepted

## Context

Kompis-managed app projects need a clear and stable rule for what technologies are approved, how engineering standards are set, and how new stack choices are introduced.

Without this, projects can drift across different frameworks, runtimes, and patterns, making support, maintenance, and handover harder.

## Decision

### 1. Approved technologies must be explicit

For each app project, the approved stack must be documented in the project repo and/or the relevant project policy docs.

Approved technologies are only those that are explicitly documented or explicitly approved by David.

### 2. Preferred stack should be deliberate, not accidental

Each project should have a preferred stack for:

- runtime / language
- framework
- hosting platform
- database / storage
- auth / identity approach
- testing / linting / build tooling

The stack should be chosen intentionally for the project, not inherited by convenience.

### 3. New technologies require review

Introducing a new major technology, framework, platform, or architectural pattern requires a conscious review.

That review should consider:

- project fit
- operational complexity
- long-term maintainability
- security implications
- supportability
- whether the same need can be met with the existing stack

### 4. Engineering standards must be consistent

All projects should follow common engineering standards such as:

- linting and formatting
- type checking where applicable
- meaningful build verification
- minimal dependency sprawl
- clear code organization
- readable error handling
- reproducible local development

### 5. Prefer boring, supportable choices

Where practical, prefer technologies that are:

- well-supported
- understandable to future maintainers
- easy to deploy and troubleshoot
- compatible with the project's environment model

### 6. Exceptions must be explicit

If a project needs a technology outside the preferred/approved set, the exception must be stated clearly in the project docs and accepted intentionally.

## Consequences

### Positive

- Less stack drift
- Easier maintenance and onboarding
- More predictable deployments
- Better cross-project consistency

### Tradeoffs

- Slightly more process when introducing new tools
- Less freedom to experiment by default

## Notes

See also:

- `docs/ADR-0002-app-projects-environments-and-repos.md`
- `docs/ADR-0004-app-solution-documentation-and-acceptance.md`
- `docs/ADR-0006-security-and-integrity.md`
- `docs/APP-DEVELOPMENT-POLICY.md`
- `docs/PROJECT-POLICY.md`