Setup Guide
Q-Flow — Smart Virtual Queue System
This guide walks you through installing, configuring, and running the platform from source.
Table of Contents
- Prerequisites
- Clone & Install
- Environment Configuration
- Database Setup
- Running the Application
- Demo Data & Default Accounts
- Production Deployment Checklist
1. Prerequisites
| Requirement | Minimum Version | Notes |
|---|---|---|
| Node.js | 18+ | LTS recommended |
| PostgreSQL | 14+ | Local or managed (e.g. Neon, Supabase) |
| npm | 9+ | Bundled with Node.js |
| Appwrite account | Cloud or self-hosted | Free tier sufficient for development |
2. Clone & Install
git clone https://github.com/AAgecy/atechqflow.git
cd atechqflow
npm install
3. Environment Configuration
Copy the example environment file and fill in the required values:
cp .env.example .env
Open .env and update each section:
Database
DATABASE_URL="postgresql://user:password@localhost:5432/atechqflow"
DATABASE_CONNECTION_LIMIT=10
DATABASE_POOL_TIMEOUT=10
DATABASE_CONNECTION_TIMEOUT=5
Authentication
# Generate with: openssl rand -hex 32
JWT_SECRET="your-32-char-secret-here"
NEXT_PUBLIC_ROOT_DOMAIN="" # leave empty for local dev
NEXT_PUBLIC_ROOT_DOMAIN="http://localhost:3000"
SMS Notifications
SMS_PROVIDER=console # use "sparrow" for production
SPARROW_SMS_TOKEN=""
SPARROW_SMS_FROM="INFO"
WhatsApp Notifications
Multi-channel notification support alongside SMS. Leave empty to disable.
WHATSAPP_PROVIDER=console # use provider name for production
WHATSAPP_API_KEY=""
WHATSAPP_PHONE_NUMBER_ID=""
Email Notifications
EMAIL_PROVIDER=console # use "smtp" for production
EMAIL_SMTP_HOST=""
EMAIL_SMTP_PORT="587"
EMAIL_FROM="noreply@atechqflow.com"
Integration System (Square POS)
Square POS adapter for payment-terminal integration. Leave empty to disable.
SQUARE_ACCESS_TOKEN=""
SQUARE_LOCATION_ID=""
SQUARE_MERCHANT_ID=""
SQUARE_WEBHOOK_SECRET=""
Development tip: Keep
SMS_PROVIDER=consoleduring development. All SMS messages will be printed to the terminal instead of being sent.
Appwrite Realtime
Q-Flow uses Appwrite for serverless real-time events.
- Create a free Appwrite project.
- Create a Database and inside it a Collection named
Events. - Add four
Textattributes to the collection:tenantId,event,payload,timestamp. - Grant the Any role Read permission on the collection.
- Create a server-side API Key with database scope.
NEXT_PUBLIC_APPWRITE_PROJECT_ID="your-project-id"
NEXT_PUBLIC_APPWRITE_PROJECT_NAME="Q-Flow"
APPWRITE_API_KEY="your-server-api-key"
NEXT_PUBLIC_APPWRITE_ENDPOINT="https://cloud.appwrite.io/v1"
NEXT_PUBLIC_APPWRITE_DATABASE_ID="your-database-id"
NEXT_PUBLIC_APPWRITE_COLLECTION_ID="your-collection-id"
Optional: Web Push (VAPID)
Browser push notifications for citizens tracking their token:
node -e "const w=require('web-push'); console.log(JSON.stringify(w.generateVAPIDKeys()))"
VAPID_PUBLIC_KEY="..."
VAPID_PRIVATE_KEY="..."
VAPID_EMAIL="mailto:qflow@atechqflow.com"
Optional: Nagarik App (National ID)
Enables 1-click token issuance via Nepal's government National ID platform. Leave empty to disable.
NAGARIK_API_BASE_URL="https://api.nagarikapp.gov.np/v1"
NAGARIK_API_KEY=""
NAGARIK_CLIENT_ID=""
NAGARIK_CLIENT_SECRET=""
NAGARIK_TIMEOUT_MS=10000
4. Database Setup
Development (push schema directly)
npm run db:push
Production (migration files)
npm run db:migrate
Seed Demo Data
npm run db:seed
This creates a sample organisation (lalitpur-metro) with departments, counters, and user accounts for every role. See Demo Data & Default Accounts below.
5. Running the Application
Development server
npm run dev
Open http://localhost:3000 in your browser.
Production build
npm run build
npm start
Useful npm scripts
| Script | Description |
|---|---|
npm run dev | Start the Next.js development server with hot reload |
npm run build | Compile the production bundle |
npm start | Run the compiled production bundle |
npm run db:push | Sync the Prisma schema to the database (no migration history) |
npm run db:migrate | Apply pending migrations |
npm run db:seed | Seed demo data |
npm run lint | Run ESLint |
npm run test:e2e | Run Playwright end-to-end tests |
npm run test:unit | Run vitest unit tests |
node tests/screenshots.capture.mjs | Capture route screenshots for UI review |
6. Demo Data & Default Accounts
Run npm run db:seed to create demo organisations, departments, counters, and user accounts.
When seeding completes, the seeder prints every account email and its password to your
terminal — passwords are intentionally not documented anywhere in this guide or repository.
Security Warning: Never reuse seeded credentials in an internet-accessible environment. Change all demo passwords before deploying.
Demo URLs
| Page | URL |
|---|---|
| Home | http://localhost:3000 |
| Join Queue | http://localhost:3000/lalitpur-metro/join |
| Staff Dashboard | http://localhost:3000/lalitpur-metro/dashboard |
| Display Board | http://localhost:3000/lalitpur-metro/board |
| Admin Panel | http://localhost:3000/admin |
7. Production Deployment Checklist
- Generate a strong
JWT_SECRET(≥ 32 random characters). - Set
SMS_PROVIDER=sparrowand configure Sparrow SMS credentials. - Configure WhatsApp and Email notification channels if using multi-channel dispatch.
- Set Square POS credentials if using payment-terminal integration.
- Set
NEXT_PUBLIC_ROOT_DOMAINto your public domain (no trailing slash). - Configure
NEXT_PUBLIC_ROOT_DOMAINfor subdomain routing if applicable. - Run
npm run db:migrate(notdb:push) in production. - Remove or change all default demo passwords.
- Restrict
SOCKET_ALLOWED_ORIGINSto your actual domain(s). - Enable HTTPS and set
Securecookies (the app sets them automatically whenNODE_ENV=production). - Configure database connection pooling (
DATABASE_CONNECTION_LIMIT) appropriate for your server count. - Set up Appwrite Realtime with production API keys.
- Verify Nagarik App credentials if National ID login is required.
For architectural details see System Guide. For day-to-day operations see How-To Guides.