PA Compact Licensing Platform

API Coverage:

Client Coverage:

Repository Structure

api/          Python API (FastAPI, Python 3.13)
client/       Next.js frontend (React, TypeScript, USWDS)
iac/          Infrastructure as Code

Prerequisites

• Install the following using asdf:

    asdf plugin add python
    asdf install python 3.13.12
    asdf set python 3.13.12
  
    asdf plugin add nodejs
    asdf install nodejs 25.8.2
    asdf set nodejs 25.8.2
  
    asdf plugin add uv
    asdf install uv 0.11.2
    asdf set uv 0.11.2
  
    asdf plugin add just
    asdf install just 1.48.1
    asdf set just 1.48.1
  
    asdf reshim
    npm install -g pnpm@latest-10

  • Python 3.13+
  • Node.js 24+
  • uv (Python package manager)
  • pnpm 10+
  • just (task runner)

• Docker (for containerized linting and builds)

• pre-commit (pipx install pre-commit or brew install pre-commit)

Pre-commit hooks

Install once after cloning:

pre-commit install           # sets up the git hook
pre-commit install-hooks     # pre-fetch hook environments

Hooks run automatically on git commit. To run them on demand:

pre-commit run --all-files   # lint the whole repo
pre-commit run               # lint staged files only

Hooks include: ruff (Python lint + format), gitleaks (secret detection), markdownlint, and generic file checks (trailing whitespace, EOF, merge conflicts, large files, YAML/JSON validity). The same hooks run in CI via .github/workflows/lint.yml.

Getting Started

API

cd api
export UV_PYTHON=$(asdf which python) # use the python from asdf
just install     # Install Python dependencies
just dev         # Run API with hot reload (localhost:8000)

Client

cd client
pnpm install     # Install Node dependencies
pnpm dev         # Run dev server

Development

API Commands

just test              # Run tests
just test-coverage     # Run tests with coverage
just lint              # Run all linting (spectral + ruff + pyright)
just format            # Format code
just build             # Build production Docker image

Client Commands

pnpm test              # Run tests (vitest)
pnpm lint              # Lint
pnpm storybook         # Run Storybook
pnpm build             # Production build