Citizen Tools Specification

Home / Citizen Tools / Citizen Tools Specification

Citizen Tools

Overview

The Citizen Tools module provides a public-facing transparency platform that allows citizens to search, review, compare, and monitor elected officials and political candidates. The module presents public accountability information through searchable politician profiles, public dashboards, election comparison tools, and community participation features.

The system is designed to:

Increase public access to political information.
Simplify complex government data.
Encourage civic participation.
Support community-driven evidence collection.
Improve transparency and accountability.
Provide mobile-friendly public access.

Objectives

The module shall provide:

Public politician profiles.
Search by city, state, district, party, and office.
Election season comparison tools.
Re-election risk reporting.
Exportable accountability summaries.
Public dashboards.
Mobile-friendly access.
Community evidence submissions.
Public correction requests.

Functional Architecture

Public Access Layer

Components:

Web portal
Mobile interface
Search API
Public dashboard engine
Export engine
Community submission portal

Data Collection Layer

Components:

Government data ingestion services
Election data importers
Legislative data importers
Public records importers
Filing document importers
Community submission intake services

Processing Layer

Components:

Search indexing engine
Relationship engine
Election comparison engine
Risk scoring engine
Dashboard generation engine
Export generation engine
Moderation engine

Storage Layer

Components:

Relational database
Document database
Search index
Evidence repository
Audit logs
Version history repository

System Requirements

Minimum Hardware

Development

8 CPU cores
32 GB RAM
500 GB SSD

Production

16 CPU cores
64 GB RAM
2 TB SSD
High-availability storage

Supported Operating Systems

Linux
Debian
Ubuntu
Rocky Linux
Red Hat Enterprise Linux

Required Services

PostgreSQL
Elasticsearch or OpenSearch
Redis
Object storage
Reverse proxy
Message queue system

Directory Structure

/docs
/config
/database
/api
/services
/importers
/workflows
/templates
/public
/evidence
/exports
/logs
/tests

Database Requirements

politicians

Fields:

id
full_name
party
office
district
city
state
country
biography
official_website
social_media
status
created_at
updated_at

elections

Fields:

id
election_name
office
district
election_date
result
vote_percentage
winner
created_at

accountability_reports

Fields:

id
politician_id
report_date
risk_score
summary
findings
generated_at

evidence_submissions

Fields:

id
submitter_type
title
description
source_url
uploaded_files
status
reviewer
created_at

correction_requests

Fields:

id
politician_id
requested_change
supporting_evidence
status
reviewer
created_at

public_dashboards

Fields:

id
dashboard_name
dashboard_type
configuration
last_generated

audit_logs

Fields:

id
actor
action
object_type
object_id
timestamp
details

Entity Relationship Model

Politicians:

Have many elections.
Have many accountability reports.
Have many evidence submissions.
Have many correction requests.

Elections:

Belong to politicians.

Evidence:

May reference multiple politicians.
May reference legislation.
May reference organizations.

Correction requests:

May modify profile information.
May modify accountability reports.
May modify evidence records.

Public Politician Profiles

Each profile shall display:

Name
Photograph
Political affiliation
Office held
District
Biography
Election history
Voting history
Legislative activity
Committee participation
Accountability reports
Community evidence
Corrections history
Source citations

Search System

The platform shall support searching by:

Geographic Search

Country
State
County
City
District
Zip code

Political Search

Party
Office
Committee
Election cycle

Advanced Search

Keyword search
Full text search
Fuzzy matching
Filter combinations
Saved searches

Election Season Comparison Tools

The module shall support:

Candidate comparisons
Incumbent comparisons
Voting record comparisons
Legislative comparisons
Promise versus action comparisons
Campaign finance comparisons
Public statement comparisons

Comparison reports shall include:

Visual charts
Historical timelines
Exportable reports
Source citations

Re-Election Risk Reports

The system shall calculate:

Approval trends
Legislative controversies
Ethics investigations
Voting inconsistencies
Attendance issues
Public sentiment indicators
Fundraising performance
Historical election margins

Risk Score Methodology

Risk scores shall include:

Low Risk

0-30

Moderate Risk

31-60

High Risk

61-80

Critical Risk

81-100

Risk calculations shall remain fully documented and reproducible.

Exportable Accountability Summaries

The platform shall support exporting:

PDF
CSV
JSON
HTML
Markdown

Exports shall include:

Summary information
Citations
Charts
Risk scores
Evidence references
Timestamp
System version

Public Dashboards

Dashboard categories:

Election dashboards
Politician dashboards
Accountability dashboards
Community contribution dashboards
Geographic dashboards
Legislative dashboards

Dashboards shall support:

Filtering
Sorting
Exporting
Sharing
Mobile rendering

Mobile-Friendly Access

The platform shall support:

Responsive layouts
Touch navigation
Accessibility features
Progressive Web Application support
Offline caching
Reduced bandwidth mode

Accessibility Requirements

Compliance requirements:

WCAG 2.2 AA
Keyboard navigation
Screen reader support
High contrast mode
Adjustable text sizing
ARIA support

Community Evidence Submissions

Citizens may submit:

Public documents
News articles
Videos
Images
Meeting records
Campaign materials
Government filings
Archived records

Each submission shall include:

Title
Description
Sources
Supporting files
Submission date

Evidence Verification Workflow

Submission received.
Virus and malware scan.
Duplicate detection.
Source verification.
Human moderation.
Publication approval.
Public availability.

Public Correction Requests

Correction requests shall allow users to:

Report factual errors.
Submit supporting evidence.
Request profile updates.
Request citation changes.
Request data removal.

Correction Workflow

Request received.
Automated validation.
Evidence verification.
Human review.
Decision recorded.
Public audit entry created.
Request closed.

Moderation Requirements

The system shall support:

Spam detection
Abuse prevention
Duplicate detection
Rate limiting
Reputation scoring
Human moderation queues

Abuse Prevention

The platform shall detect:

Coordinated manipulation
Automated submissions
Citation fraud
Mass false reports
Harassment campaigns
Duplicate evidence attacks

Audit Logging

Every action shall generate immutable audit records including:

User identifier
Timestamp
Action performed
Before values
After values
Reviewer information

API Requirements

Public API

Endpoints:

Search politicians
Retrieve profiles
Retrieve dashboards
Retrieve reports
Submit evidence
Submit corrections
Export reports

Security Requirements

Mandatory controls:

TLS encryption
Input validation
API authentication
Rate limiting
CSRF protection
XSS protection
SQL injection prevention
Content Security Policy

Privacy Requirements

The platform shall:

Minimize personal data collection.
Allow anonymous evidence submissions.
Permit pseudonymous participation.
Retain moderation records.
Publish privacy policies.

Monitoring Requirements

Metrics:

Search performance
Dashboard performance
Submission rates
Review times
Export generation times
Error rates
API usage

Backup Requirements

Backups:

Hourly database backups
Daily object storage backups
Weekly full snapshots
Quarterly restoration testing

Disaster Recovery

Recovery objectives:

RPO: 15 minutes
RTO: 4 hours

Testing Requirements

Testing shall include:

Unit testing
Integration testing
Search testing
Accessibility testing
Security testing
Load testing
Mobile testing
Moderation workflow testing

Deployment Requirements

Production deployments shall support:

Containerized environments
Kubernetes
High availability
Horizontal scaling
Blue-green deployments
Automated rollback

Governance Requirements

All algorithms used for:

Risk scoring
Comparisons
Moderation
Evidence verification

Shall be fully documented and publicly reviewable.

Specification Branding License (SBL)

Standard

Fully AGPL-3.0+ compliant system
Copyleft enforced for network deployments
Required attribution:
- Roxanne Ardary
- https://www.roxanneardary.com/

Optional

Specification Branding License (SBL)
- Attribution-free commercial deployment
- Pricing based on scale, usage, and deployment scope
- https://roxanneardary.com/citizen-tools/

License & Notice Requirements

Citizen Tools Module Specification is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0+). By contributing to any Open Arsenal project, you agree that your contributions will also be released under this license.

Please note the following:

All contributions must comply with the AGPL-3.0+ terms.
Under Section 7 of the license, all redistributions, forks, and derivative works must preserve attribution to Roxanne Ardary and roxanneardary.com.
Citizen Tools Module specifications are free to use with attribution. A Specification Branding License can be negotiated upon request.
The project’s notice.md file tracks attribution requirements and contributor acknowledgments. Any update that adds new contributors or modifies attribution should also update notice.md.
When submitting a pull request, ensure that any new files maintain the attribution headers where applicable.
Network-deployed versions of this software must also remain fully AGPL-3.0+ compliant, including exposure of source code modifications when applicable under the license.

For full legal details, please refer to the AGPL-3.0+ license and the project’s notice.md file.

Notice – ActionCheck

Attribution Requirement: Under Section 7 of the AGPL 3.0+ license, all redistributions, forks, and derivative works, including network-deployed versions of this project, must provide attribution to Roxanne Ardary and roxanneardary.com.

Contributors

This file tracks contributors and their specific contributions to the project.

Roxanne Ardary, roxanneardary.com – March 10, 2026
Created the repository for ActionCheck. Designed the platform to track politicians’ promises, votes, financial activity, and board memberships for public accountability.
[Add other contributors here] – [Date]
[Describe contribution in one sentence]

License

This repository is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0+).

Key Points

You are free to use, modify, and distribute the code.
All redistributions, forks, and derivative works or network-deployed versions must also be licensed under AGPL-3.0+ and provide attribution to Roxanne Ardary and roxanneardary.com as required under Section 7 of the license.
The software is provided “as is,” without warranty of any kind.

For the full license text, see GNU AGPL-3.0 License.