HMS SaaS — Run the complete app on localhost (dev mode)

Everything through Phase 1 + Phase 2 (Patients + OPD) is included. Dev mode skips Firebase and logs you in as Super Admin automatically.

0. Prerequisites (once)

brew install node@22 docker      # then OPEN Docker Desktop and wait for the whale to go solid
corepack enable                  # pnpm

1. Unzip and enter

unzip hms-project.zip && cd hms

2. Start Postgres + Redis

pnpm services:up
docker ps                        # note the postgres container NAME (e.g. hms-postgres-1)

3. Install + generate the DB client

pnpm install
pnpm --filter @hms/db exec prisma generate

4. Env files (defaults are already dev mode — no edits needed)

cp apps/api/.env.example       apps/api/.env
cp apps/web/.env.example       apps/web/.env.local
cp packages/db/.env.example    packages/db/.env

5. Create the runtime DB role, build schema, seed

(Using the container so you don't need psql installed. Adjust the container name if step 2 showed a different one.)

docker exec -i hms-postgres-1 psql -U postgres -d hms -c "CREATE ROLE hms_app LOGIN PASSWORD 'app_pw'; GRANT USAGE ON SCHEMA public TO hms_app; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT,INSERT,UPDATE,DELETE ON TABLES TO hms_app;"

pnpm db:setup                    # migrate -> apply RLS -> seed (incl. the dev admin user)

docker exec -i hms-postgres-1 psql -U postgres -d hms -c "GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO hms_app;"

Note: the rls step inside db:setup runs psql against ADMIN_URL. If your Mac's psql errors on a local socket, apply RLS via the container instead: docker exec -i hms-postgres-1 psql -U postgres -d hms < packages/db/sql/rls.sql then run pnpm --filter @hms/db seed.

6. Run everything

pnpm dev                         # API :3000 + web :3001

The API line should now read (AUTH_MODE=dev) automatically — no inline prefix needed.

7. Open

http://localhost:3001 → you're auto-logged-in as Super Admin (no manual user insert needed).

What you can do

• Hospitals (/platform) — provision / suspend / activate tenant hospitals.
• Patients (/patients) — register patients with ABHA/Ayushman IDs + consent. Pick the hospital up top.
• OPD (/opd) — add walk-ins (auto token), book appointments, check in, watch the live queue (5s refresh).

Verify it's real data (any time)

docker exec -i hms-postgres-1 psql -U postgres -d hms -c "SELECT name,status FROM tenant; SELECT mrn,\"fullName\" FROM patient; SELECT \"tokenNumber\",status FROM encounter WHERE type='OPD';"

Run the security test

ADMIN_URL="postgresql://postgres:postgres@localhost:5432/postgres" \
APP_URL="postgresql://hms_app:app_pw@localhost:5432/postgres" \
pnpm --filter @hms/db proof      # expect: 5 passed, 0 failed

Switching to real login later

Set AUTH_MODE=prod (api/.env) + NEXT_PUBLIC_AUTH_MODE=prod (web/.env.local), add Firebase keys, and provision users with pnpm --filter api provision. See README-auth.md.

Still to build (final Phase 2 slice)

Doctor consultation + prescriptions + role dashboards. Then Phase 3: billing, SMS, deploy.