How openstreetmap/openstreetmap-website works
Main components of the system
• Frontend & Integrated Editor: Since the project includes the integrated version of the iD editor and browse pages, clearly indicate a “Frontend” or “Web UI” component (representing the views, assets in “app/assets”, and public code in “public/”).
• Database: As a PostgreSQL-dependant Rails application, show the “Database (PostgreSQL)” with connections to Rails (including ActiveRecord models under “app/models”). You might also note that there are migrations and a “db” folder that define data schema and indexes.
• Auxiliary Components: Optionally, illustrate parts like the integrated GPX processing (see lib/gpx.rb and the API endpoints under “app/controllers/api”) and any support libraries used (e.g., for rate limiting or geolocation).
Relationships and interactions
• API endpoints interfacing with external requests (via the “api” controllers) and the client applications.
• Background jobs and asynchronous processing as part of the Rails system that interacts with the database and external systems.
Important architectural patterns and design principles
• MVC Pattern: Clearly indicate the separation of concerns between Models (data and business logic), Views (presentation), and Controllers (request handling).
• RESTful API: Emphasize that many parts of the system expose RESTful endpoints (API v0.6) and that the routing (config/routes.rb) organizes these resources.
• Background Job Processing: Indicate that jobs like trace_importer_job and trace_destroyer_job function asynchronously.
Relevant technologies and frameworks
• Ruby on Rails, PostgreSQL, and the use of standard Rails libraries/frameworks.
• Various dependencies (from Gemfile); you might mention libraries related to OAuth2, i18n, error handling, file uploads (ActiveStorage), background job processing, etc.
• Docker and Vagrant files hint at containerized development and provisioning strategies, so you might also include deployment/infrastructure layers if that helps your audience.
Elements
– From user browsers to the Web UI and then to the Rails Application.
– Between the Rails App and Database (bidirectional).
– From Rails App to external services (outgoing requests).
– From background jobs back to the Database or external notifications.
• Notations for frameworks/technology stacks attached to each component (e.g., “Ruby on Rails” on the Rails App, “PostgreSQL” on the Database, “Docker/Vagrant” on the deployment layer if desired).
Final advice
Happy diagramming!