developers-amsterdam

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: developers-amsterdam
description: >
  Mandatory for Gemeente Amsterdam architecture and engineering decisions.
  Use for tech stack choices, project setup, repo scaffolding, architecture,
  Git workflow, tests, dependency evaluation, Docker, databases, security,
  accessibility, code review, CI/CD, or other structural choices. Covers
  approved stacks (Python/Django, FastAPI, Node.js/TypeScript, React, Next.js),
  Conventional Commits, branch protection, commit signing, 70-80% test
  coverage, security-by-design, JWT RFC9068, CSP, README/ADR standards,
  EU-PL v1.2, Docker, PostgreSQL, and WCAG 2.1 AA.
---

# City of Amsterdam Engineering Standards

> **MANDATORY**: ALL architecture, tech stack, and engineering decisions MUST follow these standards. Do NOT recommend frameworks, databases, or patterns outside the approved list without explicit user approval. When setting up new projects, always apply these standards from day one.

Development standards for all Gemeente Amsterdam projects, maintained by Engineering Enablement.

> **Portal:** https://developers.amsterdam/
> **Source:** https://github.com/Amsterdam/development-standards
> **License:** CC0 1.0 Universal

## Clarify Before Building

When the user's request is vague (e.g., "build me an API", "set up a new project", "create a service"), **ask before assuming**. Surface these decision gates — they map to the picker tables below:

| Decision | Options | Why it matters |
|----------|---------|----------------|
| **Backend language** | Python (Django or FastAPI) or Node.js (TypeScript + NestJS) | Determines entire stack, test framework, and project structure |
| **Python framework** | Django (standard) or FastAPI (async/high-perf) | Different project layout, ORM, and testing patterns |
| **Project structure** | Single package or pnpm monorepo | Monorepo if sharing code across apps; single if one deployable |
| **Database** | PostgreSQL (default), PostGIS (geo), Cosmos DB (documents) | Affects Docker setup, migrations, and connection patterns |
| **Full-stack or API-only** | Next.js/React Router (full-stack) or API-only backend | Determines whether frontend scaffolding is needed |
| **Git workflow** | GitLab Flow, Git Flow, or Trunk-based | Trunk-based requires mature CI/CD; Git Flow for release trains |

**Don't ask all at once.** Pick the 1-2 questions that the prompt leaves genuinely ambiguous. If the user says "FastAPI service" → Python + FastAPI + API-only are all implied, just clarify structure and database if needed.

## Quick Decision Tables

### Language & Framework Picker

| Need | Choose | Notes |
|------|--------|-------|
| Backend API (standard) | Python + Django | Default choice for most projects |
| Backend API (high-perf / async) | Python + FastAPI | When async or performance is critical |
| Backend API (JS ecosystem) | Node.js + TypeScript + NestJS | When team expertise is JS-heavy |
| Frontend app | TypeScript + React | Always TypeScript for new projects |
| Full-stack app | Next.js or React Router | With Amsterdam Design System |
| Mobile | React Native | Integrated into Amsterdam App platform |
| Low-code | Mendix | For citizen-facing simple apps |
| Maps | Leaflet | See maps.developers.amsterdam |
| Package manager | pnpm | Default for all Node.js/TypeScript projects |

### Database Picker

| Need | Choose |
|------|--------|
| Standard RDBMS | PostgreSQL |
| Geospatial data | PostgreSQL + PostGIS |
| Document store | Azure Cosmos DB or MongoDB |
| Legacy/migration | Microsoft SQL Server |

### Repo Requirements Checklist

| Requirement | Mandatory |
|-------------|-----------|
| Hosted in City of Amsterdam GitHub org | Yes |
| Public repository | Yes (except IaC = private) |
| CODEOWNERS file with team name | Yes |
| README with template sections | Yes |
| EU-PL v1.2 license | Yes |
| Branch protection on `develop` and `main` | Yes |
| Commit signing (GPG or SSH) | Yes |
| CI/CD pipeline | Yes |
| ADRs for architecture decisions | Yes |
| Ch