Representative Data Model

Relevant source files

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

• app/models/representative.rb
• db/migrate/20200520030218_create_representatives.rb
• db/schema.rb
• app/controllers/my_news_items_controller.rb
• db/seeds.rb
• config/routes.rb

The Representative Data Model is a core component of the Actionmap application, designed to store and manage information regarding political officials. This model acts as a central link between geographic entities (like states and counties) and user-generated content, such as news items and ratings. It facilitates the discovery of local politicians and provides a platform for tracking news related to specific issues.

The system primary populates this model using data from the Google Civic Information API, mapping external official records to internal database attributes. It supports a one-to-many relationship with news items, allowing users to associate specific articles and ratings with individual representatives.

Sources: app/models/representative.rb:1-5, db/schema.rb:58-67, README.md

Database Schema and Attributes

The representatives table stores both identifying information and descriptive metadata for political officials. While the initial migration only defined a name and timestamps, the current schema has been expanded to include API-specific identifiers and contact details.

Field Definitions

Field	Type	Description
id	integer	Primary key for the representative record.
name	string	Full name of the official.
ocdid	string	Open Civic Data Identifier, used for mapping to geographic divisions.
title	string	The official office or position title held by the representative.
party	string	Political party affiliation (e.g., Democratic, Republican).
photo_url	string	URL to an official photograph of the representative.
address	string	Formatted string containing the official's contact address.
created_at	datetime	Record creation timestamp.
updated_at	datetime	Record last update timestamp.

Sources: db/schema.rb:58-67, db/migrate/20200520030218_create_representatives.rb:4-7

Model Logic and Data Integration

The Representative model contains specialized logic for processing data from the Google Civic API. The primary entry point for this integration is the civic_api_to_representative_params method, which iterates through API results to create or update local records.

Civic API Mapping Flow

The integration process involves parsing officials and offices from the API response. The model uses find_or_create_by! to ensure that representatives are not duplicated when multiple searches or updates are performed.

The logic relies on helper methods to clean and format strings before database insertion, specifically handling multi-line address fields.
Sources: app/models/representative.rb:6-25

Key Model Methods

• civic_api_to_representative_params(rep_info): Converts the complex nested structure of the Civic API response into a collection of Representative active record objects. It maps API "offices" to representative "titles" and "division_id" to "ocdid".
• build_address(first_address): A helper that concatenates line1, line2, line3, city, state, and zip into a single comma-separated string for the address attribute.
• update_dict(dict, name, division_id, party, photo_url): Standardizes the mapping of API fields to temporary attribute keys used during the creation process.

Sources: app/models/representative.rb:6-48

Relationships and Dependencies

The Representative model serves as the parent in several associations, most notably with news items.

News Items*: A Representative has a has_many relationship with news_items. If a representative record is deleted, all associated news items are also removed (dependent: :delete_all).

• Controllers: The MyNewsItemsController uses the representative_id to scope news item creation and management, ensuring that every news article is linked to a valid official.

Sources: app/models/representative.rb:4, db/schema.rb:34-45, app/controllers/my_news_items_controller.rb:102-106

Routing and Access

Representatives are accessed via standard RESTful routes and specialized search endpoints.

Route	Helper	Description
GET /representatives	representatives_path	Lists all representatives in the database.
GET /search/(:address)	search_representatives_path	Triggers the Civic API lookup and representative creation/update based on an address.
GET /representatives/:id	representative_path	Shows detailed information for a specific official.

Sources: config/routes.rb:41-60

Seeding and Development

For development purposes, the system includes seed data to populate the representatives table with initial entries. This process also demonstrates the creation of associated news items during initialization.

SeedData.representatives.each do |rep|
    rep_model = Representative.create(name: rep[:name])
    rep[:news_items].each do |news_item|
        NewsItem.create(
            representative: rep_model,
            title:          news_item[:title],
            description:    news_item[:description],
            link:           news_item[:link]
        )
    end
end

Sources: db/seeds.rb:25-36, db/seed_data.rb:440-478

Conclusion

The Representative Data Model is the architectural anchor for the Actionmap's political information system. By combining dynamic data from the Google Civic Information API with user-contributed news items, it creates a relational structure that allows users to navigate from geographic locations to specific officials and their relevant news history. The model's logic ensures data persistence and deduplication while maintaining strict relational integrity with the news and rating systems.