PolicyEngine app (v2)

Architecture and patterns for developing the main PolicyEngine web application at policyengine.org.

Repository: PolicyEngine/policyengine-app-v2

Architecture

Monorepo

policyengine-app-v2/
├── packages/
│   └── design-system/          # @policyengine/design-system (npm)
├── app/                        # Main Vite application
│   ├── src/
│   │   ├── pages/              # Page components (*.page.tsx)
│   │   ├── components/         # Shared UI (charts, layouts, modals)
│   │   ├── routing/            # Guards, router config
│   │   ├── hooks/              # Custom React hooks
│   │   ├── designTokens/       # Re-exports from design-system
│   │   ├── styles/             # Mantine theme, global PostCSS
│   │   ├── data/               # Static data (apps.json, posts/)
│   │   ├── adapters/           # API fetch wrappers
│   │   ├── api/                # React Query hooks
│   │   ├── contexts/           # React Context providers
│   │   ├── types/              # TypeScript interfaces
│   │   └── utils/              # Formatters, helpers
│   ├── public/                 # Static assets (logos, post images)
│   └── vite.config.mjs
├── turbo.json
└── package.json                # Bun workspaces root

Tech stack

Layer	Technology
Package manager	Bun (primary), npm fallback
Build	Vite + Turbo
UI framework	Mantine v8
Routing	React Router v7 (createBrowserRouter)
Charts	Recharts (standard), Plotly (maps only)
Server state	React Query
Design tokens	@policyengine/design-system
Language	TypeScript
Formatting	Prettier + ESLint
Testing	Vitest

Dual SPA mode

VITE_APP_MODE controls which entry point builds:

• website — Full policyengine.org (pages, blog, research, embedded tools)
• calculator — Standalone calculator at app.policyengine.org

Development

bun install                          # Install dependencies
bun run dev                          # Dev server (builds design-system first)
cd app && bun run prettier -- --write .  # Format before committing
bun run lint                         # Lint (CI uses --max-warnings 0)
bun run build                        # Production build
bun run test                         # Tests

CRITICAL: Frontend verification and troubleshooting

How to verify the frontend works

The ONLY reliable way to verify the frontend compiles correctly is bun run build. This catches import errors, TypeScript errors, and missing dependencies.

curl is NOT verification. Vite serves an HTML shell regardless of whether React components actually render. A 200 from curl means nothing for an SPA. Never use curl output as evidence that the frontend works.

You cannot visually verify a frontend. After the build passes and dev server starts, tell the user it's ready for them to check in the browser. Do not claim it "looks good."

Before making any claim about dev server status, check with lsof -i :5173. Do not assume it is running.

Correct verification sequence

bun run build                        # Catches all compile-time errors
# If build passes and dev server needed:
cd app && VITE_APP_MODE=website ./node_modules/.bin/vite --port 5173 &
open http://localhost:5173/us         # User checks visually

Dependency troubleshooting

When bun install fails:

1. Read the error. Fix the specific issue.
2. Try at most 2 approaches before asking the user for help.
3. Hard stops — never do these:
   • rm -rf node_modules without user approval
   • Manually npm pack + tar -xzf packages into node_modules
   • Editing lockfile internals
   • Looping through increasingly obscure npm/bun flags

Design tokens

Import from @/designTokens (convenience layer that re-exports from the design-system package):

import { colors, spacing, typography } from '@/designTokens';

Never hardcode values:

// Wrong
style={{ color: '#319795', marginBottom: '16px' }}

// Correct
style={{ color: colors.primary[500], marginBottom: spacing.lg }}

See policyengine-design-skill for the full token reference.

Mantine components

All UI uses Mantine v8. Key components:

import { Stack, Group, Text, Button, Paper } from '@mantine/core';
import { colors, spacing } from '@/designTokens';

function PolicyCard({ title, description, onEdit }) {
  return (
    <Paper p={spacing.lg} withBorder>
      <Stack gap={spacing.sm}>
        <Text fw={600}>{title}</Text>
        <Text c={colors.text.secondary} fz="sm">{description}</Text>
        <Button variant="outline" onClick={onEdit}>Edit</Button>
      </Stack>
    </Paper>
  );
}

Component	Usage
Stack, Group, Box	Layout
Text, Title	Typography
Button, ActionIcon	Controls
Paper, Card	Containers
Table, Modal, Tooltip	Complex UI
TextInput, Select, NumberInput	Forms

Charts

Recharts (standard for all new charts)

import { BarChart, Bar, XAxis, YAxis, Tooltip, ResponsiveContainer } from 'recharts';
import { ChartContainer, ChartWatermark, ImpactTooltip } from '@/components/charts';
import { colors } from '@/designTokens';

function RevenueChart({ data }) {
  return (
    <ChartContainer title="Revenue impact" csvData={data}>
      <ResponsiveContainer width="100%" height={400}>
        <BarChart data={data}>
          <XAxis dataKey="name" />
          <YAxis tickFormatter={(v) => v.toLocaleString('en-US', {
            style: 'currency', currency: 'USD', notation: 'compact', maximumFractionDigits: 1,
          })} />
          <Tooltip content={<ImpactTooltip />} />
          <Bar dataKey="value" fill={colors.primary[500]} />
        </BarChart>
      </ResponsiveContainer>
      <ChartWatermark />
    </ChartContainer>
  );
}

Semantic chart colors

Meaning	Token
Primary data	colors.primary[500]
Secondary	colors.gray[400]
Positive/gains	colors.success
Negative/losses	colors.gray[600]
Error	colors.error

Plotly (maps only)

Plotly is only used for geographic visualizations (choropleths, hex maps). All other charts use Recharts.

Chart components

Component	Purpose
ChartContainer	Card wrapper with title, CSV download
ChartWatermark	PolicyEngine logo below chart
ImpactTooltip	Formatted hover tooltip
ImpactBarLabel	Values above/below bars

Routing

Routes in app/src/WebsiteRouter.tsx:

/:countryId/
  ├── (StaticLayout)
  │   ├── home (index)
  │   ├── research/:slug (blog posts)
  │   ├── brand/*, team, donate
  │   └── model
  ├── (AppLayout)
  │   └── :slug → AppPage.tsx (apps.json)
  └── (full-page embeds)

Country guards

• CountryGuardSimple — Validates countryId, redirects to default
• CountryAppGuard — Validates slug+countryId for apps

Adding a new page

1. Create app/src/pages/MyPage.page.tsx
2. Add route in WebsiteRouter.tsx under appropriate layout
3. Use useParams() for countryId

Embedded apps (apps.json)

Interactive tools register in app/src/data/apps/apps.json and render via AppPage.tsx:

{
  "type": "iframe",
  "slug": "marriage",
  "title": "Marriage calculator",
  "source": "https://marriage-zeta-beryl.vercel.app/",
  "countryId": "us",
  "displayWithResearch": true
}

See policyengine-interactive-tools-skill for the full embedding pattern.

Ingredient CRUD pages

Policies, Reports, Simulations, and Populations follow a shared pattern using IngredientReadView and RenameIngredientModal. See app/.claude/skills/ingredient-patterns.md for details.

Blog posts

Markdown files in app/src/data/posts/articles/. Metadata in posts.json.

Sentence case

Strictly enforced everywhere:

// Correct
<Title order={2}>Your saved policies</Title>

// Wrong
<Title order={2}>Your Saved Policies</Title>

Exceptions: proper nouns (PolicyEngine), acronyms (IRS), official names (Child Tax Credit).

Deployment

• Automatic on push to main via Vercel
• Domain: policyengine.org (website), app.policyengine.org (calculator)
• Team: policy-engine scope

Key files

File	Purpose
app/src/WebsiteRouter.tsx	Main routes
app/src/pages/AppPage.tsx	Renders embedded apps
app/src/data/apps/apps.json	Tool registry
app/src/designTokens/	Token imports
app/src/components/charts/	Chart components
packages/design-system/	Token source of truth
app/.claude/skills/	Local skills (design-tokens, chart-standards, ingredient-patterns)

URL patterns

Production domains

Domain	Purpose
policyengine.org	Marketing website, research, blog
app.policyengine.org	Calculator app (policies, households, reports)

Calculator URLs (app.policyengine.org)

app.policyengine.org/:countryId/                             # Dashboard
app.policyengine.org/:countryId/policies                     # Saved policies
app.policyengine.org/:countryId/policies/create               # Policy builder
app.policyengine.org/:countryId/households                    # Saved households
app.policyengine.org/:countryId/households/create             # Household builder
app.policyengine.org/:countryId/reports                       # Saved reports
app.policyengine.org/:countryId/reports/create                # Report builder
app.policyengine.org/:countryId/simulations                   # Saved simulations
app.policyengine.org/:countryId/simulations/create            # Simulation builder
app.policyengine.org/:countryId/report-output/:reportId       # Report output (overview)
app.policyengine.org/:countryId/report-output/:reportId/:subpage/:view  # Specific chart

Report output subpages and views:

/report-output/:reportId/budget                               # Budget overview
/report-output/:reportId/distributional/incomeDecile          # Distributional by income
/report-output/:reportId/distributional/wealthDecile          # Distributional by wealth
/report-output/:reportId/winners-losers/incomeDecile          # Winners/losers by income
/report-output/:reportId/winners-losers/wealthDecile          # Winners/losers by wealth
/report-output/:reportId/poverty/age                          # Poverty by age
/report-output/:reportId/poverty/gender                       # Poverty by gender
/report-output/:reportId/poverty/race                         # Poverty by race (US only)
/report-output/:reportId/deep-poverty/age                     # Deep poverty by age
/report-output/:reportId/deep-poverty/gender                  # Deep poverty by gender
/report-output/:reportId/inequality                           # Inequality measures

Country IDs: us, uk, ca, ng, il

Website URLs (policyengine.org)

policyengine.org/:countryId/                     # Country home
policyengine.org/:countryId/research             # Research index
policyengine.org/:countryId/research/:slug       # Research article
policyengine.org/:countryId/blog                 # Blog index
policyengine.org/:countryId/blog/:postName       # Blog post
policyengine.org/:countryId/model                # Policy model explorer
policyengine.org/:countryId/:slug                # Embedded app (from apps.json)

Legacy v1 URLs (DO NOT USE)

The old policyengine-app (v1) used a different URL pattern that no longer works:

# WRONG — v1 format, returns "App not found"
policyengine.org/us/policy?reform=73278&baseline=2&region=enhanced_us&timePeriod=2025
policyengine.org/us/reform/2/280039/over/2/us?focus=policyOutput.winnersAndLosers.incomeDecile

Always use app.policyengine.org for calculator functionality.

Related skills

• policyengine-design-skill — Full token reference
• policyengine-interactive-tools-skill — Building standalone tools
• policyengine-vercel-deployment-skill — Deployment patterns
• policyengine-writing-skill — Content style
• policyengine-api-skill — Backend API