Imported from Dansong00/laundromate (AGENTS.md). Install upstream with npx skills add Dansong00/laundromate. Copyright stays with the author.

AGENTS.md

Cursor Cloud specific instructions

Project overview

LaundroMate is a pnpm monorepo with a FastAPI backend (apps/api) and a Next.js 14 frontend (apps/web), plus three shared TypeScript packages (packages/ui, packages/types, packages/utils). PostgreSQL 15 is required infrastructure.

Services

Lint / Test / Build

See package.json scripts in root and apps/web/package.json, plus pyproject.toml in apps/api.

• API lint: cd apps/api && source .venv/bin/activate && flake8 --config .flake8 app/
• API tests: cd apps/api && source .venv/bin/activate && PYTHONPATH=$PWD pytest
• Web lint: pnpm --filter @laundromate/web lint
• Web tests: cd apps/web && npx vitest --run
• Web build: pnpm --filter @laundromate/web build

Non-obvious caveats

• Database port: Docker maps PostgreSQL to port 5433 on the host (not 5432). The .env file in apps/api must use port 5433 in the DATABASE_URL. Copy .env.example and update the port from 5432 to 5433.
• Alembic: alembic.ini hard-codes the DB URL pointing to postgres:5432 (Docker network hostname). For local development, alembic reads the URL from app.core.database.session.engine, which loads from .env. Always run alembic from apps/api with the venv activated and PYTHONPATH set.
• Settings strict mode: app.core.config.settings.Settings (pydantic-settings) forbids extra fields. The .env file must only contain fields declared in the Settings model (no REDIS_URL, DEBUG, TWILIO_* etc.).
• bcrypt compatibility: passlib 1.7.4 is incompatible with bcrypt >= 4.1. Pin bcrypt==4.0.1 in the venv to avoid AttributeError: module 'bcrypt' has no attribute '__about__'.
• Pytest ARRAY errors: ~306 test errors are pre-existing — tests use SQLite which doesn't support PostgreSQL ARRAY columns. The 75 passing tests and 17 failures are the real test results.
• Docker in Cloud VM: Docker daemon must be started with sudo dockerd and fuse-overlayfs storage driver. The socket needs chmod 666 /var/run/docker.sock for non-root access.
• pnpm build scripts: On first pnpm install, some packages (@clerk/shared, esbuild, unrs-resolver) have blocked build scripts. These do not affect dev functionality.
• Clerk auth routes: The <SignIn /> and <SignUp /> Clerk components must live in catch-all route directories ([[...sign-in]] / [[...sign-up]]). Without this, Clerk's internal sub-path requests (SSO callbacks, verification steps) 404 and cause "network error" on login. The afterSignInUrl/afterSignUpUrl props are deprecated in @clerk/nextjs v6; use fallbackRedirectUrl instead.
• Clerk env vars: NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY must be in apps/web/.env.local. Without them Clerk falls back to "keyless mode" with a temporary dev instance. Also set NEXT_PUBLIC_CLERK_SIGN_IN_URL=/auth/login and NEXT_PUBLIC_CLERK_SIGN_UP_URL=/auth/sign-up so Clerk routing matches the app's custom auth paths.
• Backend IdP config: For Clerk JWTs to verify on the API, set IDP_JWKS_URI and IDP_ISSUER in apps/api/.env to your Clerk instance values (e.g. https://<your-app>.clerk.accounts.dev/.well-known/jwks.json).