DOCSEARCHbyAlgolia
Submit Docs

Developers Amsterdam Standards

website·Indexed 31 days ago

https://developers.amsterdam

Development standards and guidelines for the city of Amsterdam, covering backend development with Python, frontend frameworks like React and Leaflet, AI governance, cybersecurity, and general practices for Git, GitHub, and Docker.

Tokens
11.9K
Snippets
18
Records
104
Agent score
58%

What's inside Developers Amsterdam

  1. Required content for City of Amsterdam project READMEs

    To comply with the city of Amsterdam's development standards, a README.md must include the following sections:

    1. Project Name and Introduction: A brief overview of the project's purpose, main objectives, motivation, and (if applicable) links to the deployed web application and documentation.
    2. Maintenance Team: The name of the team responsible for the project and their contact information.
    3. Installation Guide: Detailed information regarding software dependencies.
    4. Build and Test Instructions: Clear steps on how to build and test the application.
    5. Bug Reporting and Feature Requests: Guidelines on where to report issues (e.g., GitHub Issues, Jira).

  2. Select the approved testing frameworks by project type

    Depending on the project architecture, use the following approved frameworks:

    • Front-end projects: Use Jest or Vitest combined with React Testing Library.
    • Back-end projects (Django/Python): Use Django's built-in testing framework.
    • Regression tests: Use Playwright or Cypress.

  3. Access Amsterdam shared component libraries and demos

    Amsterdam provides several shared component libraries and demonstration resources for developers. Key repositories include the BMI DMS Upload tool, the core Design System, and the Wonen UI component library. For developers working specifically with maps, a dedicated portal provides common use-case examples.

  4. Use the recommended mapping stack for Amsterdam projects

    For projects requiring map functionality, the City of Amsterdam recommends using Leaflet as the map library and React as the frontend framework. To address the challenges of integrating Leaflet with the React component lifecycle, a reference repository and Storybook application containing common map components and feature examples is available.
    Browse examples and components at: https://maps.developers.amsterdam/

  5. Accessibility standards for Amsterdam municipality applications

    In accordance with the Digital Government Act, all websites and applications for the municipality of Amsterdam—including intranets, extranets, cloud applications, and mobile apps (native, web, and hybrid)—must comply with the Web Content Accessibility Guidelines (WCAG) 2.1 at AA level.

  6. Apply the 10 rules of security by design

    When developing applications for the city of Amsterdam, the following 10 security-by-design principles must be applied:

    1. Proactive Security Integration: Incorporate security during requirements, design, and architecture phases.
    2. Principle of Least Privilege: Limit user and process access to the minimum necessary for their role.
    3. Principle of Defense in Depth: Implement multiple layers of security controls so that if one fails, others remain.
    4. Principle of Fail-Safe: Ensure applications default to a secure state upon failure.
    5. Minimize the Attack Surface: Use only essential tools, software, data, and hardware.
    6. Do Not Trust Services: Always validate and sanitize all data from external or internal services and users.
    7. Principle of Open Design: Security must not rely on the secrecy of the design or source code.
    8. Security by Default: Default configurations must prioritize security; users must take deliberate action to lower security settings.
    9. Principle of Separation of Duties: Require multiple conditions or participants for sensitive processes to prevent single-entity control.
    10. Keep Security Simple: Minimize complexity for both end-users and developers to avoid workarounds.

  7. Implement Model Identity and Logic standards

    To ensure structural transparency and traceability, AI models must adhere to the following identity and logic requirements:

    • Architecture Definition: Explicitly state the technical architecture and algorithmic logic (e.g., ResNet-50, Random Forest).
    • Design Specifications: Document primary optimization goals (e.g., prioritizing recall over precision) and any trade-offs made for transparency or efficiency.
    • Version Control: Assign a unique identifier to the versioned model artifact (e.g., BosFauna-CNN-v1.0.pth) for precise traceability.

  8. Avoid common pitfalls in AI model architecture and testing

    To prevent skewed results and operational risks, avoid the following:

    • Using the validation dataset for final performance evaluation (leads to overly optimistic metrics).
    • Relying solely on top-line aggregate accuracy (masks poor performance on critical edge cases).
    • Deploying 'black-box' models without documented optimization goals and trade-offs.

  9. Configure Drift Detection and AI Telemetry

    To maintain model integrity, implement the following telemetry and detection mechanisms:

    • Data Drift: Monitor production data for statistical deviations from the training dataset.
    • Concept Drift: Track changes in the relationship between model inputs and outputs.
    • Custom AI Metrics: Log prediction confidence scores, inference latency, and the frequency of edge cases.

  10. Prepare Jupyter Notebooks for production code review

    Jupyter Notebooks (.ipynb) should not be submitted for production code reviews because of version control difficulties and hidden cell-execution states. All Data Science and AI code must be refactored into modular Python scripts before a review is requested. If a notebook is uploaded, all outputs must be removed to prevent the leak of sensitive information.

  11. Configure GitHub repository requirements for Amsterdam projects

    All projects must be hosted on GitHub within the city of Amsterdam's account. By default, repositories should be public, except for Infra-as-code logic, which must always be stored in a private repository to protect sensitive information. Every repository must include a CODEOWNERS file specifying the team name.

  12. Apply Bias Analysis and Mitigation Strategies

    Bias mitigation must be applied and documented across the machine learning lifecycle:

    • Baseline Analysis: Conduct pre-processing analysis of training data to establish baseline bias (e.g., class imbalances).
    • Pre-processing: Use re-sampling, re-weighting, over-sampling underrepresented groups, or targeted data augmentation.
    • In-processing: Use algorithmic adjustments during training, such as class-weighted loss functions (e.g., Focal Loss).
    • Post-processing: Adjust model outputs or decision thresholds after training to improve fairness.