Comprehensive Outdoor Playspace Audit (COPA) Tool (Frontend)
Enterprise-grade frontend for the Comprehensive Outdoor Playspace Audit (COPA) Tool.
This app is part of a hierarchical Audit Management System (Account → Projects → Places → Audits) and is designed to integrate with a FastAPI backend.
Tech stack
- Framework: Next.js 16 (App Router) + TypeScript
- Styling: Tailwind CSS
- UI: shadcn/ui
- Data: TanStack Query (React Query) + Axios
- Forms: React Hook Form + Zod
- Icons: Lucide React
Screenshots
Dashboard Pages
| Manager Dashboard | Auditor Dashboard | Administrator Dashboard |
|---|
| | |
| |
|---|
| Manager Projects | Manager Places |
| |
| Manager Place | Manager Project |
| |
| Manager Audits | Manager Auditor |
| |
| Manager Assignment | Manager Settings |
| |
|---|
| Auditor Execute Page | Auditor Places Page |
| |
| Auditor Reports Page | Auditor Report |
| |
| Auditor Settings | |
| |
|---|
| Administrator Accounts | Administrator Projects |
| |
| Administrator Places | Administrator Audits |
| |
| Administrator Auditor | Administrator System |
| |
| Administrator Settings | |
RBAC roles
- Managers (full access):
- Manager dashboard shows aggregate stats + recent activity.
- Playspace place screens show separate
place_audit_status, and place_survey_status statuses.
- Manager/admin score views now show explicit
PV / U pairs instead of a collapsed combined score.
- Auditors (limited access):
- Identified strictly by an alphanumeric
auditor_code (no real names displayed).
- Can execute audits, auto-save progress, and view their own work.
- Cannot access
/manager routes.
Local setup (macOS + pnpm)
Install dependencies:
pnpm install
Run the dev server:
pnpm dev
Open the app at [http://localhost:3000](http://localhost:3000).
Other useful commands:
pnpm lint
pnpm build
pnpm start
Visual testing
Visual regression coverage lives in tests/visual/ and uses Playwright for navigation/state setup plus Percy for visual review and diffing.
- Percy snapshots are the canonical regression/review surface.
public/screenshots/ remains the home for curated README/docs assets.- Local and CI setup, auth bootstrapping, and snapshot naming conventions are documented in
docs/visual-testing.md.
Environment variables
Configure the FastAPI base URL in .env.local:
NEXT_PUBLIC_API_BASE_URL="http://127.0.0.1:8000"
If not set, the frontend defaults to http://127.0.0.1:8000.
Analytics is optional and controlled by two variables. Both tools only load in production builds — never in local dev or previews.
NEXT_PUBLIC_CLARITY_PROJECT_ID="your-clarity-project-id" # Microsoft Clarity (heatmaps + session replay)
NEXT_PUBLIC_GA_MEASUREMENT_ID="G-XXXXXXXXXX" # Google Analytics 4 (gtag.js)
When a variable is unset, that tool never loads.
Region-aware consent. The app determines the visitor's region on the server from the edge geo header (x-vercel-ip-country, EEA/UK/CH treated as consent-required):
- Consent-required regions (EU/EEA, UK, Switzerland): a consent banner is shown; nothing tracks until the visitor accepts. Clarity waits for acceptance; GA loads under Google Consent Mode v2 with consent defaulted to
denied (cookieless pings only) until the visitor accepts.
- Everywhere else: analytics runs by default and no banner is shown, unless the visitor explicitly declines.
The consent region set lives in src/lib/analytics/regions.ts. When no geo header is present, the app defaults to the stricter consent-required behavior.
Authentication (current scaffold)
This repo currently uses a frontend-only demo login that sets cookies in the browser to simulate an authenticated session.
- Cookie names (see
src/lib/auth/role.ts):
playspace_role: "manager" or "auditor"playspace_access_token: bearer token (demo-generated for now)playspace_auditor_code: auditor-only identifier
The route guard is implemented in proxy.ts using those cookies:
/manager/** requires playspace_role="manager"/auditor/** requires playspace_role="auditor"/settings requires authentication (either role)
App routes
- Public
- Manager
/manager/dashboard/manager/projects
- Auditor
/auditor/dashboard/auditor/execute/[placeId]
- Shared
Role-based layout (sidebar)
Protected routes render inside a responsive AppShell with a sidebar (desktop) and a sheet drawer (mobile):
src/app/(protected)/layout.tsxsrc/components/app/app-shell.tsx
The navigation items are derived from the active role and rendered dynamically.
API client
Axios client lives at src/lib/api/api-client.ts:
- Adds
Authorization: Bearer <token> from playspace_access_token
- On
401, clears auth cookies and redirects to /login
Auditor multi-step form + auto-save
The audit execution UI is in:
src/app/(protected)/auditor/execute/[placeId]/page.tsx (server wrapper)src/app/(protected)/auditor/execute/[placeId]/audit-form.tsx (client form)
Auto-save behavior:
- Watches form values via React Hook Form.
- Sends a debounced
PATCH (900ms) with a partial payload to:
PATCH /playspace/places/:placeId/audits/draft
Playspace score model (current)
- Auditor execution mode still drives submission kind:
audit, survey, or both
- Place rollups now expose:
place_audit_statusplace_survey_statusaudit_mean_scoressurvey_mean_scoresoverall_scores
- Manager/admin UI should render score pairs as
PV {x} | U {y}
Agent rules (Cursor + Claude Code)
Scoped conventions for this repo (keep .cursor/rules/ and .claude/rules/ in sync):
frontend-dashboard-core.mdc - role guards, shared dashboard components, API contract, UI copyfrontend-i18n-and-exports.mdc - messages/en.json + de.json, report views, PDF/Excel exports
See CLAUDE.md and .claude/README.md. Workspace routing: ../.claude/AGENT_ROUTING.md → web-dashboard-ui.
Project structure
src/app/(public) - unauthenticated pagessrc/app/(protected) - authenticated shell + role-specific routessrc/lib/auth - role/session cookie helpers (server + browser)src/lib/api - Axios client + interceptorssrc/components/app - application shell components
