AI-agent-first government digital platform built with Nuxt 3, Ripple UI, and TypeScript. Port of the Victorian government Ripple design system to a modern, full-stack architecture optimized for AI coding agents.
Ripple Next is a hybrid monorepo that publishes @ripple-next/* packages to a private
npm registry. Consumer teams scaffold downstream repos, install the packages they need,
and follow the golden-path conventions for documentation, testing, and deployment.
The platform uses the provider pattern for all infrastructure concerns, SST v3 for
deployment, and machine-readable runbooks, error taxonomy, and code generators to
make AI agents first-class developers.
Primary reference: AGENTS.md — architecture, conventions, task routing.
pnpm bootstrap # zero-to-ready (install + doctor + validate)
pnpm doctor -- --json # environment check with taxonomy codes
pnpm verify -- --json # all quality gates (lint, typecheck, test)- Error codes: Look up
RPL-*taxonomy codes indocs/error-taxonomy.json. - What to build: Product Roadmap — follow the AI Agent Suggestions format. Do not self-triage.
| You are... | Start here |
|---|---|
| AI agent | AGENTS.md then pnpm bootstrap and pnpm verify |
| Platform developer | Platform Developer Guide, Architecture, API Contracts, Testing Guide, Deployment |
| Consumer app developer | Consumer App Guide, Downstream Adoption Guide, AI Adoption Prompts |
| Tester / QA | Testing Guide, CI Gates, Performance, Session Observability |
| Downstream team lead / governance | Downstream Adoption Guide, Downstream Workflows, Platform Capabilities, Fleet Governance (ADR-019) |
| Architect / reviewer | Architecture, Platform Capabilities, Critique Evaluation, Lambda vs ECS |
| Product owner / tech lead | Product Roadmap — priorities, status, and AI-first benefit rationale |
| Curious contributor | Contributing — safe zones, workflow, and expectations |
This quick start is for platform development (the ripple-next monorepo). For consumer app setup, see the Consumer App Guide.
# One-command setup (install + doctor + validate)
pnpm bootstrap
# Start local services (Postgres, Redis, MinIO, Mailpit, MeiliSearch)
docker compose up -d
# Copy env template and run migrations
cp .env.example .env
pnpm db:migrate && pnpm db:seed
# Start development server
pnpm dev| Document | Description |
|---|---|
| Platform Developer Guide | Platform internals — setup to deployment |
| Consumer App Guide | Building apps with @ripple-next/* packages |
| Architecture | System design and stack overview |
| Provider Pattern | Swappable infrastructure interfaces |
| Data Model | PostgreSQL schema and entities |
| API Contracts | oRPC routers and REST endpoints |
| Deployment | Local → staging → production |
| Testing Guide | Test pyramid, mocks, conformance |
| Accessibility | WCAG 2.1 AA compliance |
| CI Gates | Blocking vs advisory gates |
| Performance | Core Web Vitals budgets |
| Release Verification | SBOM and checksums |
| Session Observability | Agent session metrics |
| Lambda vs ECS | Compute decision framework |
| Critique Evaluation | Architecture review log |
| Downstream Workflows | Reusable CI actions |
| Downstream Adoption Guide | Documentation governance for downstream repos |
| AI Adoption Prompts | Copy-paste prompts for AI agents |
| Platform Capabilities | Package and tool inventory |
| Runbooks | Machine-readable procedures — pnpm runbook <name> |
| Product Roadmap | Priorities, status, and archive |
| AGENTS.md | Agent conventions and task routing |
| ADR | Decision |
|---|---|
| ADR-001 | Nuxt 3 over Next.js |
| ADR-002 | Drizzle ORM over Prisma |
| ADR-003 | Provider pattern for infrastructure |
| ADR-004 | SST v3 over CDK/CloudFormation |
| ADR-005 | Lambda default, ECS escape hatch |
| ADR-006 | No Kubernetes |
| ADR-007 | Hybrid monorepo + published packages |
| ADR-008 | OIDC/OAuth over deprecated Lucia |
| ADR-009 | CMS provider pattern for Drupal/Tide |
| ADR-010 | CI observability + supply chain |
| ADR-011 | CMS decoupling — pull out Drupal |
| ADR-012 | Env schema validation gate |
| ADR-013 | Flaky test containment policy |
| ADR-014 | Preview deploy guardrails |
| ADR-015 | LocalStack — provider pattern preferred |
| ADR-016 | Roadmap reorganisation — AI-first priority tiers |
| ADR-017 | Upstream Ripple — port, own, selectively sync |
| ADR-018 | AI-first workflow — runbooks, generators, error taxonomy |
| ADR-019 | Fleet governance — drift detection + sync automation |
| ADR-020 | Context file minimalism — evidence-based line limits |
| ADR-021 | API contract strategy — oRPC + OpenAPI-first |
| ADR-022 | Bidirectional fleet communication |
| ADR-023 | Downstream adoption standards — documentation governance |
| ADR-024 | Declarative secrets schema — typed, validated, machine-readable |
| ADR-025 | Platform CLI — unified pnpm rip with JSON output |
| ADR-026 | GitHub OIDC federation — zero secrets in CI/CD |
| ADR-027 | Licensing — Apache 2.0 for government procurement |
| Layer | Technology |
|---|---|
| Frontend | Nuxt 3 + Vue 3 + TypeScript |
| UI | Ripple UI Core + Storybook 10 |
| API | Nitro server routes + oRPC (OpenAPI 3.1.1) |
| Database | PostgreSQL (Drizzle ORM) |
| CMS | Drupal/Tide (JSON:API) / Mock |
| Queue | SQS / BullMQ / Memory |
| Auth | OIDC/OAuth (oauth4webapi) |
| Infra | SST v3 (Pulumi) |
| Compute | Lambda + ECS Fargate |
| Secrets | SSM Parameter Store + Secrets Manager (Provider pattern) |
| CI/CD | GitHub Actions + OIDC federation |
| Testing | Vitest + Playwright |
Every infrastructure concern has an interface with swappable implementations. Tests always use memory/mock providers — never cloud services. See full docs and ADR-003.
graph LR
Interface["Provider Interface"] --> Mock["Memory / Mock<br/>Tests + CI"]
Interface --> Local["Local<br/>Docker Compose"]
Interface --> Prod["AWS<br/>Lambda + ECS"]
| Command | Description |
|---|---|
pnpm bootstrap |
First-time setup (all-in-one) |
pnpm doctor |
Validate environment readiness |
pnpm dev |
Start dev server |
pnpm build |
Build all packages |
pnpm test |
Run all tests |
pnpm test:e2e |
Run E2E tests |
pnpm lint |
Lint all code |
pnpm typecheck |
Type check |
pnpm db:generate |
Generate migration |
pnpm db:migrate |
Run migrations |
pnpm db:seed |
Seed dev data |
pnpm storybook |
Start Storybook |
pnpm storybook:build |
Build Storybook |
pnpm generate:scaffold <dir> |
Scaffold a downstream repo with full DX infrastructure |
pnpm conform |
Score a repo against the golden-path conformance rubric |
apps/web/ — Nuxt 3 application
packages/ui/ — Ripple UI component library
packages/db/ — Database (Drizzle ORM)
packages/cms/ — CMS abstraction (Drupal/Tide + Mock)
packages/queue/ — Queue abstraction
packages/auth/ — Authentication
packages/storage/ — File storage
packages/email/ — Email
packages/events/ — Domain events
packages/validation/ — Zod schemas
packages/shared/ — Shared types/utils
packages/testing/ — Test infrastructure
packages/config/ — Declarative secrets schema, environment config
packages/secrets/ — Secrets management (provider pattern)
packages/cli/ — Platform CLI (pnpm rip)
services/worker/ — Queue consumers
services/websocket/ — WebSocket service
services/cron/ — Cron jobs
services/events/ — Event handlers
infra/ — GitHub OIDC, IAM roles, SST components
Ripple Next is the AI-augmented golden path for Victorian government digital platforms. Every contribution — from a typo fix to a new provider — improves the platform for all consumers.
- Documentation — improve guides, fix typos, add examples (
docs/) - Tests — increase coverage toward thresholds (
packages/*/tests/) - Provider implementations — add a new provider for an existing interface (
packages/*/providers/) - Mermaid diagrams — add or improve architecture visuals in docs
- CI improvements — improve pipeline reliability (
.github/workflows/)
graph LR
A["pnpm bootstrap"] --> B["Make changes"]
B --> C["pnpm verify"]
C --> D{"API change?"}
D -- Yes --> E["pnpm changeset"]
D -- No --> F["Open PR"]
E --> F
- PRs receive a first response within 48 hours on business days
- All feedback is constructive — we explain the why behind requests
pnpm verifypassing is the primary bar for merge-readiness
See CONTRIBUTING.md for the full workflow and upstream Ripple sync procedures.
This project is licensed under the Apache License 2.0.
Licensed under the Apache License, Version 2.0. You may use, modify, and distribute this software in compliance with the License. See LICENSE for the full text.