Quick Start: Developer

For the full architectural picture, see Architecture Overview. This page is just enough to get a local environment running.

The monorepo

LSCApp/
  apps/
    web/          Next.js — /admin (staff), /portal (customer web),
                   every public page, and every /api/* route
    mobile/       Expo — staff/manager companion app
    customer/     Expo — native customer app
    print-agent/  Plain Node — runs on a Raspberry Pi at the physical
                   location, not deployed to Vercel
    docs/         This documentation site
  packages/
    shared/       Prisma schema, shared TypeScript types and business
                   logic used by every app above

npm workspaces tie it together — there is no separate API server; apps/web's /api/* routes are the backend for the mobile and customer apps too.

Getting a database connection

The database is AWS Aurora PostgreSQL. Local development connects through an SSH-tunneled bridge — you'll need:

The bridge's SSH key and the tunnel command (documented directly above DIRECT_URL in packages/shared/.env)
Your machine's outbound IP added to the bridge's security group (it's IP-allowlisted) — get it with curl -s https://checkip.amazonaws.com and ask an existing team member to add it

DATABASE_URL (the pgbouncer bridge) doesn't need the tunnel — only DIRECT_URL, used for Prisma migrations, does.

Install and run

npm install
npm run dev:web   # apps/web on localhost:3000

Environment variables live in apps/web/.env.local and packages/shared/.env — ask an existing team member for real values rather than guessing at placeholders; several (Stripe, Clerk, AWS) are shared, live credentials.

Running a database migration

Migrations need the SSH tunnel active (see above) plus, in this project's current setup, a local shadow database for the diff step (the database user doesn't have permission to create one on Aurora itself):

createdb lscapp_shadow
npx prisma migrate diff \
  --from-migrations prisma/migrations \
  --to-schema-datamodel prisma/schema.prisma \
  --shadow-database-url "postgresql://<you>@localhost:5432/lscapp_shadow" \
  --script > prisma/migrations/<timestamp>_<name>/migration.sql
npx prisma migrate deploy

Review the generated SQL before applying it — this connects to the real production database; there is no separate staging database for this project.

Deploying

There is no CI/CD pipeline and no git remote for this repo — deploys go straight from a local checkout via the Vercel CLI:

npx vercel --prod --archive=tgz

The --archive=tgz flag is required (the repo is past Vercel's non-archived upload file-count limit). apps/web/vercel.json — not a root-level one — holds the cron configuration.

Running tests

npm run test:shared

Before you touch anything real

Read Architecture Overview and the security notes in Security & Access Model — this system processes real payments and real customer identity documents for an operating business. Nothing in it is a toy.