QueueZero

Digital queue management app. Business owners manage queues from a dashboard; customers join with a business code.

Live app: https://queuezero-mvp-build.vercel.app/

Prerequisites

• Node.js 22+
• Docker Desktop
• Clerk account → https://dashboard.clerk.com

---

First-time setup

1. Install dependencies

npm install

2. Create .env.local

cp .env.example .env.local

Set your Clerk keys from the Clerk dashboard:

DATABASE_PROVIDER=local
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/queuezero

NEXT_PUBLIC_APP_URL=http://localhost:3000

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_SECRET_KEY=sk_test_...

Port 5433 avoids conflicts with a local Postgres install on Windows (which often uses 5432).

3. Start Postgres in Docker

npm run db:docker:start

4. Create tables

npm run db:setup

Optional demo data (CITYCARE business):

npm run db:setup:seed

5. Run the app

npm run dev

Open http://localhost:3000

6. Test it

1. Go to http://localhost:3000/sign-up
2. Create an account
3. Complete onboarding at /dashboard/onboarding
4. Create a business
5. Add services in the dashboard

Customer flow: http://localhost:3000/join

Hackathon submission assets

See docs/submission/README.md for:

• Architecture diagram (docs/architecture.drawio)
• Aurora DSQL design notes
• AWS screenshot checklist
• 3-minute demo script

Set QUEUEZERO_QR_SECRET in Vercel for signed QR check-in in production.

---

Coming back to the project

If Docker is already set up

docker start queuezero-postgres
npm run dev

Open http://localhost:3000

If the container was removed or this is a new machine

npm install
npm run db:docker:start
npm run db:setup
npm run dev

If the database is empty but the container still exists

docker start queuezero-postgres
npm run db:setup
npm run dev

---

Commands

Command	What it does
npm run dev	Start the app
npm run db:docker:start	Create/recreate the Postgres container on port 5433
npm run db:setup	Apply schema to the Docker database
npm run db:setup:seed	Apply schema + demo data
npm run build	Production build
npm run typecheck	TypeScript check

---

Troubleshooting

password authentication failed for user "postgres"

Your app is hitting the wrong Postgres on port 5432. Use port 5433:

DATABASE_URL=postgresql://postgres:postgres@localhost:5433/queuezero

Then:

npm run db:docker:start
npm run db:setup

relation "businesses" does not exist

docker start queuezero-postgres
npm run db:setup

Vercel OIDC warnings on npm run dev

Ignored when DATABASE_PROVIDER=local in .env.local.

---

Production

Production runs on Vercel with Aurora DSQL (configured in the Vercel dashboard). Local development uses Docker Postgres only — no AWS or OIDC setup needed.