implimentation_plan.md

Implementation Plan: Election Process Assistant

Source Analysis

• The actionable requirements source is .kiro/specs/election-process-assistant/requirements.md.
• The previous static JavaScript implementation has been removed at the user's request.
• This plan now targets a Python-first implementation with no Node.js runtime, package manager, or JavaScript application logic.

Definition of Done

The implementation is complete only when:

1. Every requirement from 1 through 20 has a Python-backed workflow, service, or route.
2. User-facing pages are rendered by Python.
3. Data loading, timeline calculation, registration guidance, voter guide generation, feedback, analytics, integrations, security behavior, and export generation are implemented in Python.
4. Any unavoidable browser-standard files are limited to static assets. The service worker is a tiny PWA cache file only; it contains no application workflow logic.
5. Every deleted, created, or modified file is tracked in progress.md.
6. Python tests and local HTTP checks pass before final delivery.
7. The app can run locally with the bundled Python runtime and standard library only.

Python Technical Approach

• Use the Python standard library for the local runnable version and list production dependencies in requirements.txt.
• Implement a WSGI application served locally with wsgiref.simple_server; use FastAPI/Uvicorn from requirements.txt for the next production ASGI migration.
• Use Python route handling for pages, forms, downloads, status lookups, guide generation, analytics, feedback, incidents, organizer tools, and admin views.
• Keep state in SQLite under storage/app_state.sqlite3, isolated by an HTTP-only session cookie.
• Protect all POST actions with session-bound CSRF tokens.
• Keep election_assistant/seed_data.py as rich US fallback data and shared metadata.
• Use election_assistant/data_sources.py for country-aware jurisdiction loading, adapter selection, JSON country configs, and SQLite jurisdiction caching.
• Render HTML with Python helpers in election_assistant/render.py.
• Use Python services for each domain area:
  • timeline.py
  • data_sources.py
  • registration.py
  • voting.py
  • ballot.py
  • polling.py
  • documents.py
  • feedback.py
  • analytics.py
  • integrations.py
  • security.py
  • education.py
• Add optional Google Civic API and Google Maps hooks controlled by GOOGLE_CIVIC_API_KEY and GOOGLE_MAPS_EMBED_KEY.
• Add a Python smoke test suite in tests/test_python_app.py.
• Add static CSS and SVG assets in static/.

Requirement Coverage Checklist

Requirement 1: Interactive Election Process Navigation

• Render a step-by-step Python page.
• Persist completion state in the session's SQLite state row.
• Show completed, current, and upcoming states.
• Include details, required documents, estimated time, contextual help, and ARIA-friendly controls.

Requirement 2: Personalized Timeline and Deadline Management

• Calculate jurisdiction deadlines in Python.
• Sort deadlines chronologically and show days remaining.
• Highlight deadlines within 14 days.
• Generate .ics calendar files in Python.
• Show reminder schedules and timezone labels.

Requirement 3: Voter Registration Guidance and Tracking

• Determine status from Python profile state.
• Render jurisdiction-specific methods, official links, required documents, eligibility rules, processing time, and fallback instructions.
• Simulate official registration lookup through the Python integration layer.

Requirement 4: Multi-Language and Accessibility Support

• Support English, Spanish, Chinese, Vietnamese, Korean, Tagalog, Arabic, French, Russian, and Portuguese.
• Persist selected language and text-size settings.
• Render landmarks, skip link, keyboard-friendly controls, contrast-conscious design, scalable text, and screen-reader mode.

Requirement 5: Voting Method Education and Comparison

• Render all voting methods available for the selected jurisdiction.
• Compare deadlines, requirements, procedures, and accessibility.
• Show detailed instructions, mail tracking, early voting info, absentee criteria, and wait-time fields.

Requirement 6: Ballot Information and Candidate Research

• Retrieve ballot data from the active country adapter, using US seed fallback, JSON country config, Google Civic where configured for US, or manual fallback notes.
• Render candidate details, party, websites, statements, measures, fiscal impact, arguments, and citations.
• Persist local research notes and include them in guide exports.

Requirement 7: Real-Time Notifications and Updates

• Persist notification settings in Python state.
• Support email, SMS, push, categories, and reminder intervals.
• Simulate update notices and immediate disable behavior.

Requirement 8: Polling Location Finder with Real-Time Information

• Render assigned polling location, address, directions link, hours, wait time, parking, transit, accessibility, language support, and alternative locations within 10 miles from the selected country adapter.

Requirement 9: Eligibility Verification and Problem Resolution

• Verify age, citizenship, and residency in Python.
• Explain failed criteria and show resolution steps, voting rights restoration notes, official contacts, and hotline details.

Requirement 10: Personalized Voter Guide Generation

• Generate personalized guide HTML and plain text in Python.
• Generate printable guide layout and QR-style official resource tile.
• Include checklist, status, deadlines, polling place, ballot summary, notes, and contacts.

Requirement 11: Feedback Collection and Pain Point Identification

• Render feedback forms on major pages.
• Capture page, category, message, timestamp, and optional contact.
• Flag content errors and produce trend summaries in Python.

Requirement 12: Usage Analytics and System Improvement

• Track anonymized local events in Python state.
• Show page usage, completion, deadline adherence proxy, satisfaction score, feedback trends, and drop-off signals.

Requirement 13: Offline Access and Progressive Web App

• Add web manifest and service worker static files.
• Render an offline status notice and queueable-action explanation.
• Cache essential app shell files and document cache-size policy.

Requirement 14: Integration with Official Election Systems

• Implement Python mock adapters for registration status, polling locations, and ballot information.
• Validate schemas, log requests, use retry with exponential backoff, and show fallback notices.

Requirement 15: Security and Privacy Protection

• Do not collect SSN or driver license values.
• Validate password complexity in Python.
• Rate-limit failed login attempts.
• Enforce a 30-minute authenticated session timeout.
• Provide local account deletion.
• Use a Python local vault with PBKDF2-HMAC and Fernet-like authenticated encryption fallback using standard-library HMAC and XOR stream derivation for prototype storage, with clear production guidance to use audited cryptography.

Requirement 16: Educational Content and Civic Engagement

• Render educational modules, transcripts, completion state, voting rights context, volunteer opportunities, and election worker information.

Requirement 17: Mobile-First Responsive Design

• Use mobile-first CSS from 320px upward.
• Provide touch-friendly controls, compact layouts, responsive grids, print support, and orientation-safe content.

Requirement 18: Innovative Voting Method Proposals

• Render ranked choice, approval, and STAR voting explainers.
• Include benefits, challenges, examples, modernization proposals, advocacy resources, and reform tracking placeholders.

Requirement 19: Voter Registration Drive Support

• Render organizer toolkit, printable materials, QR-style links, batch tracking, multilingual options, legal guidance, and aggregate stats.

Requirement 20: Election Day Support and Incident Reporting

• Render election day dashboard, incident forms, categorization, immediate guidance, escalation messaging, hotline/legal resources, pattern detection, and election day reminder settings.

Build Phases

Phase 1: Replace Current Implementation

• Stop the old Node server.
• Delete the JavaScript/Node implementation files.
• Update implimentation_plan.md and progress.md.

Phase 2: Python Skeleton

• Create election_assistant/ package.
• Create server.py.
• Add static assets and manifest.
• Add storage directory placeholder and SQLite-backed state.

Phase 3: Python Domain Services

• Implement seed data, SQLite state management, timelines, registration, eligibility, voting, ballot, polling, guide exports, feedback, analytics, integration adapters, security, CSRF, and education services.

Phase 4: Python Rendering and Routes

• Render all user pages server-side.
• Add POST actions for progress, settings, profile, notifications, feedback, incidents, notes, batch tracking, password validation, vault operations, data refresh, and account deletion.
• Add download routes for ICS, HTML guide, plain text guide, and organizer toolkit.

Phase 5: PWA and Static Assets

• Add static/styles.css, static/assets/icon.svg, static/assets/civic-map.svg, static/manifest.webmanifest, and static/service-worker.js.
• Keep PWA script minimal and static only.

Phase 6: Verification

• Add Python smoke tests.
• Compile all Python files.
• Run tests with bundled Python.
• Start the Python server and verify HTTP responses.
• Record every result in progress.md.