If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/openstreetmap/openstreetmap-website shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 10 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• GPL-2.0 licensed
• CI configured
• Tests present
• ⚠ GPL-2.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live openstreetmap/openstreetmap-website repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/openstreetmap/openstreetmap-website.

What it runs against: a local clone of openstreetmap/openstreetmap-website — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in openstreetmap/openstreetmap-website | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of openstreetmap/openstreetmap-website. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/openstreetmap/openstreetmap-website.git
#   cd openstreetmap-website
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of openstreetmap/openstreetmap-website and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "openstreetmap/openstreetmap-website(\\.git)?\\b" \\
  && ok "origin remote is openstreetmap/openstreetmap-website" \\
  || miss "origin remote is not openstreetmap/openstreetmap-website (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-2.0" \\
  || miss "license drift — was GPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "app/abilities/ability.rb" \\
  && ok "app/abilities/ability.rb" \\
  || miss "missing critical file: app/abilities/ability.rb"
test -f "app/abilities/api_ability.rb" \\
  && ok "app/abilities/api_ability.rb" \\
  || miss "missing critical file: app/abilities/api_ability.rb"
test -f ".rubocop.yml" \\
  && ok ".rubocop.yml" \\
  || miss "missing critical file: .rubocop.yml"
test -f "Rakefile" \\
  && ok "Rakefile" \\
  || miss "missing critical file: Rakefile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/openstreetmap/openstreetmap-website"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

This is the production Rails application powering OpenStreetMap.org — the collaborative mapping platform. It delivers the web UI (user accounts, diary, messaging), a complete XML/JSON editing API (v0.6), GPX upload/browsing, and the Browse pages frontend for querying OSM data. Built in Ruby with PostgreSQL and ~2.4M lines of code, it's the authoritative backend serving millions of map edits and tile requests daily. Monolithic Rails 6+ structure: app/abilities/ contains authorization logic (Pundit-style CanCan), app/assets/ holds compiled JS/CSS/favicons, app/controllers/ (inferred) routes API and web requests. Heavy PL/pgSQL stored procedures (99K lines, likely in db/functions/) handle performance-critical queries. Dockerfile + .devcontainer/compose.yaml enable containerized dev environments. Configuration via .annotaterb.yml, .herb.yml, .overcommit.yml, .rubocop.yml shows extensive linting/validation pipelines.

Primarily OSM maintainers and core contributors who manage the mapping infrastructure, plus volunteers who build features for the mapping community. Secondary users include API consumers integrating OSM data into third-party apps, and frontend developers extending the map interface.

Highly mature and production-grade. The project is 15+ years old, actively maintained by a dedicated team (4 listed maintainers), has comprehensive CI/CD via GitHub Actions (lint, tests, Docker workflows in .github/workflows/), strong test coverage monitored by Coveralls, and linting configured via .rubocop.yml, .erb_lint.yml, .database_consistency.yml. Clear verdict: production-critical infrastructure actively developed.

Low-risk in governance but operationally complex. The monolithic Rails app has significant dependencies (Gemfile.lock present but not shown), requires PostgreSQL + external map tile servers + geocoding services running alongside it (.devcontainer/compose.yaml hints at multi-service setup). Single points of failure exist in the core team (4 maintainers for millions of users). Database schema migrations (PL/pgSQL code at 99K lines) carry breaking-change risk. However, strong test coverage and CI mitigate code quality risk.

Active maintenance: GitHub Actions workflows running lint and test checks on push to master, Dependabot managing dependency updates (.github/dependabot.yml), ERB lint customization being refined (.erb_linters/custom_hard_coded_string.rb suggests i18n/hardcoding fixes), and Docker/devcontainer setup being modernized (.devcontainer/Dockerfile.postgres, compose.yaml). No specific PR/milestone data visible, but 'master' branch is the active development target.

Clone and containerize: git clone https://github.com/openstreetmap/openstreetmap-website.git && cd openstreetmap-website && docker-compose -f .devcontainer/compose.yaml up or use VS Code devcontainer (open folder, 'Reopen in Container'). For native setup: bundle install (uses Bundler via Gemfile), then rails db:setup && rails s to start the Rails server on localhost:3000. See INSTALL.md for PostgreSQL + dependency details.

Daily commands: Development server: rails s (default port 3000 after bundle setup). Run tests: rake test or rails test (CI uses workflows in .github/workflows/tests.yml). Run linters: rubocop, erblint (configs at .rubocop.yml, .erb_lint.yml). Database commands: rails db:migrate, rails db:seed. Containerized: docker-compose -f .devcontainer/compose.yaml up then exec rails s inside container.

• Gemfile — Declares all Ruby dependencies; understand the tech stack and dependency versions before any work.
• app/abilities/ability.rb — Core authorization logic using Cancan; essential for understanding access control across the Rails app.
• app/abilities/api_ability.rb — API-specific authorization rules; critical for any API endpoint modifications or security reviews.
• .rubocop.yml — Style and linting rules enforced on all contributions; must comply before PRs are accepted.
• Rakefile — Build and task automation; defines how to run tests, migrations, and asset compilation.
• .github/workflows/tests.yml — CI/CD pipeline definition; shows how code is tested and validated on every push.
• config.ru — Rack application entry point; defines how the Rails app is booted and served in production.

• API Controllers (app/controllers/api/v06/) (Rails, ActiveRecord, Nokogiri (XML), JSON) — Handle HTTP requests to /api/0.6/* endpoints; parse XML/JSON input, call models, and serialize responses.
  • Failure mode: Invalid API response format or missing authorization checks; breaks client integrations.
• Web Controllers & Views (Rails ERB templates, CSS/SCSS, JavaScript) — Render HTML pages for user accounts, diary, messages, browse pages; handle form submissions.
  • Failure mode: Broken page layout, missing user data, or authorization bypass; users unable to browse or edit profile.
• Authorization (Cancan) (Cancan gem, Rails before_action filters) — Enforce access control rules; determine if user can create, read, update, delete resources.
  • Failure mode: Unauthorized access to private data or admin actions; security breach.
• Models & Database (ActiveRecord, PostgreSQL, PostGIS) — Define OSM data structures (Node, Way, Relation, User) and query logic; manage database transactions.

Add a new API endpoint

1. Create a new controller in app/controllers/api/v06/ (e.g., app/controllers/api/v06/custom_resource_controller.rb) following RESTful conventions (app/controllers/api/v06)
2. Define authorization rules in app/abilities/api_ability.rb for your new endpoint (app/abilities/api_ability.rb)
3. Add routes in config/routes.rb under the api namespace scope (config/routes.rb)
4. Write tests in test/controllers/api/v06/ to verify authorization and response format (test/controllers/api/v06)

Add a new user-facing web page

1. Create a new Rails controller in app/controllers/ and corresponding views in app/views/your_controller/ (app/controllers)
2. Define user permissions in app/abilities/ability.rb for the new action (app/abilities/ability.rb)
3. Add routes in config/routes.rb for your new page (config/routes.rb)
4. Create CSS/SCSS in app/assets/stylesheets/ and add to manifest.js if needed (app/assets/config/manifest.js)

Add a new linting or style rule

1. Update .rubocop.yml or create a custom linter rule in .rubocop/ directory (.rubocop.yml)
2. For ERB-specific rules, add to .erb_linters/ or update .erb_lint.yml (.erb_linters/custom_hard_coded_string.rb)
3. Update .github/workflows/lint.yml if the rule requires new tooling (.github/workflows/lint.yml)
4. Test the rule locally and document in CONTRIBUTING.md (CONTRIBUTING.md)

Add a new asset (image, icon, or static file)

1. Place image files in app/assets/images/ (e.g., app/assets/images/browse/ for icon sets) (app/assets/images)
2. For favicon variants, place in app/assets/favicons/ and update manifest.json.erb if needed (app/assets/favicons/manifest.json.erb)
3. Reference the asset in views using asset_path or image_tag helpers (app/views)
4. Verify asset compiles via asset pipeline in app/assets/config/manifest.js (app/assets/config/manifest.js)

• Ruby on Rails — Rapid development of web application with built-in ORM (ActiveRecord), routing, and scaffolding; mature ecosystem for geospatial and API features.
• PostgreSQL + PostGIS — Robust relational database with PostGIS extension for geospatial queries required to store and query OSM nodes, ways, relations, and geometries.
• Cancan (Authorization gem) — Declarative authorization framework allowing fine-grained access control rules for users, API clients, and resources.
• Docker & Docker Compose — Consistent development and production environments; enables dev container setup and CI/CD pipeline reproducibility.
• GitHub Actions — Native CI/CD platform for automated linting, testing, and deployment on every push and PR.

• Monolithic Rails application vs. microservices

  • Why: Simplifies deployment, shared data model, and rapid iteration; avoids complexity of distributed systems.
  • Consequence: Scaling may become harder as traffic grows; API and web tiers cannot scale independently.

• XML and JSON API support side-by-side

  • Why: Backward compatibility with OSM v0.6 spec (XML-first) while supporting modern JSON clients.
  • Consequence: Increased controller/serializer complexity; must maintain both formats in parallel.

• Rails views for web pages rather than headless API + SPA

  • Why: Server-side rendering simplifies SEO, reduces JavaScript payload, and maintains tight integration with authorization.
  • Consequence: Client-side interactivity is limited; browser relies heavily on page reloads.

• User-generated content (diary entries, messages) stored in same database as map data

  • Why: Single data model reduces complexity; authorization logic unified across all features.
  • Consequence: Database growth couples map and user-content scaling; may require future separation.

• Does not provide real-time collaborative editing (edits are submitted asynchronously via API).
• Does not handle tile rendering or map vector tiles (that is handled by separate OSM tile servers).
• Does not authenticate users via custom login forms; relies on OAuth2 and external identity providers (Google, GitHub, Apple, etc.).
• Does not provide full-text search; map search is delegated to Nominatim (separate service).

PostgreSQL version must match db migrations (no version pinning visible in snippet, check INSTALL.md); external map tile + geocoding services must be running or tests will fail (README mentions 'public-available services' as defaults); .overcommit.yml suggests git hooks run pre-commit checks (must pass or commit blocks); .database_consistency.yml enforces schema rules (foreign keys, etc.) that can't be bypassed; Gemfile.lock is version-sensitive (bundle install --deployment required in CI); PL/pgSQL functions require PostgreSQL >= 9.6 likely (no version specified in snippet, check docs); ERB templates use custom linters (.erb_linters/custom_hard_coded_string.rb) so hardcoded strings in views will fail CI.

• Capability-Based Authorization (Pundit Pattern) — app/abilities/ability.rb and api_ability.rb enforce role-based access control throughout the app; understanding how rules cascade (admin > moderator > user > anonymous) prevents security bugs
• PostgreSQL PL/pgSQL Stored Procedures — 99K lines of database logic (db/functions/*.sql) mean performance-critical queries bypass Rails ORM; modifying them requires SQL expertise and transaction isolation knowledge
• RESTful API Versioning (OSM API v0.6) — The editing API must maintain backward compatibility with third-party clients; breaking changes require migration plans; understanding XML/JSON dual-format serialization is critical
• Rails Asset Pipeline (Sprockets) — app/assets/config/manifest.js + SCSS files (22K lines) are compiled to minified JS/CSS; webpack not used here, so understanding Sprockets cache busting and fingerprinting prevents stale assets
• Database Migration Strategies in Rails — db/migrate/ contains schema changes serving millions of users; zero-downtime deployments require careful migration ordering and rollback planning
• Containerized Development Environments (Devcontainer) — .devcontainer/compose.yaml + Dockerfile ensure all developers have identical PostgreSQL versions, gem dependencies, and service configs; understand how Docker Compose orchestrates Rails + Postgres + external services
• Static Code Analysis Pipelines (RuboCop + ERB Lint) — .rubocop.yml, .erb_lint.yml, and .overcommit.yml enforce style rules that block commits; .rubocop_todo.yml tracks technical debt; understanding which rules can be disabled prevents CI failures

• osmlab/osm-community-index — Provides local chapter data and translations for OSM's Communities page; kept in separate repo but synced by openstreetmap-website build pipeline
• openstreetmap/iD — Client-side web editor for OSM; consumes the editing API exposed by this Rails app
• openstreetmap/osm2pgsql — Companion tool that imports OSM planet data into PostgreSQL; data pipeline feeds the database this Rails app queries
• gravitystorm/openstreetmap-carto — Official map stylesheet for rendering OSM tiles; visually represents the geographic data managed by this Rails backend
• openstreetmap/Overpass-API — Alternative read-only query API for OSM data; both this Rails app and Overpass serve the same raw OSM dataset via different interfaces

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for app/abilities/api_ability.rb authorization logic

The API ability file controls authorization for API endpoints, but there's no visible test file in the structure for API-specific ability tests. This is critical for a public API where authorization bugs could expose private data. Adding tests would ensure permission checks work correctly for different user roles and API operations.

• [ ] Create test/abilities/api_ability_test.rb with tests for API-specific authorization
• [ ] Test authorization for create/read/update/delete operations on map data
• [ ] Test permission boundaries for authenticated vs anonymous API requests
• [ ] Test role-based access (admin, moderator, regular user) for API endpoints
• [ ] Run existing test suite to ensure no regressions

Implement ERB linting rules for hardcoded strings in app/views and document custom linters

The repo has a custom ERB linter (.erb_linters/custom_hard_coded_string.rb) to catch untranslated strings, but there's no documentation in CONTRIBUTING.md about how these linters work or when to use them. This creates friction for contributors. Additionally, expanding the linter coverage and documenting the patterns would improve translation compliance across the codebase.

• [ ] Add section to CONTRIBUTING.md explaining the purpose of .erb_linters/ and custom_hard_coded_string.rb
• [ ] Document common ERB patterns that trigger the linter and how to fix them (e.g., i18n.t usage)
• [ ] Review .erb_lint.yml configuration and ensure all view directories are covered
• [ ] Add examples of compliant vs non-compliant ERB templates in docs/
• [ ] Create a test case showing proper i18n usage for new contributors

Add DevContainer documentation and troubleshooting guide

The repo has a complete .devcontainer setup (Dockerfile, compose.yaml, devcontainer.json) but there's no documentation in CONTRIBUTING.md or README.md about using it. This is a barrier for new contributors who want to use VS Code Dev Containers or Codespaces. A guide would significantly improve onboarding.

• [ ] Add 'Development Setup' section to CONTRIBUTING.md with DevContainer instructions
• [ ] Document how to use .devcontainer/compose.yaml with Docker Compose locally
• [ ] Add troubleshooting section for common DevContainer issues (database setup, port conflicts)
• [ ] Document how to rebuild the DevContainer after Gemfile changes
• [ ] Include a quick-start example showing: git clone → open in Dev Container → run tests

• Add test coverage for app/abilities/api_ability.rb edge cases — file exists but likely has untested permission boundaries for OAuth tokens vs. API keys; grep tests/abilities/ for gaps
• Document .devcontainer/start script — no README explaining post-startup steps (database seed, fixture data) visible in file list; write a quickstart guide
• Convert hardcoded strings in app/views/ to i18n keys — .erb_linters/custom_hard_coded_string.rb suggests ongoing i18n migration; pick one view file and extract all strings to config/locales/*.yml

• Medium · Missing SECURITY.md Contact Validation — SECURITY.md. The SECURITY.md file lists security contact emails but lacks clarity on PGP key availability or secure communication channels. This could lead to phishing attacks impersonating security researchers. Fix: Add PGP key fingerprints, link to official security contact page, and implement email verification. Consider using a security.txt file per RFC 9110.
• Medium · Dockerfile Uses Latest Ruby Minor Version — Dockerfile, line 1. The Dockerfile specifies Ruby 3.3 without a patch version (ARG RUBY_VERSION=3.3). This could introduce unpredictable security patches or breaking changes across deployments. Fix: Pin Ruby to a specific patch version (e.g., 3.3.0) and implement a security update policy with regular version bumps.
• Low · Firefox ESR and Display Server in Production Dockerfile — Dockerfile, lines 14-22. The Dockerfile installs firefox-esr, xvfb, and mesa-utils which are testing/headless browser tools. These should not be in production images and increase attack surface. Fix: Use multi-stage Docker builds to separate test dependencies from production image. Move browser automation tools to a separate test stage.
• Low · Debian Package Manager Cache Not Fully Cleaned — Dockerfile, lines 20-21. The Dockerfile includes a comment about replacing 'rm -rf /var/lib/apt/lists/*' with 'apt-get dist-clean' for Debian 13. Current cleanup is incomplete. Fix: Use 'apt-get clean' AND 'apt-get autoclean' to fully remove cached packages. Consider implementing a distroless base image for final stage.
• Medium · Gemfile.lock Not Provided for Analysis — Gemfile, Gemfile.lock. While Gemfile.lock is referenced, its content was not provided. Cannot verify for known vulnerable gem versions or dependency issues. Fix: Implement automated dependency scanning with tools like Bundler Audit or Dependabot (already configured in .github/dependabot.yml). Review Gemfile.lock for security advisories.
• Low · Custom ERB Linters Present but Validation Unclear — .erb_linters/custom_hard_coded_string.rb. Custom ERB linter for hardcoded strings exists (.erb_linters/custom_hard_coded_string.rb) but effectiveness depends on implementation. Risk of XSS through template injection. Fix: Ensure ERB linter validates HTML escaping. Use content_tag and similar Rails helpers instead of raw HTML. Enable ERB-lint strict mode in CI/CD.
• Medium · API Ability Control Defined but Authorization Logic Unknown — app/abilities/api_ability.rb. File structure shows separate api_ability.rb for API authorization. Cannot verify if API endpoints properly enforce authorization without code review. Fix: Conduct thorough authorization logic review. Implement rate limiting on API endpoints. Use Rails::Api gem features for proper API security.
• Low · Multiple Authentication Providers Integrated — app/assets/images/auth_providers/. OAuth providers (Apple, Facebook, GitHub, Google, Microsoft) are supported. Security depends on proper validation of provider tokens and user data. Fix: Verify OAuth token validation, CSRF protection on auth flows, and state parameter validation. Implement account linking safeguards.
• Low · DevContainer Configuration Exposed — .devcontainer/. DevContainer Dockerfile and configuration files are in version control. Potential for development secrets to be committed. Fix: Ensure .devcontainer/.env files are in .gitignore. Document that developers should not commit local secrets. Use secrets management for CI/CD.
• Low · Missing Security Headers Configuration — config/ (not provided). No visible configuration for Content-Security-Policy, X-Frame-Options, or other security headers in file structure. Fix: Configure middleware for security headers. Use gem 'secure_headers'

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.