Repository Guidelines

Project Structure & Modules

• frontend/: Vite + React app. Entry in src/main.jsx, UI in src/App.jsx, styles in src/styles.css, config defaults in src/config.js, API helpers in src/api/client.js, and token helpers expected in src/lib/token.js (imported by App.jsx).
• frontend/template.yaml and vite.config.js: SAM + Vite build/deploy config for the static site.
• backend/: FastAPI Lambda. Core logic in app/main.py, dependencies in requirements.txt, SAM stack in template.yaml.
• Root scripts: deploy-frontend.ps1, deploy-backend.ps1, and docs in README.md and DEPLOY.md.
• Live deployment details are tracked in DEPLOYMENT_STATUS.md; reference it before changing stack names, regions, or secrets.

Build, Test, and Development Commands

• Frontend: cd frontend && npm install && npm run dev (local dev server), npm run build (Vite prod build), npm run preview (serve built assets).
• Backend: cd backend && python -m venv .venv && .\.venv\Scripts\Activate.ps1 && pip install -r requirements.txt to bootstrap; uvicorn app.main:app --reload for local API, sam build then sam deploy ... for packaging.
• Deploy helpers: PowerShell scripts in the repo wrap the SAM deploy steps for each stack.

Coding Style & Naming Conventions

• JavaScript/React: ES modules, functional components, hooks. Prefer named exports for utilities. Keep components in PascalCase.jsx, helpers in camelCase.js. Use Vite env vars (import.meta.env) with VITE_ prefix.
• Python: FastAPI style with type hints and dependency injection. Functions and variables in snake_case; constants in UPPER_SNAKE_CASE. Avoid global state beyond cached JWKS.
• Formatting: Follow existing spacing/quote style (double quotes in JS, 4-space indents in Python). Run Prettier/Black if added later; none enforced yet.

Testing Guidelines

• No automated tests ship yet. For backend changes, add lightweight FastAPI route tests (e.g., pytest + httpx) and verify token failure/success cases. For frontend, add React/Vite tests (Vitest/RTL) around token parsing and API client behaviors.
• Manual checks: run npm run dev with a sample ?sso_token= query, and hit /health, /greeting, /me locally via uvicorn.

Commit & Pull Request Guidelines

• Commits: short imperative titles (“Add token decode helpers”). Keep related changes together; avoid large mixed commits.
• PRs: include summary, testing notes (commands run), and any screenshots of UI changes. Link related issues/tickets. Call out env var or infra parameter changes (VITE_API_BASE_URL, CUSTOM_ISSUER, ALLOWED_ORIGINS, etc.).

Security & Configuration

• Never commit real tokens or AWS secrets. Use .env for frontend overrides and stack parameters for backend secrets. Ensure AllowedFrameAncestors/CORS settings remain restricted to the Doc Viewer origin.
• Token handling: keep getTokenFromLocation, decodeClaims, and auth header construction in src/lib/token.js pure and side-effect free; all backend calls must include the bearer token.