Running the Project
Starting both servers and verifying the setup
Note
Both servers must be running at the same time. Keep two terminal windows open
— one for saas-pos-backend and one for saas-pos-frontend. If you use the
bundled Docker compose for the database, start it first:
POSTGRES_PASSWORD=yourpassword docker compose up -d in saas-pos-backend.
Start the Backend Server
In the saas-pos-backend terminal, run:
The server is ready when the structured log shows (with PORT=5000 in your .env):
The API is live at: http://localhost:5000
Start the Frontend Server
In the saas-pos-frontend terminal, run:
Ready when you see:
The app is live at: http://localhost:3000
Verification Checklist
| Check | Expected Result |
|---|---|
| Open http://localhost:5000/api/health in browser | JSON health response |
| Open http://localhost:3000 in browser | POSVelo login page appears |
| Log in with Super Admin credentials | Redirect to the platform admin panel |
| Log in with a tenant account (from the demo seed or the setup wizard) | Business dashboard appears |
| Navigate to Products | Demo products appear (if you ran the demo seed) |
All Backend npm Scripts
| Script | Description |
|---|---|
npm run dev | Start backend in development mode with hot-reload (tsx watch) |
npm run build | Compile TypeScript to JavaScript (outputs to dist/) |
npm run start | Run the compiled production build from dist/server.js |
npm run db:generate | Regenerate Prisma client after any schema change |
npm run db:migrate | Create and apply a new migration — prompts for a name (dev only) |
npm run db:migrate:prod | Apply pending migrations without prompts — use in production |
npm run db:seed | Insert the full demo dataset (same as seed:demo): tenant, stores, products, customers, employees, sales |
npm run db:seed:super-admin | Create the platform-level Super Admin account from SUPER_ADMIN_EMAIL / SUPER_ADMIN_PASSWORD |
npm run db:seed:billing | Seed the default subscription plans for the billing module |
npm run db:studio | Launch visual database browser at http://localhost:5555 |
npm run db:reset | ⚠️ DANGER — Wipes the entire database and re-runs all migrations |
npm run test | Run the Vitest test suite once and exit |
npm run test:watch | Run tests in interactive watch mode |
npm run typecheck | Validate TypeScript types without emitting output files |
npm run lint | Run ESLint across the entire src/ directory |
All Frontend npm Scripts
| Script | Description |
|---|---|
npm run dev | Start the Next.js dev server at http://localhost:3000 |
npm run build | Create an optimized production build |
npm run start | Serve the production build |
npm run lint | Run ESLint across the frontend source |