Guardian

ESL-friendly study tool for Alberta's Basic Security Training (ABST) provincial licensing exam. Combines a visual-novel shift simulator with an integrated bilingual manual reader (English / Plain English / Hindi + conceptual bridge note). 24-hour AWS hackathon project.

Demo language: Hindi (Punjabi as alternate; current content is Hindi).

Architecture — Path 1 + Drill

RAG-out (panel content is hardcoded JSON, not retrieved) plus the /drill endpoint from the dashboard. Only two Bedrock touchpoints, both Claude Haiku.

┌──────────────────────────────────────┐
│  Frontend (Vite + React + TS)        │
│  Amplify Hosting                     │
│  - Status bar / Scene / Dialogue     │
│  - BilingualPanel (3 tabs)           │
│  - FailureCascade · FieldReport      │
│  - ShiftDashboard · DrillChat        │
└────────────────┬─────────────────────┘
                 │ fetch (JSON over HTTPS)
                 ▼
┌──────────────────────────────────────┐
│  API Gateway (us-east-1)             │
└────────────────┬─────────────────────┘
                 │
   ┌─────────────┼──────────────┬──────────────┐
   ▼             ▼              ▼              ▼
┌────────┐  ┌──────────┐  ┌───────────┐  ┌──────────┐
│Lambdas │  │ Bedrock  │  │    S3     │  │ Bundled  │
│(Node20)│──│ (Haiku)  │  │ (assets)  │  │  JSON    │
└────────┘  └──────────┘  └───────────┘  └──────────┘
   │             ▲
   │             │ /generate-feedback
   │             │ /drill
   │
   ├── GET  /scene/:sceneId
   ├── GET  /manual-section/:sectionId
   ├── POST /grade-field-report     (pure logic, no AWS)
   ├── POST /generate-feedback      (Bedrock Haiku)
   └── POST /drill                  (Bedrock Haiku)

Stateless. No database, no user accounts, no sessions. Frontend holds all UI state in memory. Refresh restarts the demo.

No RAG. No Knowledge Base, no OpenSearch. Panel content (Manual / Plain English / L1) is hand-authored JSON in content/.

Decisions log: see docs/Design_Decisions.md. API contract: docs/api_contract.md. Wireframe: docs/wireframe.html. Drill spec: docs/Drill_Feature_Addition.md.

Repo layout

guardian/
├── frontend/   # Vite + React + TS + Tailwind + shadcn/ui
├── backend/    # Python 3.12 single-file Lambda, deployed via AWS Console
├── content/    # scene_backpack.json, panel_494_1_a.json — source of truth
├── assets/     # placeholder dirs for backgrounds, portraits, audio
├── docs/       # design decisions, API contract, wireframe, drill spec
└── scripts/    # sync-content.mjs

Setup — frontend dev

npm install                  # installs both workspaces
npm run dev:frontend         # http://localhost:5173

In dev, the API client (frontend/src/api/client.ts) loads content/*.json directly from local imports — no AWS needed. To point at a deployed backend, set VITE_API_BASE in frontend/.env.local:

VITE_API_BASE=https://abc123.execute-api.us-east-1.amazonaws.com/prod

Setup — backend dev

The backend is a single-file Python 3.12 Lambda deployed manually via the AWS Console. See backend/README.md for zip-and-upload steps and smoke tests.

Setup — content / polish dev

Edit content/scene_backpack.json or content/panel_494_1_a.json, then:

npm run sync:content         # copies into frontend/src/content/ and backend/src/content/

Asset files (backgrounds, portraits, audio) are listed in assets/README.md. Drop them in the matching subdirectory; they get uploaded to S3 at deploy time.

Hour-by-hour build plan

From docs/api_contract.md §7:

Hours 0–2

• Backend (Hoss): Bedrock model access; SAM init; /scene and /manual-section working from bundled JSON.
• Frontend: scaffold renders; StatusBar + SceneZone + DialogueZone wired up against local JSON imports.
• Content/polish: lock Hindi panel content; review checklist done.

Hours 2–4

• Backend: /generate-feedback and /drill calling Bedrock Haiku with prompt templates.
• Frontend: BilingualPanel with three tabs + vocabulary popovers; failure cascade transitions.
• Content/polish: backgrounds + NPC portraits in actual UI sizes.

Hours 4–5

• Frontend: replay flow; FieldReport UI; ShiftDashboard; DrillChat (drill feature).
• Backend: deploy to AWS; CORS verified; latency tested end-to-end.
• Content/polish: failure cascade visuals (CPS report, SSIA letter, stamp).

Hours 5–6

• Polish, demo rehearsal, pitch deck. Architecture diagram, demo script.

Constraints (locked)

• Demo target: desktop, 1280px viewport. No mobile.
• Hard rule: panel never covers the scene. Side panel only.
• Demo path: Path B — fail beat one, replay with panel, correct, fade before beat two.
• Real spaced-repetition: v2. Demo shows "+N rules added to your queue" affordance only.