CivicView

A non-partisan civic-engagement web and mobile platform that connects U.S. citizens with their elected representatives — and gives election candidates an equal-footing surface for running at the local, state, and federal level.

Beyond connection, the app helps citizens find and track their federal, state, and local representatives — including the bills those representatives sponsor, the votes they cast, the committees they sit on, the executive orders they sign (when applicable), and the public statements they make. Representatives and candidates in turn get verified pages where they can post, run polls, manage events, and engage their constituents through a moderated, district-scoped channel.

CivicView is filed as a Florida Benefit Corporation (initial Profit Corporation filing on the books — tracking #800474911808; Benefit Corp Amendment filed 2026-06-12). No ads, no venture capital, no partisan agenda. The revenue model is a $5/month consumer subscription for creating polls; browsing is free forever and commenting requires only identity verification.

---

Status

Phase: Live in demo mode. civicview.app, the installable desktop PWA, Google Play and the Microsoft Store all serve the live site, with demo accounts. The verified-account system + paid subscription flow are scaffolded end-to-end on the backend and frontend but inert until external accounts (ID.me, Stripe live mode) come online — gated on the Indiegogo campaign launch. See the Launch sequence section below for the staged rollout plan.

---

Built by

CivicView is built and maintained by Jeffrey De La Nuez ([email protected]) — sole creator, founder, and owner of the business.

The project was developed with major assistance from Anthropic's Claude AI suite:

• Claude Cowork — feature scoping, planning, financial modeling, legal-doc drafting (Terms of Service, Privacy Policy, Benefit Corp filing language), end-to-end fundraising prep, and most of this README.
• Claude Code — backend (FastAPI + SQLAlchemy + Pydantic), frontend (Next.js 15 + React 18), service abstractions (Postmark, Stripe, ID.me, Cloudflare R2), database auto-migrations, 2FA implementation, and cross-cutting refactors.
• Claude Design — design system tokens, the interactive U.S. map + panel split, the help-build transparency surface, the rep / candidate page layouts, identity-picker UX.

The architecture decisions, product direction, content moderation policies, business structure, and accountability live with the founder. Claude accelerated the work; it did not own it.

---

Engagement model + permission gates

CivicView enforces a tiered engagement model. The same person can hold up to three independent identities concurrently (citizen + verified rep + verified candidate), each with its own permission scope.

Citizen tier

Action	Free / unverified citizen	ID.me verified	ID.me verified + subscribed ($5/mo)
Browse representatives, bills, votes, executive orders	✅	✅	✅
Track reps / bills / elections (alerts when officials you track post or schedule events, and election reminders; no bill alerts yet)	✅	✅	✅
Like / dislike posts and polls	—	✅	✅
Vote on polls	—	✅	✅
Comment on posts and polls	—	✅	✅
Create polls (on poll page or unclaimed rep / candidate pages)	—	—	✅

Verification confirms the citizen is a real U.S. person at a real address (state + congressional district), which is the foundation for the "verified constituent" claim every engagement carries.

Representative tier

Sitting elected officials can claim their auto-generated page through a verification flow that uses ID.me identity verification cross-referenced against the official's government website. Once verified:

• Create posts (text + image)
• Run polls (4 visibility modes — public, district-scoped, party-scoped, supporter-scoped)
• Manage events (town halls, office hours, public appearances)
• Engage on their own page (likes, comments — "Author" badge surfaces page-owner voice)
• Dashboard with engagement analytics
• 2FA required at first login (FORCE_2FA_ENABLED)

Candidate tier

Declared election candidates get the same surface as reps once admin-approved (FEC ID / party nomination check today; ID.me-based self-serve in the future build). Distinct color treatment so candidate pages don't read as incumbent reps.

When a candidate wins, an admin flow promotes them to rep + archives the defeated incumbent.

Multi-identity in one browser

A single human can sign in as citizen + rep + candidate at the same time, in the same browser. The navbar exposes an identity dropdown ("pills") that lets the user pick which identity engages on any action — comment, vote, react. Author-badge UI, ✓ markers, and engagement attribution follow the chosen identity. Three independent cookies + bearer tokens back this: cl_session (rep), cl_citizen (citizen), cl_candidate (candidate).

---

Pre-launch state of verification + subscription

Today (demo preview): Self-serve demo citizen accounts are minted via /api/citizen-auth/demo-signup. Demo citizens get:

• verified=False (with verified_method='demo')
• is_subscribed=True (with subscription_status='demo', stripe_subscription_id=NULL)
• a required state and congressional district (city optional) and a display name no other account uses (see CLAUDE.md, "Account rules")

This lets the demo cohort exercise the full engagement experience (comment on posts + polls, create polls) end-to-end. The NULL stripe_subscription_id distinguishes demo grants from real paid subscribers when we audit post-launch. Both grants are flagged for removal in the codebase (auth_citizen.demo_signup) once real billing + verification go live.

Once ID.me + Stripe are live: Demo citizens get an opt-in migration (see the Identity verification + demo migration plan section below). Future signups go through the real verification → optional subscription flow.

---

Tech stack

Backend

• FastAPI (Python 3.10–3.14)
• SQLAlchemy 2.x + Pydantic v2
• PostgreSQL in production (Render), SQLite in local dev
• bcrypt for password hashing, itsdangerous for session cookies
• pyotp + cryptography (Fernet) for TOTP 2FA
• httpx for outbound HTTP (federal data, ID.me)
• boto3 for Cloudflare R2 (S3-compatible)
• Pillow to strip hidden metadata (EXIF, GPS location) from uploaded post images before they are stored
• postmarker for transactional email
• stripe for subscription billing
• anthropic for AI features (Claude Haiku — bill summaries, vote explainers, EO summaries, comment classification, semantic poll filtering)

Frontend

• Next.js 15 App Router + React 18
• Vanilla CSS + design-system tokens (no Tailwind compile step required — the design system is pre-compiled tokens)
• PWA-ready (manifest + service worker)
• localStorage-backed bearer-token fallback for cross-site-cookie-blocked environments (Safari ITP, mobile browsers)

Infrastructure

• Render (web service + Postgres) — production hosting
• Vercel — frontend hosting
• Cloudflare — DNS, WAF, DDoS protection, rate limiting on /api/admin/*
• Cloudflare R2 — post-image storage (S3-compatible, no egress fees)
• GitHub — source, Dependabot, CodeQL, Secret Scanning + Push Protection
• Domain: civicview.app (apex) + api.civicview.app (backend)

External APIs (live)

• Anthropic Claude API (Haiku) — AI summaries + classification
• Congress.gov API — federal legislator data
• Clerk of the House + U.S. Senate roll-call XML: how every member voted on every roll call, stored in the database (see Roll-call votes)
• Google Civic Information API — address-to-rep lookup
• Census Geocoder — address normalization
• Postmark — transactional email (scaffolded, awaiting credentials)
• Stripe — subscription billing (scaffolded, awaiting credentials)
• ID.me — identity verification (scaffolded, awaiting credentials)
• Cloudflare R2 — object storage for post images

---

Service abstractions (env-gated backends)

CivicView uses a consistent pattern for every external dependency: an abstract base class + a production backend + a dev / fallback backend. The factory picks based on env vars — when the production credentials aren't set, the dev backend takes over gracefully so the backend boots cleanly in any environment.

Service	Module	Production backend	Dev fallback	Required env vars
Image storage	services/image_storage.py	R2Storage	LocalDiskStorage	R2_ACCOUNT_ID + R2_ACCESS_KEY_ID + R2_SECRET_ACCESS_KEY + R2_BUCKET_NAME
Email	services/email_service.py	PostmarkEmailService	DevEmailService (sends nothing; logs the masked recipient only)	POSTMARK_API_TOKEN + POSTMARK_FROM_EMAIL
Billing	services/stripe_service.py	StripeBillingService	DevBillingService (returns about:blank)	STRIPE_API_KEY + STRIPE_PRICE_ID + STRIPE_WEBHOOK_SECRET
Identity verification	services/idme_service.py	IdMeService	DevIdMeService (fail-closed)	IDME_CLIENT_ID + IDME_CLIENT_SECRET + IDME_REDIRECT_URI
Web push (browsers, 2026-10-18)	services/web_push.py	WebPushService (http-ece + py-vapid over httpx)	off: browsers are not offered push and nothing is sent	VAPID_PUBLIC_KEY + VAPID_PRIVATE_KEY + VAPID_SUBJECT (Render), NEXT_PUBLIC_VAPID_PUBLIC_KEY (Vercel)

All four use lazy imports so missing optional dependencies don't crash boot. All four log loudly when the dev fallback is active so an operator knows the integration isn't live yet.

---

Authentication + security

• Three independent identity tracks (rep / citizen / candidate) with separate cookies and bearer tokens. Same browser can hold all three.
• Password hashing: bcrypt 4.x / 5.x directly (passlib dropped due to bcrypt-5 compat bug).
• Session cookies: httpOnly, SameSite=Lax, signed with itsdangerous + SESSION_SECRET. Mirror bearer tokens for cross-site-cookie-blocked environments.
• TOTP 2FA (Task #62): pyotp for codes, Fernet for at-rest secret encryption keyed off SESSION_SECRET via HKDF. Recovery codes bcrypt-hashed. Enforced at first login for rep / candidate / admin identities when FORCE_2FA_ENABLED=1 (citizens opt-in). Admin access always needs 2FA on the admin account, whatever that flag says; ADMIN_2FA_REQUIRED=false turns that off for local development.
• Password reset (Task #87): single-use sha256-hashed tokens with 1-hour TTL, sent via Postmark. Anti-enumeration on the request endpoint (always 200 regardless of email match). Confirmation email sent after successful reset.
• Self-serve account deletion (Task #81): soft delete with 30-day recovery window OR hard delete (immediate, with cascade). Verified identities archive a one-way hash so re-signup at the same email skips the ID.me re-charge.
• Admin moderation: suspend, hide, cascade-hide on suspension, appeals flow with grant/deny + reasoned logging.
• Cloudflare WAF + DDoS + rate-limiting on /api/admin/*. GitHub Dependabot + CodeQL + Secret Scanning + Push Protection on the source repo. See docs/SECURITY.md + docs/INCIDENT-RESPONSE.md.

---

Repository layout

backend/
  app/
    main.py                   # FastAPI app + lifespan startup + router mounts
    db.py                     # SQLAlchemy engine + session + auto-migrate
    auth.py                   # Rep session helpers
    auth_citizen.py           # Citizen session helpers
    auth_candidate.py         # Candidate session helpers
    seed.py                   # Demo accounts + demo backfill helpers
    models/
      pages.py                # ALL SQLAlchemy models (~1.4K lines)
    schemas/
      pages.py                # ALL Pydantic request/response schemas
    routers/                  # FastAPI route modules — one per feature area
      auth.py, auth_citizen.py, auth_candidate.py
      pages.py, citizen_polls.py, feed.py
      billing.py              # Stripe Checkout + Portal + webhook
      identity_verification.py # ID.me OAuth start + callback
      two_factor.py           # TOTP enroll + verify + recovery codes
      admin.py, appeals.py
      congress.py, federal_officials.py, state_officials.py, local_officials.py
      bills.py, votes.py, eos.py, elections.py, candidates.py
      notifications.py, address.py, waitlist.py, ai.py, google_civic.py, events.py, states.py
    services/                 # External-dep abstractions + business logic
      image_storage.py        # R2Storage + LocalDiskStorage
      email_service.py        # PostmarkEmailService + DevEmailService
      stripe_service.py       # StripeBillingService + DevBillingService
      idme_service.py         # IdMeService + DevIdMeService
      password_reset.py       # Token mint/verify/purge
      account_deletion.py     # Soft + hard delete + verification archive
      totp_service.py         # TOTP secret encryption + verification
      totp_enforcement.py     # FORCE_2FA_ENABLED enforcement
      ai_service.py           # Claude wrapper for bill / vote / EO / comment AI
      congress_service.py     # Congress.gov client + photo override layer
  requirements.txt
  data/                       # Curated seed JSON for accounts / candidates / etc.

frontend/
  app/                        # Next.js App Router pages
    page.js                   # Home — interactive map + side panel
    polls/page.js             # Global polls feed
    admin/                    # Admin moderation dashboard
    account/delete/           # Self-serve account deletion
    methodology, editorial-standards, privacy, terms, contact   # About-column footer
    password-reset/           # Password reset (request + confirm modes)
  components/                 # ~50 components — see directory for full list
  lib/                        # API clients (pagesApi.js is the workhorse) + auth hooks
  public/                     # Static assets

docs/
  SECURITY.md                 # Security posture, env-var setup, R2 setup
  INCIDENT-RESPONSE.md        # Runbook: compromised admin / DB breach / DDoS / leak
  LEGAL-REVIEW-ROADMAP.md     # Attorney engagement plan ($1.5K-$3K Tier-2 path)
  civicview_financial_model.xlsx  # 5-year P&L behind the crowdfunding goal
  identity-model.pdf          # Source-of-truth identity model spec
  build_identity_model_pdf.py # Regenerates the identity model PDF
  access-policy.md            # Draft access and neutrality policy (not yet published)
  *-prd.md, bills-*.md        # Product specs and design handoffs
  *listing*.md, *runbook*.md  # Store listings and launch runbooks
  # Business working files (outreach strategy, crowdfunding drafts, the
  # Benefit Corp filing language) live outside the repo since 2026-09-24.

Design Exports/               # Reference design-system snapshots (not in app)
DEPLOY.md, SETUP_GUIDE.md     # Production + local-dev runbooks
DESIGN_HANDOFF.md             # Design system handoff doc
render.yaml                   # Render service definition

---

What's shipped (high level)

The canonical, item-by-item list of shipped features lives on the Help build this page (source: frontend/components/HelpBuildThisView.js). Maintained as the single source of truth so the public funding ask and the internal status doc never drift. As of May 2026 the list runs ~35 entries; high-level categories:

• Civic data coverage — All 50 states + 435 congressional districts; full federal coverage (President, VP, Cabinet, SCOTUS, House + Senate leadership, all 535 members of Congress with photos); full Florida state coverage (state senate + house + statewide execs + 2026 candidates + election dates); address-to-rep lookup at every level.
• Bills + votes + executive orders — Per-bill CRS summary + Haiku plain-English translation, "What was this vote?" explainer with AI, per-EO Haiku abstract.
• Engagement surfaces — Rep pages (posts, polls, comments, reactions, 4 poll visibility modes, owner dashboard, scope filter), candidate pages (parallel composer + dashboard), citizen-led polls on unclaimed pages + standalone polls + global /polls feed, three-identity engagement model with multi-identity picker. Home page "National activity" section renders the same FeedCard the /posts page uses (full likes + comments + edit/delete/report inline), with an "All posts →" link to the canonical feed. Every post-action surface consolidates Edit / Delete / Report into a single kebab dropdown (PostActionsMenu) for a uniform look across home, /posts, /polls, and rep / candidate PageView feeds.
• Identity + auth — Citizen / rep / candidate auth with separate cookies + bearer tokens, 2FA with TOTP + recovery codes (enforced for rep / candidate / admin), self-serve account deletion with 30-day grace, password reset flow.
• Moderation + appeals — Report flow, auto-hide threshold, admin queue with Dismiss / Hide / Unhide / Suspend, cascade-hide on suspension, citizen + rep appeals with grant/deny.
• AI features — Comment sentiment + tone, semantic filter chips, post summarization, poll classification, vote explainer — all powered by Claude Haiku via services/ai_service.py.
• Notifications — Email (Postmark, scaffolded) + in-app bell with cross-identity inbox. Android push with as-they-happen, daily or weekly summaries, and one-click email unsubscribe (2026-10-16; see Push alerts and summaries).
• Service scaffolds (inert until env vars set) — Postmark (Task #87), Stripe ($5/mo subscription, hosted Checkout + Customer Portal + webhook, Task #88), ID.me OAuth + verification archive cost-skip (Task #89), Cloudflare R2 (Task #83).
• Security — Cloudflare WAF + DDoS + rate limiting, Dependabot + CodeQL + Secret Scanning, daily Postgres backups, documented incident-response runbook.
• Transparency — Help-build page with line-item funding breakdown, 5-year financial model in Excel, Benefit Corp formation PDF, identity-model spec PDF, full Terms + Privacy + Editorial Standards

---

Shipped 2026-10-24: ballot measures in plain English

People said the official wording of some ballot measures is hard to follow. A ballot measure's Details on the Elections tab now has "Explain in plain English" under the official ballot summary: a short paragraph, the specifics, the votes it needs, and what a Yes vote and a No vote mean, labeled AI-generated, with the official summary staying the wording that counts. It is written once per measure from the official text in the elections data only (services/ballot_measure_service.py, GET /api/ballot-measures/{id}/plain-english, POST .../generate in the AI rate limit) and saved, so everyone sees the same text. It uses Claude Sonnet, not Haiku: in testing Haiku added conditions the ballot text doesn't have. The prompt keeps it neutral and never says how to vote; an explanation with any figure that isn't in the official text is not saved. If a measure's wording changes, its explanation is written again. The three Florida 2026 amendments ship with explanations read before release (app/data/ballot_measure_explanations.json); checked by tests/test_ballot_measure_plain_english.py and npm run test:summary-text.

---

Shipped 2026-10-20: feed filters that filter, and hidden results that stay hidden

• Polls and Posts, States chip: on its own it always showed an empty grid; it now shows everything from the state picked in its dropdown (and opens the dropdown when none is picked). Chip logic is in frontend/lib/feedFilters.js (npm run test:feed-filters).
• Posts, branch chips: posts now carry the same branch as their official's polls, so Congress, Executive and Judicial work on Posts.
• Posts, AI filter: it asked the polls endpoint and matched poll ids against post ids. Posts have their own POST /api/ai/filter-posts now, and each new post gets the same tone and topic tags polls and comments get (services/post_classifier.py; the privacy page says so).
• A page's Your view: Country now really shows country-wide counts; before a choice is made no chip is highlighted and each poll shows its own default.
• Hidden results: the Polls feed, Popular polls and Explore results now follow the author's setting like the page does: "Show results" for polls hidden until the viewer asks, and no counts anywhere (CSV included, enforced on the server) until a poll set to reveal after it closes has closed (services/poll_visibility.py; checked by tests/test_feed_results_and_filters.py).
• Polls, From candidates: a candidate's poll is stored as a candidate's, and the chip's server filter only looked for rep-stored ones, so it was always empty. It now shows candidates' polls, and their likes come from the post they're attached to.

---

Shipped 2026-10-20: bill summaries read cleanly

• Profile Bills tab: the official CRS summary printed Congress.gov's leftover HTML as text ("", " "); it now reads as plain paragraphs. The AI plain-English version showed its bold labels with the asterisks; they are bold now. The same cleanup applies to a President's executive-order abstracts. Nothing is rendered as HTML from the source (frontend/lib/summaryText.js, checked by npm run test:summary-text).

---

Shipped 2026-10-19: a dashboard on real data, and labels that say what they do

• Citizen dashboard, Overview: "Your activity" counts this month's poll votes, comments and reactions (they were fixed at 0). "Coming up" (was "Upcoming in your district", always empty) lists the state's next voting deadlines, only dates with an official source (the same ones election reminders use), events from officials you track and polls you voted in that close within 14 days. "Recent activity" (always empty) shows the last 7 days of your notifications, bell-cleared ones included. One read: GET /api/activity/dashboard.
• Governor profiles no longer show an Exec. Orders tab: there is no state executive-order source, so it was always empty.
• Home: "Past 24 hours / National activity" is now "Most engaged / National activity" (it shows the most engaged posts, not the last day), and the address note reads "Address used only to find your districts. Never sold." (the address goes to the Census geocoder to find them).
• Stats: Reps joined and Candidates joined leave out the internal CivicView Test Rep and Test Candidate.
• Events: an event saved with an explicit UTC offset no longer makes GET /api/events/upcoming answer 500.
• The contact email card no longer promises an edit control that doesn't exist.

Shipped 2026-10-18: web push

The same pushes as the Android app now reach desktop browsers, browsers on Android phones, CivicView on an iPhone or iPad Home Screen (iOS 16.4 or later) and the Windows app, through each browser's own push service, encrypted for that browser. The settings list, Mute, quiet hours, summaries, grouping and the private-by-default text apply exactly as on the phone, and Notification details is one choice for all of a person's devices. The settings list shows "This browser" with Turn on; the browser asks for permission only from that tap or the opt-in card's Enable, and the card comes only after a track (and once when the Home Screen app opens). In Safari on an iPhone, Turn on shows a short Add to Home Screen guide. Installed apps show the unread count on their icon. The Android app keeps FCM, unchanged. Web push stays off until the VAPID keys are set: run scripts/generate_vapid_keys.py on your own computer and follow the runbook's Web push section (docs/push_notifications_runbook.md).

---

Shipped 2026-10-17: phone notifications

Android notification channels (Officials you track, Events, Replies, Bill updates, Poll results, Election reminders, Changes to pages you track, Summaries), private by default (each notification shows only a neutral line, not who posted, unless the person chooses Show details), a monochrome status bar icon and grouped notifications. New alerts: replies to your comments (on posts and citizen polls), a daily pass over the federal bills you track on Congress.gov, and "Results are in" when a poll you voted in closes. One short settings list, enforced on the server and the same on every device, replaces the 32 per-item switches, with Mute per official in My Tracked. The app checks Android's notification setting at every launch and resume and offers Open settings when it is off. App 1.2.0 (versionCode 5) builds the notifications itself; 1.1.0 keeps working. Details in Push alerts and summaries below and docs/push_notifications_runbook.md.

---

Shipped 2026-10-16: notifications that do what they say

Pushes were silently dropped by default (a hidden 'daily' cadence let one through per 20 hours), signing out never unhooked the phone, bell clicks didn't open the post, and many settings did nothing. Now pushes go as they happen by default, daily and weekly summaries and quiet hours hold updates instead of dropping them, the phone follows the signed-in account, every bell, archive and push link opens the post, only switches that work are shown, emails have one-click unsubscribe, and times are in the recipient's clock. Details in Push alerts and summaries below and docs/push_notifications_runbook.md.

---

Shipped 2026-10-16: member votes from the official roll calls

GovTrack started refusing our requests (fetch failures from October 3, 403s from October 15), which emptied every profile's Votes tab, party-line figure and Compare's shared votes. Votes now come from stored House Clerk and Senate roll calls, synced in the background with ten years of history; the party-line figure now counts the current Congress's party-split votes, the same way for every member. Details in Roll-call votes below and docs/bills-data-spike.md. Screenshots in docs/screenshots/member-votes-official/.

---

Shipped this session — 2026-07-28 → 2026-08-21 (Claude Opus 5)

Thirteen commits on Updates_and_fixes, all pushed. Tip 718f5ab.

Demo sunset (PRD docs/demo-sunset-and-migration-prd.md)

• ad7ae91 — increment 2: dismissible dashboard card asking existing demo accounts for a contact email, PUT /me/contact-email (422s on a bad address, unlike signup which drops silently) + POST /me/contact-email/dismiss. Dismissal is a server column so it follows the account across devices.
• 3a10040 — increment 3: the dormant switch. services/entitlements.py (IDME_ENABLED, DEMO_SUNSET_AT, require_verified, require_subscribed) wired onto 8 endpoints, no-op until the flag flips. 19 tests in both states.
• 5623cd3 — increment 4: authored_verified snapshot columns on SEVEN tables (the PRD listed five; the two comment-reaction tables were an oversight). Verification is never retroactive — a demo account that later verifies must not relabel everything it wrote. Boot-time convergent backfill.

Florida election data — accuracy

• 1a6e892 — statewide fundraising re-sourced from the FL Division of Elections with per-account provenance. Donalds' "$67.0M" was a hand-typed literal with no committee ID; the real structure is a campaign account plus a separate PAC, and Florida publishes no candidate↔committee link, so any combined total is an editorial join and is labeled as ours. Also: Jerry Demings was still rendering as an active candidate (suspended 2026-06-05), and Burn Rate printed a fabricated "0%" from null / total.
• ce7a581 — Wikimedia portrait seeding with article validation (surname must appear in the title, extract must mention the state or office). 7 of 20 resolved, zero false positives — a stranger's face is worse than initials.
• e19cddd — CFO + Agriculture races added (they were absent, not empty). Fixed ContactTab rendering "WASHINGTON, D.C." over a Tallahassee official, and falling back to member.office, which on state records holds the branch classification "Executive". Reproduces on every state's Lt. Governor.
• 8fbc2bf — every FL legislator now has a portrait (40/40 Senate, 119/119 House); 6 statewide executives got sourced bios, experience, focus areas and real Capitol contact details.
• 9566463 — Aug 18 primary results + the un-narrowed ballot guard. 24 of 35 races were showing a fictional November ballot (FL-1 listed nine Republicans against each other). A general ballot holds at most one nominee per party, so 2+ of a major party now flags general_roster_unresolved and the UI refuses to present the list as a ballot. withdrawn filtering moved into _resolve_ids so no surface can forget it.

Trust + UX rules (all from Jeffrey's review)

• 2b8303d + 1659007 — links never silently download. A .txt citation led to finding 173 Mississippi legislators with a raw .xml and 120 Vermont legislators with a district-map .pdf in contact.official_website. All 293 relocated. frontend/lib/externalLink.js labels file links; components/ui/FileLink.js asks before any download starts — a label is not consent. Ordinary pages never prompt, or the prompt becomes noise.
• 718f5ab — dropdown memory. There was none: navState.js covers only page-level "where am I", and ElectionCard was passed defaultOpen={idx===0}, force-opening the primary on every mount. New frontend/lib/disclosureState.js stores choices, not states (snapshotting every value would freeze today's defaults into every browser forever) and keys describe the thing, never its position. Primary results now collapse, with the winners still on the header.

---

Shipped this session — 2026-07-24/25 (Claude Fable 5)

• Notifications v2 complete (4 parts). Part 1 honest delivery-channels panel (7b0396d): SMS row removed permanently, badges match reality. Parts 2–4 (01eb4f4 + ruff fix 2e85866): account-synced channel prefs (CitizenAccount.notification_prefs_json + GET/PUT /me/notification-prefs; server wins on sign-in, 700ms debounced sync, payload carries tz_offset_minutes); anonymous tracked pushes (DeviceToken.tracked_json/prefs_json/last_push_at; /api/push/register accepts tracked+prefs; fan-out reaches citizen-less devices); quiet-hours + cadence enforcement in the send path (suppress, don't queue — Jeffrey's call; nights 22:00–08:00 local via tz offset, daily ≥20h / weekly ≥6d min-gap; no prefs blob = no suppression). Corrected 2026-10-16: every registration and sign-in sends a prefs blob, so the defaults applied to everyone and the daily min-gap dropped pushes silently. The min-gap is gone: pushes go as they happen by default, and daily, weekly and quiet-hour pushes go out as one summary.
• Desktop PWA (4620059). civicview.app is installable on Windows/macOS/Linux/ChromeOS: the manifest's SVG-only icons (which fail Chromium's install check) got real 192/512 PNG + maskable icons from the brand masters; minimal service worker (no fetch handler — future Web Push landing pad); registration skips the native shell; apple-touch icon fixed (iOS ignores SVG).
• Microsoft Store: SUBMITTED, in certification (2026-07-25); LIVE since mid-September 2026. Partner Center company account CIVICVIEW, INC. verified same-day via DUNS 146473171 (registration now free); name reserved; PWABuilder .msixbundle v1.0.1.0 uploaded (runFullTrust justified as standard PWABuilder template); US-only market, Free, ESRB Teen, gen-AI declared YES, block-users NO. Product-identity values + full runbook: docs/microsoft_store_listing.md (0debcbc) + Pinecone. 10 store screenshots + poster/box art in App store screenshots\_Upscaled\Desk top\store-ready\. Auto-publishes on pass; post-cert checklist in the runbook §6.
• Five app updates (2cb77a9). (1) Map zoom slider is desktop-web only — compact viewports + native app get a percent-only chip; (2) bill NAMES on /bills (Clerk <vote-desc> captured; all recent House rows enriched concurrently; dropdown/card/search show titles); (3) Text/✨AI vote search on /bills for both chambers (corpus = 50 recent votes via /api/ai/filter-items); (4) force-update gate: (env / , both unset = inert) + — hard full-screen block below min, dismissible nudge below latest, fail-open everywhere; (5) push opt-in card now also triggers on first track (any of the three stores, works signed-out).

---

Shipped this session — 2026-06-16 (Claude Opus 4.8, 1M)

• Dashboard tracked redesign. New three-tab dashboard (Overview · Manage Tracked · Account & settings). Extracted a shared components/TrackedManager.js (used by BOTH the My Tracked nav window and the Manage Tracked tab — capped/scrolling sections, search, chips, per-item alerts, a star "feature" toggle, clickable official cards). Overview is now four "Followed X" spotlights (rep / candidate / election / bill), each showing the one pinned item + its latest updates. Featured picks are account-synced via a new featured_tracked table (one row per category, UNIQUE constraint) + GET/PUT /api/tracked/featured + lib/featuredTracked.js. My Tracked window gained an "Open in dashboard →" button; subtitle corrected to "synced to your account".
• Profile About + Experience data. Added neutral, cited bio + current-office-led experience to: the executive branch (President, VP, 15 Cabinet secretaries), all 9 SCOTUS justices, 13 congressional-leadership entries (federal_officials.json), and the full U.S. delegations of FL (30), TX (40), CA (54), NY (28), PA (19) — 171 member bios in congress_profiles.json. Current role/year is roster-derived with chamber-aware, gap-aware logic (Schiff "senator since 2024", Sessions "since 2021"); prior roles curated + cited to bioguide.congress.gov. (The generated candidates.json bios were boilerplate — not reused.)
• Google Play — LIVE in Production (versionCode 3, v1.0.2), after clearing three Misleading-Claims rejections. (1) 2026-06-27: on-device launcher icon ≠ store hi-res icon (the AAB had shipped the default Capacitor placeholder because capacitor-assets generate was never run) — fixed by adding real brand masters to frontend/assets/ (from Logos & emblems/civicview_logo_solo.png) and regenerating icons; bumped versionCode 2→3, v1.0.1→1.0.2. (1b) same date: description lacked sources + a government disclaimer — added a "⚠️ NOT A GOVERNMENT APP" disclaimer. (2) 2026-07-05: "Insufficient Sources" — the "primary sources include…/where available…" hedging implied a partial list; rewrote "WHERE OUR INFORMATION COMES FROM" as an exhaustive list (congress.gov, GovTrack, @unitedstates project, House Clerk, Senate, federalregister.gov, CourtListener, fec.gov, openstates.org, Google Civic, Census geocoder, OpenStreetMap) + a Wikimedia photo credit, ending "we use no other sources." Store-listing source of truth: docs/playstore_listing.md. App verified (green ✓), managed publishing OFF, US-only, category Social, org account (exempt from the 12-tester gate), Android developer verification COMPLETE. Appeal note held in reserve at .

Shipped this session — 2026-06-10 (Claude Fable 5, 1M)

• Full standard audit (parse / smoke-import / tests / secrets / lint / feature review): verdict healthy. Repaired the two failing test files — test_official_votes.py had stale list-parser expectations from the intentional 19e77ca Senate-bill fix; test_tracked_cross_account.py predated the CSRF middleware and now derives + sends X-CSRF-Token exactly like the frontend. All 9 test files green. Lint 73 → 2 findings (both intentional E402s). Removed 2 unused imports.
• Citizen dashboard reorg (Task #102): split into Overview (My Reps, Upcoming, Recent, My Polls, Saved) and Account & settings (2FA, verification, billing, start page, demographic profile, hidden-by- moderation) views. Civic content now leads on every viewport — the four account sections no longer push My Representatives below the fold on mobile. Quick links "Account settings" now goes somewhere real.
• Start-page preference (Task #102): citizens choose which surface CivicView opens on (Home / Polls / Posts / Bills / Dashboard / Stats). CitizenAccount.start_page (nullable, auto-migrates) + allowlisted PUT /api/citizen-auth/me/start-page + StartPageSection in dashboard settings + once-per-session redirect in app/page.js (explicit URL params always win; sessionStorage guard).
• Expanded /stats page (Task #71 — DONE): new GET /api/stats/detail (60s TTL cache, separate from /summary so home stays fast) — identity / engagement / content-library counts, 8-week signup + poll-vote trends, citizens-by-state. Frontend page rebuilt with loading + error + retry states, CSS-only charts, all numbers live or structural (none fabricated).
• UX fixes from the audit: /bills navbar "Tracked items" + "Dashboard" now deep-link via /?open=tracked|dashboard|settings instead of dead- ending on home; /polls infinite scroll failure now shows a tap-to-retry button instead of silently ending the feed.
• Engagement rate limiting (Task #101 — DONE): shared sliding-window limiter (services/rate_limit.py) + EngagementRateLimitMiddleware (30 writes/min on comments/reactions/votes/reports, 10/10min on poll/post creation, keyed by session token); demo-signup limiter migrated onto the same mechanism (5/24h per IP unchanged).
• Weekly civic digest (Task #104 — DONE, sending gated): opt-in Saturday email (tracked officials' posts/polls, polls closing, district events) via Postmark; DIGEST_ENABLED env flag is OFF until Jeffrey flips it in Render; demo-domain addresses never sent to; preview endpoint + Settings card with live preview.

Shipped this session — 2026-06-05 (Claude Opus 4.8, 1M)

• Optional Poll Demographic Forms — complete (P0+P1+P2). Poll creators can attach an optional standardized demographic form (11 single-select questions; sensitive categories flagged + consent-gated). Voters answer optionally (replace-on-revote until close). "Explore results" inline explorer with geography + demographic filters and a break-down-by cross-tab (inline-SVG grouped bar chart) + aggregate CSV export. ALL suppression server-side: k-anonymity MIN_CELL=10 with per-poll creator override (25/50/100). Reusable opt-in citizen demographic profile (sensitive keys never persisted). New models PollDemographicQuestion / PollVoteDemographic / CitizenDemographicProfile + Poll.min_cell_override; services/demographics_catalog.py + services/poll_demographics.py + routers/poll_demographics.py; frontend PollResultsModal / PollDemographicsPicker / PollDemographicsForm / DemographicProfileSection wired into every poll surface. Tests green. PRD: docs/polls-demographic-forms-prd.md.
• Multi-state election candidates (#96 partial): TX, CA, NY, PA candidates.json + elections.json generated via backend/scripts/build_state_federal_candidates.py (config-driven: state key dates, closed-primary flags NY/PA, NY ballot measures, Senate-cycle gating; federal incumbents enriched from sourced profiles, challengers FEC-facts-only). Re-run playbook persisted in Pinecone.
• Crowdfunding pivoted GoFundMe → Indiegogo. docs/indiegogo_draft.md (moved out of the repo on 2026-09-24, with the rest of the business working files) is FINAL (Flexible funding, $25K, 35 days, 4 perks w/ Dec-2026 delivery, FAQ, launch checklist, share copy, video script). Financial model gained an isolated one-time crowdfunding block (Assumptions rows 68–75: ~8% fees → ~$23K net; NOT wired into recurring P&L). Campaign art to Indiegogo spec in ../Indiegogo images/ (21:6 text-free cover, square logo thumbnail from the official glyph, 4 escalating reward-tier images).
• Mobile map fixes (3): open/closed state now persists correctly across reloads/navigation (localStorage written ONLY from resizer gestures + degenerate-viewport guard, app/page.js); desktop-layout first-paint flash killed via pre-paint viewport measurement (lib/useViewport.js); map camera re-asserts its intended target after container resizes settle (intendedCameraRef + debounced ResizeObserver, components/MapView.js).
• KIE API evaluated → Task #100. api.kie.ai/claude/v1/messages is an Anthropic-native drop-in; measured Haiku 4.5 ≈ $0.27/$1.45 per M tokens (~72% off) but 2.9–5.6s latency. Decision: build the provider flag, keep it OFF; user-comment classification stays on official Anthropic regardless.

---

Shipped this session — 2026-06-03 (Claude Opus 4.8, 1M)

Federal + state DATA layers were committed/pushed earlier this session; the election-candidate work at the end may still be local — verify git status (uncommitted: backend/app/services/fec_service.py, backend/app/data/fl/candidates.json, backend/app/data/fl/elections.json).

• Federal officials — full neutral + sourced issue data. Every sitting member of Congress (both chambers, all 50 states + territory delegates, ~538 profiles) now has neutral, sourced top_issues in congress_profiles.json; executive branch, SCOTUS (as neutral "Areas of Focus"), and congressional leadership in federal_officials.json too. Committee auto-fill + sponsored-bill issue-area derivation + fix to the live bio/experience derivation (Congress.gov startYear/stateCode term fields). Fabricated/stale seed entries purged; SAMPLE_DATA Rick Scott bioguide fixed (S001227 → S001217).
• State legislators + governors — all 50 states. Built data/<state>/state_officials.json for every state from Open States bulk data (~7,355 legislators) + statewide executives; all 50 governors curated + sourced. Live state-legislator Bills/Votes wired (fixed the OpenStates /bills sponsor filter needing jurisdiction; added openstates_id fast-path) + a live AI-derived issue-areas endpoint (Haiku over bill titles).
• Florida Supreme Court via CourtListener (opinions; fixed the v4 docket__court filter; roster already curated).
• Address-to-rep / Google Civic. Confirmed federal/state lookup is fully off the retired Representatives API (Census + own data); fixed the state-legislative-district layer key; wired the free Divisions OCD-ID bridge into /lookup.
• Florida election candidates. New fec_service.py (OpenFEC): 156 FL federal candidates added with live fundraising; US Senate + all 28 US House district races added to fl/elections.json. All FL state candidates given overviews; the 6 Governor contenders + AG race fully curated from official campaign sites (issues/endorsements/experience/fundraising); withdrawn Josh Weil removed.
• Docs/financials. API_Research_Report.html: added CourtListener + IN-USE/PLANNED tags. /help-build + financial model: Vote Smart $4,850/yr optional add-on + Google Workspace Business Starter $8.40/mo. Gmail draft reply to Vote Smart declining the license for now.

Shipped this session — 2026-05-31 (Claude Opus 4.8, 1M)

Local/uncommitted unless pushed — Jeffrey decides the commits.

• Bills & Votes feature (new). Home-page "Bills" section (between Popular polls and Browse by state) + interactive /bills page: govtrack-style selectable seat hemicycle (Senate/House toggle, seat → mini-card → rep profile link), recent-vote selector, slate tally bar, inline AI vote explainer, deep-linkable vote URLs, and a "View the bill on Congress.gov" source link. Reachable via the navbar hamburger as "Floor Bills".
  • Backend: backend/app/services/official_votes_service.py (House Clerk EVS XML + Senate LIS XML parsers, lis→bioguide crosswalk, Congress.gov beta House Roll Call API integration, GovTrack fallback, caching) + GET /api/votes/recent and GET /api/votes/{vote_id}/members (backend/app/routers/votes.py). 51 offline parser assertions in backend/tests/test_official_votes.py.
  • Frontend: frontend/app/bills/page.js, frontend/components/bills/*, frontend/app/bills/bills.css, plus the home section in NationalOfficialsPanel.js and the navbar entry.
  • Docs: docs/bills-feature-prd.md, docs/bills-feature-design-handoff.md, docs/bills-data-spike.md (GO verdict, Congress.gov LIVE-validated).
  • Polish/fixes: slate tally tones (was harsh green/red), full member names in the list, small seats to fit state labels, tappable mobile seats, Senate chart top-clip fix, visible "Clear" button, mobile footer reorder, House vacancy caption (431), Senate menu date year-parse fix, House list newest-first ordering.
• Task #92 — done. Removed the inert executive/judicial branch chips from frontend/app/polls/page.js (see Pending table for the deliberate non-changes).
• Task #93 — increment 1. Added an archived read-only prop to the shared components/polls/CommentsThread.js (prep for consolidating the 3-way comment fork; increments 2 + 3 are scoped in the Pending table).

---

Shipped this session — 2026-05-28 (Claude Opus 4.8)

Local/uncommitted unless pushed — Jeffrey decides the commits.

• Task #16 — Save/favorite posts + polls to a dashboard "Saved" section (SavedItem model, /api/saved, viewer.is_saved, Save kebab on cards).
• Task #41 — Threat/incitement detection, Phase 0 (shadow mode) — verdicts logged, nothing hidden (docs/threat-detection-prd.md). Acting on verdicts is Task #49.
• Home "Popular polls" → shared FeedCard parity; /polls ?kind=rep candidate-leak fix; comments Edit/Delete/Report consolidated into the kebab on all three comment surfaces.
• Feed cursor pagination + infinite scroll on rep/candidate pages, /polls, and /posts.
• Map: desktop slider now matches the mobile chunky bar + a reset-view control (clicking outside the US also resets the camera).
• Rep profile: Bills tab search + an AI-search toggle on Bills + Votes (POST /api/ai/filter-items, scoped to the loaded set).
• Non-partisan neutrality hardening on the bill / EO / vote AI prompts, plus a one-time cache reset (backend/scripts/reset_summary_cache.py).

---

In progress

(Mirrored on /help-build under the "In progress" section.)

• Remaining state/local content: official photos for state legislators, state judiciary for the other 49 states, and LOCAL officials (sheriffs/judges/DAs/school boards). State legislators + governors for all 50 states are now seeded (Open States); federal issue-data is complete.
• Email deliverability hardening (SPF / DKIM / DMARC on civicview.app)
• Election-win promotion flow (admin UI surface — backend shipped)
• Crowdfunding launch — Indiegogo (final draft + cover/thumbnail/reward art ready). EIN obtained, business bank account opened, and Benefit Corp Amendment filed (Task #90 done) — campaign is ready to publish.
• App distribution: Google Play LIVE in Production (v1.1.0); desktop PWA live (installable from any Chromium browser); Microsoft Store LIVE since mid-September 2026 (post-cert checklist in docs/microsoft_store_listing.md §6).

---

Pending tasks (handed off to the next session)

Canonical open-tasks list. On session start, recreate every row below (plus the launch-sequence items) as a task in the Cowork Progress widget so the backlog carries across sessions. (CLAUDE.md instructs this read on every session start; Pinecone holds the per-session narrative.)

#	Task	Status	Notes
71	Build /stats expanded analytics page	done (2026-06-10)	Shipped: GET /api/stats/detail (60s in-process TTL cache, separate endpoint so the home hero stays sub-100ms) + rebuilt frontend/app/stats/page.js — government-structure constants, identity/engagement/content-library live counts, 8-week signup + poll-vote trend charts (CSS bars, zero-filled buckets), citizens-by-state top-15, explicit loading/error/retry states (no fabricated fallback). Future depth (growth curves beyond 8 weeks, verified-citizen coverage map) can extend the same endpoint.
84	Wrap web app into iOS + Android native via Capacitor	done (2026-06-12)	Capacitor remote-URL shell scaffold + app-store runbook committed (9fbbac0). Android organization account verified on Google Play Console (CivicView org, ID 5150866026642573505); next step is creating the app listing + first build upload. Apple Dev $99/yr + Google Play $25 paid. 2026-06-16: app SUBMITTED to Google Play Production review (status: In review); Child Safety Standards page (/child-safety) published to clear the CSAE declaration; Android developer verification confirmed complete.
90	File Articles of Amendment for Benefit Corp status	done (2026-06-12)	Filed with Sunbiz. Initial Profit Corp filing (#800474911808) processed; CIVICVIEW, INC. is ACTIVE; cr2e011 Articles of Amendment (Exhibit A statute cites §§607.601-607.613) filed. Language in the Benefit Corp filing language (kept outside the repo since 2026-09-24).
91	Evaluate Vercel AI Gateway for backend AI calls	pending	Post-launch / deferred. Not urgent: current AI (comment classification + post summaries in backend/app/services/ai_service.py) is single-provider Anthropic and already degrades gracefully. The Gateway's OpenAI-compatible endpoint makes adoption a base_url + key swap in ai_service.py (no SDK rewrite). Adopt when AI spend warrants cost/usage dashboards, when provider failover matters, or to mix models (cheap classification + stronger summaries). Pricing: $5/mo free credit, then provider list prices at zero markup (BYOK also no markup). Caveat: routing the summarize flow through the OpenAI-compatible shim instead of the native Anthropic SDK can change system-prompt / citations / prompt-caching behavior — re-test that one flow before switching.
92	Trim /polls + /posts filter cruft (audit follow-up)	done (2026-05-31)	Removed the inert + branch chips from + in (backend only emits for Congress reps, so those chips always counted ~0). Deliberately LEFT the // pipeline and the client-side state re-filter (~lines 313-319) intact — the original audit overreached: the re-filter guards a real refetch race, not dead work. Original audit 2026-05-28.

| 38 | Notifications v2 (honest panel · synced prefs · anonymous pushes · quiet hours) | done (2026-07-24/25) | All four parts shipped + pushed (7b0396d, 01eb4f4, 2e85866); see the 2026-07-24/25 shipped block. Enforcement is opt-in-by-sync: accounts/devices that never synced prefs keep pre-v2 behavior. Corrected 2026-10-16: in practice every app registration and every signed-in account syncs prefs, so the old defaults (quiet hours nights, cadence daily) applied to everyone and dropped pushes; see "Push alerts and summaries" below. | | 108 | Microsoft Store listing (Windows desktop) | LIVE since mid-September 2026 (submitted 2026-07-25) | PWABuilder MSIX shell of the live PWA; web deploys need NO store resubmission. Post-cert checklist in runbook §6 (clean-machine install test, Store badge next to the Play badge, README/HelpBuild "Already built" row). Identity values in Pinecone (2026-07-25-microsoft-store-identity). | | 109 | Force-update gate: arm when needed | shipped OFF (2026-07-25) | 2cb77a9. Gate is inert until APP_MIN_VERSION_CODE (hard block) / APP_LATEST_VERSION_CODE (nudge) are set in Render env + restart. Set LATEST when a new AAB ships (5 once 1.2.0 is at 100 percent); set MIN only when an old shell is genuinely broken (1.1.0 is not: the server still sends it the standard message). |

| 110 | Rebuild FL U.S. House rosters against the 2026 map | done (2026-09-24) | All 28 FL U.S. House races rebuilt on the 2026 map from the Division of Elections qualified-candidate list, with roster_status: verified_nominees, write-ins listed separately and incumbents only where they sit in the same district. Commit "fix(fl-data): rebuild Florida 2026 ballot from the official candidate list and certified results" in the 2026-09-24 audit series. | | 111 | Certify FL primary results + resolve FL-11 recount | done (2026-09-24) | Certified primary results recorded with a source link and shown as "Official results"; FL-11 recount outcome recorded (Joe Strada advances). Same commit as #110. | | 112 | Demo-sunset increments 5–7 | pending (5 blocked) | 5 — in-place ID.me upgrade path (blocked on the RP contract); 6 — fallback credential-transfer UI with audit log; 7 — sunset machinery (DEMO_SUNSET_AT countdown banner, T0/T-14/T-7/T-1 email cadence, soft-delete job, data export). Increments 1–4 are done and inert until IDME_ENABLED flips. | | 113 | Re-justify the paid tier (poll creation only) | pending (business decision) | Commenting moved from the subscriber tier to the verified tier (64ff2ab), so the $5/mo subscription now unlocks poll creation only. HelpBuildThisView.js:217 revenue projection (3% conversion, $1.8K Y1) and the Indiegogo draft (kept outside the repo since 2026-09-24):240-241 still lean on the old engagement bundle. Flagged, deliberately not silently edited. | | 114 | Privacy policy + terms: contact_email & deletion schedule | done without counsel; attorney review when affordable | The 2026-09-24 audit rewrote the privacy policy and terms to match the code (contact email, poll answers, recipients, deletion and retention, Florida law and Orange County venue, arbitration removed pending counsel). 2026-10-15: the privacy policy was rewritten again without an attorney (none affordable yet), checked line by line against the code and against California's CalOPPA contents (data and recipient categories, review and correction, change notices, effective date, Do Not Track, cross-site tracking) and Florida's 30-day breach notice; it offers access, correction, deletion, portability and appeal to every U.S. user, and the Terms now say 18 and older. Have an attorney review both when that becomes affordable. | | 115 | Automated FL Division of Elections finance ingest | pending | Today's state fundraising is curated with provenance, not automated. Path is confirmed: TreSel.exe?account=N returns per-period totals for candidates and committees, and the qualified-candidate list downloads as TSV keyed by a stable AcctNum. Caveat that shapes the design: the candidate↔committee mapping cannot be automated (the state's Affiliates field is empty for candidate-aligned PCs), so that join stays a human-signed-off table, not a scraper. | | 116 | Publish Android 1.2.0 (phone notifications) | pending (Jeffrey) | Build the signed AAB (versionCode 5), Internal testing on Jeffrey's phone with the device checklist, then a staged Production rollout; keep the 1.1.0 AAB and a tag to rebuild a 1.1.1 if a rollback is needed. Data safety changes listed in . | | 117 | State bill tracking + Open States bill updates | deferred (after November 3, Jeffrey) | State bills can't be tracked today (billKey is Congress only). Needs a new tracked type with its own key (Open States id), storage, My Tracked rows and bell links, then an Open States pass beside the Congress.gov one in . Until then no copy promises state bill alerts. | | 118 | Turn on web push (VAPID keys) and run the browser checklists | pending (Jeffrey) | Shipped OFF (2026-10-18, ). Run on your own computer; set , , on Render () and (the same public key) on Vercel Production, redeploy both, then run the iPhone (Home Screen app) and Windows app checklists in . Keep the pair in ; a new pair later ends every browser's subscription. | | 119 | One coded notification id in Android pushes | deferred (after November 3, Jeffrey) | Each FCM push now carries the kind of update and the ids that open it (an official's page id, a post, poll or event id, a federal bill's number, a state code, the bell row id), never names or text unless Show details is on; the privacy policy says exactly that (2026-10-18). A later Android build replaces those ids with one coded notification id the app looks up after the tap; then reword the privacy sentence. Web push is unaffected (encrypted payload). |

Closed: Task #58 (Add financial-model link to /help-build) — won't ship as a public link. The docs/civicview_financial_model.xlsx is already in the public GitHub repo for anyone who wants to audit the math; shared on request rather than surfaced as a download on the campaign or app surfaces.

---

Launch sequence

See docs/gofundme_draft.md for the full launch playbook with copy-paste share text + GoFundMe story + perk tiers + FAQ. High-level:

Phase 1 — free / cheap pre-work (do now):

• Postmark account + Server API token
• ✓ EIN application at IRS.gov — obtained (interim notice; official CP 575 arriving by mail ~mid-June 2026)
• ✓ Stripe in test mode — done (no EIN required — full subscription flow works with test card 4242 4242 4242 4242)

Phase 2 — corporate + banking (1-2 weeks):

• ✓ Sunbiz processed the initial Profit Corp filing — CIVICVIEW, INC. active
• ✓ File Benefit Corp Amendment (Task #90) — filed 2026-06-12
• ✓ Open business bank account — done (Mercury / Relay / Novo — 1-3 day approvals)

Phase 3 — launch the GoFundMe ($25K goal):

• Demo citizen system launches simultaneously so visitors can experience the full engagement model immediately (verified-quality features unlocked via demo grants — no waiting on ID.me)

Phase 4 — deploy GoFundMe proceeds in priority order:

1. First $2,400 → ID.me Relying Party application (the application itself requires the $2,400 setup fee upfront — campaign funds it)
2. Next $1,050 → USPTO trademark filing (classes 9 / 42 / 45)
3. Stripe live mode activation (after EIN + bank land)
4. Attorney review of ToS + Privacy Policy ($1.5K-$3K via Tier-2 solo attorney — see docs/LEGAL-REVIEW-ROADMAP.md)
5. Open States higher-volume API access (about $100/mo, to be quoted by Plural). The ProPublica Congress API shut down; bills and votes come from the free Congress.gov API
6. Remainder → Year-2 operating buffer

Phase 5 — transition demo cohort to verified accounts:

• Once ID.me is live, demo users get an opt-in "Verify my identity" CTA. See the Identity verification + demo migration plan section below for the carry-over-vs-start-fresh policy.

---

Identity verification + demo migration plan

The current build runs entirely on self-serve demo citizen accounts. Real verified citizen accounts ship once the ID.me Relying Party contract is funded.

When ID.me ships, demo users get an opt-in migration:

1. Demo user hits the new "Verify my identity" CTA (in the citizen dashboard or on any engagement surface that prompts for verification).
2. ID.me's flow runs in a popup / redirect. On success, ID.me returns a verified identity claim (legal name, address, etc.).
3. The CivicView frontend detects the demo session and presents a one-time choice:
   • Keep my demo activity — polls, votes, comments, and tracked reps carry over. The existing CitizenAccount row is updated in place (verified=True, display name + city + district reconciled against ID.me), and engagement surfaces stop labeling the user "Unverified."
   • Start fresh — the demo account is archived and a new verified CitizenAccount is created. Old polls / comments keep their original demo authorship attribution (no identity laundering); votes are wiped to avoid skewing historical poll results.
4. Default the toggle to "Start fresh" so accidental migration doesn't preserve abuse, but make "Keep" a one-click option so legitimate early users keep their work.

Why opt-in, not forced: Full migration is bad because demo accounts are self-serve and not identity-verified — forcing migration would attach real verified identities to whatever the demo account did. Full reset is bad because legitimate early users (your TikTok-live early adopters, friends who tested) lose their engagement history just for upgrading. Opt-in with a sensible default threads the needle.

Implementation note for the cutover:

• New endpoint POST /api/citizen-auth/verify-and-merge accepts the ID.me identity claim + a keep_demo_data: bool flag.
• Either updates verified=True on the existing row and reconciles display/geo fields, or archives the old row and creates a fresh one.
• A migration service function handles FK reassignment if we ever decide to migrate authorship attribution too (right now, archived old rows preserve attribution as-is).

---

Future product features

Captured for a future release — not in scope for current launch.

• Video posts on rep / candidate pages — verified reps + candidates attach video to posts (not just text + images). Needs transcoding pipeline (Mux or Cloudflare Stream), size cap, moderation queue tied into existing takedown / DMCA flow.
• Live-streamed town halls — first-class "Live" affordance: rep / candidate goes live, citizens get push notification (PWA stack already in place), stream archives back into post feed. Pairs with comment thread for live Q&A.
• 1-on-1 live debates between reps / candidates — request / accept flow where one official can challenge another to a scheduled debate. Surfaced on both pages + on the On-the-ballot home section while live. Same streaming + archival infra as town halls; the new piece is the invitation / scheduling state machine.
• Optional citizen nicknames — verified citizen picks a display nickname instead of their legal name on public surfaces. Verification still tied to real name + address (vote integrity + district scoping
  • abuse moderation preserved), but what the community sees is the user's choice. Pairs with a small "verified citizen" pill so a nickname reads as "verified, just doesn't want to publish their legal name."

---

IP / legal roadmap

Tracked here so it stays visible across sessions:

• Federal trademark filing for CivicView — three classes (9, 42, 45) at ~$350/class via USPTO TEAS Standard. Deferred until budget allows (Phase 4 of the launch sequence).
• Copyright registration with the US Copyright Office — $45-85 via the eCO portal. Deposit is first 25 + last 25 pages of source code. Worth doing once the codebase stabilizes after the next round of features.
• DMCA agent registration — $6 every 3 years at dmca.copyright.gov. Required for §512 safe-harbor on user-generated content. Pair with a clearly-posted takedown contact on the site.
• Florida Benefit Corp Amendment: Task #90 above, filed 2026-06-12. The Articles language is kept with the business files outside the repo.
• Attorney review of ToS + Privacy Policy — $1.5K-$3K Tier-2 path per docs/LEGAL-REVIEW-ROADMAP.md. Required before holding real subscription funds.
• Open-source carve-outs — if any subset of CivicView ever ships as an OSS library (e.g. design tokens or district-geometry helpers), spin into a separate repo with an OSS license rather than dual-licensing the monorepo.

---

Quick start

• Local dev: SETUP_GUIDE.md — run frontend + backend locally, test on a real phone via Wi-Fi or Tailscale.
• Production deploy: DEPLOY.md — Vercel + Render + Cloudflare DNS end-to-end walkthrough.
• Security setup: docs/SECURITY.md — env-var inventory, R2 / Postmark / Stripe / ID.me configuration.
• Email deliverability: docs/EMAIL-DELIVERABILITY.md — SPF / DKIM / DMARC setup for Postmark + Resend on Cloudflare DNS.
• Incident response: docs/INCIDENT-RESPONSE.md — runbook for compromised admin, DB breach, DDoS, credential leak.
• Fundraising: docs/gofundme_draft.md — full GoFundMe campaign package (story, FAQ, tiers, share copy, launch checklist).
• Android build: Gradle 8.14.3 + AGP 8.13.0, verified building on Android Studio Quail 4 as of 2026-09-13. The Gradle JDK must be Java 17–24 — currently Microsoft OpenJDK 21. Studio's own bundled runtime is Java 25, which is one release past what Gradle 8.14.3 supports, so a fresh Studio install fails sync until the Gradle JDK is pointed at a real JDK 21. Fix the JDK, never the Gradle version; see CLAUDE.md for the two decoys that make this look already-fixed when it isn't.

---

January turnover

Each odd-numbered January a new Congress is sworn in (the 120th at noon Eastern on January 3, 2027) and most legislatures seat new members. docs/january-turnover.md is the checklist: what switches by itself, then the state refresh below, the federal roster refresh (backend/scripts/refresh_congress_roster.py), and the checks.

---

Push alerts and summaries

One settings list (the bell's Settings, or Dashboard, Account & settings, Notifications) decides, per kind of alert, whether it reaches the bell, the phone or email: Officials you track, Events, Replies to your comments, Bill updates (federal bills, from Congress.gov), Poll results, Election reminders, Changes to pages you track, and the Weekly email digest. The server enforces it on every send path. Mute in My Tracked silences one official. Push alerts: As they happen (the default), Daily summary (6 p.m. local) or Weekly summary (Saturday 10 a.m. local) for officials, events, bills and poll results; nothing is dropped, and quiet hours hold pushes for one summary when they end. Election reminders always come on their own. On Android each kind has its own notification channel, and a notification, locked phone or not, shows only a neutral line unless the person chooses Show details. Since 2026-10-18 browsers, the iPhone Home Screen app and the Windows app get the same pushes by web push (services/web_push.py, public/sw.js, lib/webPush.js), under the same rules. A phone or browser is bound to whoever is signed in on it and unbound on sign-out. Emails a person can turn off carry a one-click unsubscribe (RFC 8058) that turns off only that email type. How it works, the release steps, Data safety and the device checklist: docs/push_notifications_runbook.md; the email side: docs/EMAIL-DELIVERABILITY.md 2.6.

---

Election reminders

Reminders before voting deadlines and Election Day are built from each state's backend/app/data/<state>/elections.json alone: a state is covered once its reminder dates have official sources. The format, the source and retrieved-date rules and an example are in docs/election-reminders.md. Sending is off until ELECTION_REMINDERS_ENABLED=true is set on Render; check Admin, Election reminders first.

---

Site notice

The privacy policy and the Terms promise a notice on CivicView at least 30 days before a material change. Set SITE_NOTICE_TEXT on Render (and optionally SITE_NOTICE_URL, a "Read more" link such as /privacy or a full https:// address) and a small banner appears at the top of every page on the site and in the apps; unset the text to take it down. Each browser can dismiss it once per notice: a new text or link shows again. Served by GET /api/app/notice (backend/app/routers/app_meta.py), shown by frontend/components/SiteNoticeBanner.js.

---

Roll-call votes

Every member's Votes tab, the party-line figure, Compare's shared votes and the /bills seat chart read stored roll calls from the official records: the Clerk of the House (clerk.house.gov/evs/{year}/roll{NNN}.xml, counted through Congress.gov's /house-vote API) and the U.S. Senate (senate.gov vote menus and per-vote XML). GovTrack is not used anywhere (it began refusing our requests in October 2026).

• Tables: roll_calls, roll_call_positions (one row per member per vote, with the member's party on that vote), roll_call_choices (who each member voted for in an election of the Speaker, shown as "Voted for {name}" for every name alike), roll_call_members, roll_call_sync_state. Created by the boot auto-migrate.
• The sync (backend/app/services/roll_call_sync.py) runs in the API process, never on the boot path: first pass two minutes after boot, then hourly from 9 a.m. to midnight Eastern on weekdays and every 6 hours otherwise. It fetches only roll calls that are not stored yet, newest first, and holds a Postgres advisory lock so two instances during a deploy cannot both run it. Each pass writes one log line starting Roll-call sync:. A site that fails five times in a row is left alone for the rest of the pass, and after three passes with no progress on history the sync goes back to the normal schedule; both are logged. On by default in production only (off in tests and local runs).
• History: ten years (the current Congress and the four before it, 2017 onward), filled in 25-minute chunks with 5-minute breaks after the current Congress is complete. About 9,000 requests and 300 MB. ROLL_CALL_BACKFILL_CONGRESSES changes the number of Congresses (default 5). Nothing stored is ever deleted.
• Check it: GET /api/admin/roll-calls (admin sign-in) lists each session's official and stored counts, what was added in the last 24 hours and the last pass. ROLL_CALL_SYNC_ENABLED=false turns the sync off in production; =true runs it anywhere else.
• What a request may fetch: nobody can make CivicView crawl the official sites. /api/votes/recent answers only for sessions in the stored window, and reads a past session from storage; an unstored vote is fetched on request only inside the window, for a session not yet complete, and not far beyond the highest stored number.
• The party-line figure counts the current Congress's roll calls on which most Republicans and most Democrats voted on opposite sides (party-split votes), and shows how often the member voted with most of their own party. Present, Not Voting and elections of the Speaker are left out; at least 10 such votes are needed. The same method for every member; independents get no figure (roll_call_store.party_line). A member who changed party, in either direction, is measured only on the votes cast in their current party (the party on their most recent vote); if that is independent, no figure (Jeffrey, 2026-10-16).
• vote_id: h-{congress}-{session}-{roll} / , the same on /bills and on profiles, so the vote explainer caches one explanation per roll call and builds it from the stored record.

---

Refreshing state officials

The 50 backend/app/data/<state>/state_officials.json files (state legislators, governors and statewide executives) are refreshed from Open States by one script. Run it whenever legislatures change, and always in January, after the new legislatures are sworn in.

cd backend
python scripts/refresh_state_officials.py --all              # dry run: prints the report, writes nothing
python scripts/refresh_state_officials.py --state TX --state NE   # some states only
python scripts/refresh_state_officials.py --all --write      # write the files
python scripts/build_photo_credits.py --write                # only if a Wikimedia photo changed
python tests/test_data_lint.py

It needs git and network access. The source is the openstates/people repository (public domain, CC0 1.0), cloned shallow into a temporary folder; seats per district come from openstates-core. The Open States API is used only when a person is missing from the repository.

How it treats the data:

• People are matched by openstates_id. The same person in the same seat keeps their id and every hand-curated field (photos and photo credits, bios, capitol offices, sources).
• A new person gets a new id: the seat id plus their family name, e.g. tx-sen-4-ligon. An id is never handed to a different person, because posts, claimed pages, citizen polls and follows are keyed on it. Ids that leave the roster are kept in each file's _retired_ids so they are never reused.
• Vacant seats go in a vacancies list on each chamber. The app does not show them yet.
• A new governor or statewide executive gets a record with no bio, and the report says so.

The report lists, per state: added, removed, changed (name, party, district), vacancies, anything unverified, and fields left empty.

January checklist:

1. Dry run with --all and read the whole report.
2. Confirm every new governor and statewide executive on the official state website, and write a short neutral bio with sources in the style of the existing ones. Never copy campaign language.
3. Confirm party changes, and anything else marked unverified, on the legislature's own website.
4. Write and commit in batches of about ten states, so one bad batch is easy to back out.
5. Check that incumbents in the CA, NY, PA and TX candidates.json and elections.json still point at sitting people. Do not regenerate those files with build_state_federal_candidates.py.
6. Rebuild photo credits if a Wikimedia photo changed, then run tests/test_data_lint.py and python -m pytest.

---

License

CivicView is proprietary software. All source code, designs, content, and assets are © 2026 Jeffrey De La Nuez. All rights reserved.

No part of this repository may be copied, modified, distributed, or otherwise used without the express written permission of the copyright holder. See LICENSE for full terms.

For licensing inquiries: [email protected]