Pathfinder — Government Services Navigator

AI-powered navigation agent that guides users through complex government web portals (FAFSA, Medicaid, etc.) using Amazon Nova: observation and automation (Nova Act), reasoning (Nova 2 Lite), and real-time voice (Nova 2 Sonic).

Hackathon: Amazon Nova AI Hackathon — Category: UI Automation | Secondary: Best Student App
Submission deadline: March 16, 2026, 5:00 PM PT

Problem

Government portals are confusing and hostile to the people who need them most. Pathfinder is the knowledgeable friend in the room: it sees your screen, explains jargon in plain language, and walks you step-by-step—with optional automation only when you confirm.

Tech stack

• Backend: Python, FastAPI, AWS Bedrock (Nova 2 Lite, Nova 2 Sonic), Nova Act (UI observation/automation), DynamoDB
• Frontend: React, TypeScript
• Safety: PII Guard on all model outputs; no extraction or storage of personal data

Repo structure

backend/     # FastAPI, Nova clients, PII Guard, session/knowledge store
frontend/    # React app (guidance panel, voice controls)
docs/        # Architecture, runbooks
knowledge/   # FAFSA knowledge base seed data

How to run

Backend (Python 3.10+):

cd backend
python -m venv .venv
.venv\Scripts\activate   # Windows
pip install -r requirements.txt
# Set AWS credentials (and optional .env: BEDROCK_REGION, NOVA_LITE_MODEL_ID)
uvicorn main:app --reload

API: http://localhost:8000 — GET /health, POST /session/start, POST /guidance, GET /session/{id}/state.

Frontend:

cd frontend
npm install
npm run dev

Open the dev URL (e.g. http://localhost:5173). Use the proxy so the app calls the backend at /api. For a different backend URL set VITE_API_URL.

See docs/architecture.md for architecture, API list, DynamoDB setup, and demo checklist (3-minute video, #AmazonNova).

Production

• Set CORS_ORIGINS to your frontend origin(s), e.g. https://app.example.com (no wildcard).
• Set ENV=production to disable API docs and tighten behavior.
• Copy backend/.env.example to backend/.env and configure AWS and CORS.

CI/CD

• CI (.github/workflows/ci.yml): on push/PR to main or master — backend lint (Ruff), security (Bandit, Safety), tests (pytest); frontend lint (ESLint), typecheck (tsc), build.
• CD (.github/workflows/cd.yml): builds backend and frontend and uploads artifacts; add a deploy step for your target (e.g. AWS Amplify, S3 + CloudFront, Lambda).

License

MIT