High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• config/application.rb
• config/routes.rb
• db/schema.rb
• package.json
• app/controllers/my_news_items_controller.rb
• lib/task_helpers/topojson_task_helper.rb
• lib/task_helpers/state_shapefile_request.rb
• app/javascript/packs/national_states_map.js

Actionmap is a Ruby on Rails web application designed to facilitate civic engagement by allowing users to locate representatives, track political events, and aggregate news items based on specific localities. The system integrates geographic data, external news APIs, and social authentication to provide a unified platform for political transparency.

The architecture follows a traditional Model-View-Controller (MVC) pattern, augmented by a robust frontend stack managed via Webpacker and a specialized data pipeline for processing geographic shapefiles into interactive web maps.

Sources: README.md:1-15, config/application.rb:1-35

System Components and Technology Stack

The application is built on Rails 5.2 and utilizes a variety of tools for data processing and frontend interactivity.

Component	Technology	Purpose
Backend Framework	Ruby on Rails 5.2	Core application logic, routing, and API management.
Database	PostgreSQL/SQLite	Persistence for users, representatives, and geographic metadata.
Frontend Management	Webpacker / Yarn	Compiling modern JavaScript and SCSS.
Map Rendering	D3.js & Topojson	Client-side interactive map visualization.
Authentication	OmniAuth (Google/Github)	Secure user login via third-party providers.
Data Processing	Mapshaper (Node.js)	Converting US Census shapefiles to Topojson.

Sources: config/application.rb:21, package.json:13-33, config/routes.rb:4-9, lib/task_helpers/topojson_task_helper.rb:10

Data Architecture

The database schema is designed around a hierarchical geographic structure (States > Counties) and their relationships to political entities (Representatives) and user-generated content (News Items, Ratings).

Geographic Data Pipeline

A critical part of the Actionmap architecture is the conversion of raw TIGER/Line shapefiles from the US Census Bureau into optimized Topojson for web rendering.

Map Data Transformation Flow

The system uses a set of task helpers to automate the fetching and processing of geographic data:

1. Fetch: Downloads ZIP files containing shapefiles (.shp) from the Census Bureau.
2. Unzip: Extracts files into temporary directories.
3. Process: Uses the mapshaper utility to simplify geometry (retaining ~10-40% of information) and "dissolve" subdivisions into unified county or state polygons.
4. Output: Generates .topo.json files stored in app/assets/topojson/ for use by the frontend.

News and Interaction Logic

The MyNewsItemsController manages the workflow for associating news articles with specific representatives. It interfaces with external APIs to provide users with relevant content.

News Item Search and Rating Workflow

1. Selection: The user selects a representative and a specific political issue.
2. External Query: The controller queries a News API using the representative's name and the issue as keywords.
3. Persistence: Top articles are stored in the session for the user to review.
4. Rating: Users select an article and assign it a rating, which is then persisted in the ratings table.

Frontend Architecture

The frontend is modularized into JavaScript "packs" managed by Webpacker. These packs handle specific views like the national map or individual state maps.

• application.js: Initializes global libraries like jQuery, Bootstrap, and Select2. It also manages Turbolinks for faster page transitions.
• national_states_map.js: Uses D3 and Topojson to render the US map. It maps mouse events to geographic paths, allowing users to click on a state to navigate to /state/:state_symbol.
• state_map.js: Renders individual counties within a state by parsing the state-specific Topojson files generated by the backend pipeline.

Sources: app/javascript/packs/application.js:28-38, app/javascript/packs/national_states_map.js:25-50, package.json:13-26

Summary

Actionmap leverages a robust Rails backend to manage complex geographic and political data. By utilizing a specialized pipeline for shapefile processing and D3.js for interactive visualizations, the architecture ensures that high-resolution geographic data is delivered in a lightweight, performant format (Topojson). The integration of OAuth for authentication and external News APIs for content provides a comprehensive platform for localized political awareness.