Developers Amsterdam

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:

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

Database Picker

Repo Requirements Checklist

Test Framework Picker

Git Workflow

Branch Model

• main — stable, production-ready code
• develop — integration branch, set as default branch
• Recommended: GitLab Flow, Git Flow, or Trunk-based (latter requires CI/CD)

Branch Naming

Pattern: <type>/<ticket>-<description>

Examples:

• feature/PROJ-123-add-user-auth
• bugfix/PROJ-456-fix-login-redirect
• hotfix/fix-critical-payment-error

Commit Format

Use Conventional Commits. Title = what changed, description = why.

feat(auth): add SSO integration for employees

Implements SAML-based SSO to replace legacy password login.
Reduces onboarding friction and improves security posture.

Refs: PROJ-789

Rules:

• Atomic commits (one logical change per commit)
• Sign commits with GPG or SSH keys (SSH recommended)
• Never commit: secrets, credentials, PII, generated files, node_modules, local configs

Branch Protection (Required)

• PR reviews required before merging to develop and main
• Minimum one approval
• Cannot be disabled for convenience

Full branch strategy, signing setup, and PR workflow: read references/git-workflow.md

Security Rules (Summary)

Required practices:

• Branch protection rules enabled
• Public source code (except IaC)
• Test code before deployment
• Evaluate third-party dependencies
• City-standard authentication and monitoring/logging
• JWT validation per RFC9068 (validate typ, issuer, audience, signature, expiration)
• HTTPS for all data in transit
• CSP headers and SRI for fetched resources

Full security checklist with code examples: read references/security-checklist.md

Dependency Evaluation

Reject packages scoring poorly on most criteria. Mixed results = consult team.

Additional frontend requirements:

• Regular updates and patches
• Annual reviews for quality, reliability, and necessity
• Security scanning: GitHub Dependabot, NPM audit, Snyk

Accessibility

Mandatory: WCAG 2.1 AA compliance per the Digital Government Act.

Applies to all government websites, apps, intranets, extranets, cloud apps, and mobile apps.

Key requirements:

• Support 200% zoom
• Descriptive link text
• Screen reader compatible
• Logical page/focus order, visible focus rings
• Multimedia captions
• CSS spacing per WCAG 1.4.12
• Right-to-left language support

Testing tools: WebAIM WAVE, W3C Markup Validation, Google Lighthouse, VoiceOver, JAWS, TalkBack.

Database Standards

• PostgreSQL is the default RDBMS for all new projects
• PostGIS extension for geospatial data
• Use official Docker images (postgres, postgis/postgis) for local development
• Match versions with Azure PostgreSQL Flexible Server

Docker Standards

• Use Docker for containerization in dev, test, and production
• Base images: well-maintained, specify exact version (never latest tag)
• Common approved images: Alpine, NGINX, Node.js, PHP, Postgres, Python, Ubuntu
• Install only necessary packages
• Specify all dependency versions explicitly
• Dockerfiles live in the app's GitHub repo
• Compiled images in Azure Container Registry (ACR)
• Regular updates (monthly or quarterly minimum)
• No separate images for different DTAP/OTAP environments
• No unofficial or uncertified Docker images
• Use environment variables for sensitive data (never hard-coded)

Package Manager & Project Structure

• pnpm is the default package manager for all new Node.js/TypeScript projects. npm or yarn require explicit justification (e.g., tooling incompatibility, client constraint)
• Use corepack enable to pin the pnpm version via packageManager field in package.json

When to Monorepo

Monorepo Setup

# pnpm-workspace.yaml
packages:
  - "apps/*"
  - "packages/*"

Standard directory structure:

├── apps/
│   ├── web/              # Next.js frontend
│   └── api/              # Backend service
├── packages/
│   ├── shared/           # Shared types, utils
│   └── config/           # Shared ESLint, TSConfig
├── pnpm-workspace.yaml
├── package.json          # Root with "packageManager" field
└── pnpm-lock.yaml

Cross-package references

// apps/web/package.json
{
  "dependencies": {
    "@project/shared": "workspace:*"
  }
}

Run commands across packages: pnpm -r build, pnpm --filter web dev.

Documentation Requirements

Mandatory for all new repos (since May 2024):

1. Application overview (purpose)
2. License: EU-PL v1.2
3. README (using standard template)
4. Architecture Decision Records (ADRs)
5. Changelog with review date
6. Data processing information
7. API documentation (endpoints, params, auth, request/response)
8. Feature list with purposes

README template and ADR template: read references/project-setup-checklist.md

Do / Don't

Shared Components

Cross-Skill Boundaries

Reference Files