Initial scaffold from dashboard plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: anth-volk

.claude/settings.json

@@ -0,0 +1,6 @@
+{
+  "plugins": {
+    "marketplaces": ["PolicyEngine/policyengine-claude"],
+    "auto_install": ["dashboard-builder@policyengine-claude"]
+  }
+}

.github/workflows/ci.yml

@@ -0,0 +1,14 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bunx vitest run
+      - run: bun run build

.gitignore

@@ -0,0 +1,43 @@
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# bun
+bun.lock
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/

CLAUDE.md

@@ -0,0 +1,44 @@
+# va-reform-dashboard
+
+An interactive calculator that lets users model the impact of reforms to the Child Tax Credit (CTC), Earned Income Tax Credit (EITC), and income tax rates at both the federal and Virginia state levels for Virginia residents. Users configure their household and adjust reform parameters, then see household-level impacts via line charts and summary metrics, plus statewide impacts via microsimulation.
+
+## Architecture
+
+- Next.js App Router with Tailwind CSS v4 and @policyengine/ui-kit theme
+- @policyengine/ui-kit for standard UI components (Header, SidebarLayout, Tabs, MetricCard, charts, inputs)
+- Custom Modal backend (gateway + worker pattern) for household and statewide microsimulation
+- Frontend polling via @tanstack/react-query for async computation results
+- Two endpoints: `household-impact` (fast, ~10-40s) and `statewide-impact` (slow, ~2-5 min microsimulation)
+
+## Development
+
+```bash
+bun install
+make dev            # Deploy worker + start gateway + frontend (random port)
+make dev-frontend   # Frontend only (uses production API or NEXT_PUBLIC_API_URL)
+make dev-backend    # Gateway only (worker must already be deployed)
+```
+
+## Testing
+
+```bash
+make test           # Frontend tests (vitest)
+make test-backend   # Backend tests (pytest)
+```
+
+## Build
+
+```bash
+make build
+```
+
+## Design standards
+- Uses Tailwind CSS v4 with @policyengine/ui-kit/theme.css (single import for all tokens)
+- @policyengine/ui-kit for all standard UI components
+- Primary teal: `bg-teal-500` / `text-teal-500`
+- Semantic colors: `bg-primary`, `text-foreground`, `text-muted-foreground`
+- Font: Inter (via next/font/google)
+- Sentence case for all headings
+- Charts use `fill="var(--chart-1)"` for series colors
+- Recharts axes use `niceTicks` with `domain={["auto", "auto"]}`
+- Negative currency formatted as `-$100` not `$-100`

Makefile

@@ -0,0 +1,45 @@
+.PHONY: dev dev-frontend dev-backend deploy-worker
+.PHONY: build test test-backend lint clean
+
+# Deploy worker functions, then start gateway + frontend
+dev:
+	@echo "Deploying worker functions..."
+	@unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET && modal deploy backend/app.py
+	@echo "Starting gateway (ephemeral)..."
+	@modal serve backend/modal_app.py & MODAL_PID=$$!; \
+	sleep 5; \
+	MODAL_URL="https://policyengine--va-reform-dashboard-fastapi-app-dev.modal.run"; \
+	PORT=$$(python3 -c 'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsockname()[1]); s.close()'); \
+	echo "Gateway: $$MODAL_URL"; \
+	echo "Frontend: http://localhost:$$PORT"; \
+	NEXT_PUBLIC_API_URL=$$MODAL_URL PORT=$$PORT bun run dev; \
+	kill $$MODAL_PID 2>/dev/null
+
+# Frontend only (uses production API or NEXT_PUBLIC_API_URL if set)
+dev-frontend:
+	@PORT=$$(python3 -c 'import socket; s=socket.socket(); s.bind(("",0)); print(s.getsockname()[1]); s.close()'); \
+	echo "Starting dev server on http://localhost:$$PORT"; \
+	PORT=$$PORT bun run dev
+
+# Backend only (gateway in dev mode — worker must already be deployed)
+dev-backend:
+	modal serve backend/modal_app.py
+
+# Deploy worker functions to Modal (required before gateway can spawn jobs)
+deploy-worker:
+	unset MODAL_TOKEN_ID MODAL_TOKEN_SECRET && modal deploy backend/app.py
+
+build:
+	bun run build
+
+test:
+	bunx vitest run
+
+test-backend:
+	cd backend && uv run pytest
+
+lint:
+	bun run lint
+
+clean:
+	rm -rf .next node_modules

README.md

@@ -0,0 +1,17 @@
+# Virginia tax and benefit reform calculator
+
+An interactive PolicyEngine calculator for modeling the impact of federal and Virginia state tax and benefit reforms on households and statewide.
+
+## Getting started
+
+```bash
+bun install
+make dev
+```
+
+## Stack
+
+- **Frontend:** Next.js 14 (App Router), Tailwind CSS v4, @policyengine/ui-kit, Recharts
+- **Backend:** Modal (gateway + worker), policyengine-us
+- **Testing:** Vitest
+- **Deployment:** Vercel (frontend), Modal (backend)

__tests__/page.test.tsx

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import Home from '../app/page'
+
+describe('Home page', () => {
+  it('renders the dashboard title', () => {
+    render(<Home />)
+    expect(
+      screen.getByText('Virginia tax and benefit reform calculator'),
+    ).toBeDefined()
+  })
+
+  it('renders household configuration section', () => {
+    render(<Home />)
+    expect(screen.getByText('Household configuration')).toBeDefined()
+  })
+
+  it('renders both tab options', () => {
+    render(<Home />)
+    expect(screen.getByText('Household impact')).toBeDefined()
+    expect(screen.getByText('Statewide impact')).toBeDefined()
+  })
+
+  it('renders reform parameter sections', () => {
+    render(<Home />)
+    expect(screen.getByText('Federal income tax')).toBeDefined()
+    expect(screen.getByText('Federal Child Tax Credit')).toBeDefined()
+    expect(screen.getByText('Federal EITC')).toBeDefined()
+    expect(screen.getByText('Virginia income tax')).toBeDefined()
+    expect(screen.getByText('Virginia EITC')).toBeDefined()
+  })
+})

app/globals.css

@@ -0,0 +1,10 @@
+@import "tailwindcss";
+@import "@policyengine/ui-kit/theme.css";
+
+body {
+  font-family: var(--font-sans);
+  color: var(--foreground);
+  background: var(--background);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}

app/layout.tsx

@@ -0,0 +1,24 @@
+import './globals.css'
+import { Inter } from 'next/font/google'
+import type { Metadata } from 'next'
+
+const inter = Inter({ subsets: ['latin'] })
+
+export const metadata: Metadata = {
+  title: 'Virginia tax and benefit reform calculator - PolicyEngine',
+  description:
+    'An interactive calculator that lets users model the impact of reforms to the Child Tax Credit, Earned Income Tax Credit, and income tax rates at both the federal and Virginia state levels.',
+  icons: { icon: '/favicon.svg' },
+}
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body className={inter.className}>{children}</body>
+    </html>
+  )
+}