Alethical

From Aletheia (Greek: truth/unconcealedness) + ethical — sits at the intersection of truth and technology, committed to transparent governance and moral clarity. Born of an era of misinformation and political opacity, it redefines civic intelligence by grounding every insight in verifiable data, and answers the independent movement's call for accountability amid a broader moment of democratic renewal. Built in Minnesota — chosen for its civic engagement and political balance — Alethical serves as the pilot for a new era of legislative transparency.

Mission

To make legislative truth visible, actionable, and accessible — enabling citizens, journalists, and legislators to engage with verified, transparent data.

Vision

A world where legislative processes are open, comprehensible, and accountable — starting with Minnesota as the pilot for a national transparency movement.

Repository Layout

Organized as a small monorepo with separate application, backend, and documentation areas.

• alethical/: Python backend package for the API, database, ingestion runtime, migrations, and backend tests.
• alethical/tests/fixtures/: JSON fixtures used only by tests and deterministic local demo seeding.
• apps/frontend/: Expo React Native app. The MVP ships the web target; iOS and Android are post-MVP (see docs/product-onboarding/product-scope.md).
• scripts/: Repo-level Python utilities for loading data and validating queries.
• docs/: Product, design, architecture, validation, and local-development notes.

Common Commands

just format
just lint
just migrate
just up
just down

just up starts Postgres, the FastAPI backend, and the Expo web frontend. By default, the API is available at http://localhost:8000 and the frontend at http://localhost:19006.

Frontend dependencies are managed with pnpm 10.33.0 from the repository root:

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm --dir apps/frontend run build

pnpm-workspace.yaml enforces a seven-day minimum release age for all resolved packages.

Authenticated frontend features use Supabase Auth. For local browser sign-in, set these environment variables before starting the frontend:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_PUBLISHABLE_KEY=sb_publishable_...
EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

Copy .env.example to .env at the repo root and fill in your values. That template documents every variable the backend, ingestion pipeline, and frontend read, with safe defaults for everything except the secrets you must supply (Supabase keys, OPENAI_API_KEY). The backend loads .env from the repo root automatically, and the Expo frontend reads the same file for its EXPO_PUBLIC_* values. Keep the EXPO_PUBLIC_* values publishable-only; never put service-role keys in frontend environment variables.

Alethical supports desktop and phone browsers. Native iOS and Android publishing is paused. The native restart notes retain the recovery point and requirements for future work; ordinary website setup needs no native publishing tools.

Manual Supabase setup:

1. In Supabase, go to Authentication > Providers > Google and enable Google.
2. In Google Cloud Console, create or select an OAuth client for the app and add Supabase's Google callback URL from the Supabase Google provider screen.
3. Copy the Google client ID and client secret into the Supabase Google provider settings.
4. In Supabase Authentication > URL Configuration, set the site URL to the deployed web app URL when production is ready.
5. Add redirect URLs for local and production browsers: http://localhost:19006/**, http://127.0.0.1:19006/**, https://www.alethical.com/**, https://alethical.com/**. Do not add any other host: a redirect target that is allow-listed here is a host Google sign-in will return people to.
6. If you use a different local Expo web port, add that exact wildcard origin too, for example http://localhost:19007/**.

If a port is already in use, override it when starting Compose:

BACKEND_PORT=18000 EXPO_PUBLIC_API_URL=http://localhost:18000 just up