|>
* . /\ \ | / .
/ \ -- ( ) --
. /\ / .. \ / | \
/ \ /\ / : \ *
* / \ / \ / : \ /\
/ .. \ / \ .: \ / \ /\
/\ / .: :. \ \ : \/ \ / \
/ \ /.: :.\ .: \ \ / \
__/ \__/: :\____.:___________\_____\_/ \___
. . : : . .: . . . . . . . . . . . .
you are here --> *
____ _ __ __ ____ _ _____
| _ \ / \ | \/ || __ ) | | | ____|
| |_) | / _ \ | |\/| || _ \ | | | _|
| _ < / ___ \ | | | || |_) || |___ | |___
|_| \_\/_/ \_\|_| |_||____/ |_____||_____|
Ramble
A marketplace for things worth doing: classes, tours, tastings, and outdoor trips.
Ramble is a demo marketplace for bookable experiences. Guests browse, pick a date, and book a spot; hosts list sessions and get paid. No real money moves: checkout runs on a fake payment gateway.
The site is also an experiment. It is built to prove two things with one project:
- A planning method. Plan a real project end to end, freeze a dated estimate before any code is written, build it, and then publish where the plan was wrong.
- A one-person team with AI agents. One owner makes the decisions; agents research, write code, review, and test. Every unit of work is routed to an agent, to the owner, or to both, and the actual time is logged against the estimate.
Where the trail is today
| Phase | What happened | When |
|---|
| P0 Setup | Repo, project manager agent, build plan | Sep 28 |
| P1 Discovery and PRD | 78 requirements, signed off | Oct 18 |
| P2 Research and ADRs | 10 architecture decisions accepted | Oct 18 |
| P3 Design | Mobile-first flow and error states in Figma, signed off | Oct 18 |
| P4 Plan | Seven planning artifacts, frozen at tag plan-frozen-2026-10-20 | Oct 20 |
| P5 Build | In progress: the merge desk (U-118) comes first | From Oct 20 |
| P6 Write-up | Where the plan was wrong, and why | After launch |
The frozen forecast, as ranges rather than single dates:
| Milestone | Likely (P50) | Cautious (P90) |
|---|
| Prototype: a clickable guest flow on seed data | 2026-12-01 | 2026-12-07 |
| Launch scope from the PRD | 2027-03-08 | 2027-03-29 |
The walking skeleton (U-002) is in place: four route groups with placeholder pages. Real pages replace them unit by unit. Live status, decisions, and the roadmap are in ramble-pm.
The planning method
The plan is seven artifacts, each built on the one before it:
- Design doc
- Work breakdown: 134 units
- Complexity and uncertainty scores: uncertainty is its own axis, and risky unknowns get a spike before an estimate
- Dependency graph and critical path
- Execution model: who builds what, and at which review tier
- Estimate: three-point ranges from a simulation, cross-checked against a reference class
- Resourcing: staffing options and the dates each implies
Three rules keep it honest:
- Estimates are ranges. Never a single date.
- Freeze before build. After the freeze tag, plan files are read-only. Reality goes in the delta log.
- Log actuals as units close. Anything off by more than 25% gets a one-line reason.
How the work runs
ramble-pm, a project manager agent, runs the plan phase by phase, keeps status and decisions current, and hands work to other agents. Its definition is in .claude/agents/ramble-pm.md.docs/plan/units.yaml is the record of every unit, mirrored to GitHub Issues.- Every build unit carries a scope manifest (in scope, out of scope, reference code). Review checks the diff against it.
- Tiered auto-merge (ADR 0010): standard units merge to
main once CI, review, QA, and spec checks pass. Critical units (anything that could oversell a session or double-charge a guest) merge to an integration branch that the owner promotes weekly after a nightly smoke test.
- Decisions stay human. Requirement sign-off, architecture decisions, the plan freeze, deploys, and changes to the rules themselves are the owner's.
What it is built with
Decided in the architecture decision records:
| Area | Choice |
|---|
| Framework | Next.js App Router, Server Components by default, Cache Components on |
| Data | Neon Postgres with Drizzle; row-locked booking holds; an append-only money ledger |
| Payments | A fake gateway for the demo; no real money |
| Search | Server-side filtering with the URL as state; no map at launch |
| Styling | CSS Modules with design tokens from Figma; React Aria for the date picker and dialog |
| Quality | Per-PR smoke, accessibility, and Lighthouse budgets; nightly full suite |
| Hosting | Vercel and GitHub Actions |
| Content | About 60 curated experiences, plus a generated 400-experience fixture for scale |
Mobile first throughout: designs start at 390 px wide, and CSS uses min-width breakpoints.
Map of the repo
docs/
product/ PRD, client brief, market scan
adr/ architecture decisions and the research behind them
design/ wireframe review, design system plan, tone checklist, Figma library ids
plan/ build plan, the seven artifacts, units.yaml, status, decisions, delta log
scripts/plan/ Bun scripts that compute the plan from units.yaml
.claude/ the PM agent, its skill, and its project memory
Setup
Needs Node 24 (.nvmrc) and pnpm 10. Node 25 no longer bundles Corepack, so install it once with npm install -g corepack and then run corepack enable; it reads the pinned version from packageManager in package.json.
pnpm install # also runs `next typegen`, so route and cache-profile types exist from the first open
docker compose up -d --wait # local Postgres 17
cp .env.example .env.local # APP_URL has a default; the two database URLs do not
pnpm db:migrate
SEED_TARGET=local pnpm db:seed # optional: demo data for home and browse
pnpm db:http # second terminal: prints the NEON_HTTP_ENDPOINT line for .env.local
pnpm dev
Guest pages read through Neon's HTTP driver, which cannot reach the Docker Postgres, so without NEON_HTTP_ENDPOINT home and browse show their error state locally. pnpm db:http serves that protocol in front of DATABASE_URL (local databases only, port 4444 or NEON_HTTP_PORT); paste the address it prints into .env.local and restart the app. It works the same under pnpm build && pnpm start. See docs/runbooks/seed.md.
pnpm build:profile builds with React's profiler enabled, so DevTools' Profiler works against pnpm start; set REACT_PROFILING=1 on a Vercel deployment to get the same build there (it is slower, so leave it off for production).
The gates CI runs on every PR (.github/workflows/ci.yml), each a script you can run locally: pnpm format:check, lint, typecheck, test, build, knip, and e2e (Playwright; run pnpm exec playwright install chromium once). Storybook has three local scripts: pnpm storybook (dev server), pnpm storybook:build, and pnpm storybook:test (runs the stories with the a11y gate); its CI job is landing separately. pnpm smoke runs the same Playwright smoke of every route against the built app; the route list is e2e/routes.ts, one row per route. Environment variables are read and validated in one place, src/server/env.ts. Import boundaries between src/app, src/components, src/lib, and src/server are enforced by pnpm lint; tests/lint-boundaries.test.ts fails if a rule is weakened. Secrets, and how to rotate them, are in docs/runbooks/secret-rotation.md. Logging, error tracking, and how to raise an alert are in docs/runbooks/alerting.md. The two-tier Content Security Policy (enforced with a nonce on dynamic routes, report-only on cached ones), the security header set, and security.txt are in docs/runbooks/security-headers.md. The browse address grammar, its cache, and its failure state are in docs/runbooks/browse.md.
Database
Postgres on Neon through Drizzle, all under src/server/db/. db (pooled host, pg Pool) is the only handle that opens a transaction; dbRead (Neon HTTP) is for single reads and never runs a capacity or balance check. Migrations are committed SQL in src/server/db/migrations/: change the schema in src/server/db/schema/, run pnpm db:generate, commit the result, and never drizzle-kit push a shared database. A PR never drops or renames a column the deployed code still reads (expand, then contract in a later PR). pnpm db:migrate uses the direct host, pnpm db:check checks the history, and pnpm test:db runs the *.db.test.ts files against the local Postgres, each in its own schema (createFreshDatabase in tests/db/harness.ts). Previews migrate before the build; production is migrated only by the db-migrate-production workflow, run by hand.
Preview branches come from the Neon integration for Vercel, which gives each preview deployment its own preview/<git branch> database branch and injects its two URLs; the alternative, a GitHub Actions job using Neon's branch actions, would need a Vercel token to hand the URLs to the deployment and would race it, so only the integration creates branches. A GitHub Actions workflow adds what the integration lacks: the 7-day expiry and deleting the branch when the PR merges or closes.
The integration makes a branch's database and URLs only when a deployment is redeployed, so the first build of a new branch has no DATABASE_URL_UNPOOLED. The preview build then skips db:migrate with a warning instead of failing; redeploy once and it migrates.
Running the planning scripts
The scripts need Bun and have no other dependencies.
bun scripts/plan/critical-path.ts
bun scripts/plan/forecast.ts --report estimate
critical-path.ts prints the critical path through the dependency graph. forecast.ts simulates the build with review time as a limited resource; --report resourcing and --report schedule give the staffing options and the dated schedule.
Design
Wireframes and the component library are in Figma: Ramble Core Flow Wireframes.
