Skip to main content

Developer Onboarding & Operational Runbook

Welcome to the engineering team supporting the Veridex HiTech Web Application. This guide provides step-by-step instructions for provisioning a local development environment, seeding baseline database credentials, executing operational scripts, and adhering to continuous integration quality standards.

1. Prerequisites & System Requirements​

Before beginning local setup, verify your machine satisfies the following prerequisites:

Tool / RuntimeRequired VersionVerification CommandNotes / Installation Link
Node.js>= 22.0.0 (LTS)node -vUse nvm or nvm-windows.
npm>= 10.0.0npm -vBundled with Node 22.
MongoDB>= 6.0 (Replica Set recommended)mongosh --versionLocal MongoDB or cloud MongoDB Atlas instance.
Git>= 2.40.0git --versionUsed for version control.

2. Step-by-Step Local Initialization​

Step 1: Clone the Codebase​

git clone https://github.com/veridex-websites-platform/veridex-hitech-web-application.git
cd veridex-hitech-web-application

Step 2: Enforce Node 22​

Ensure your shell is using Node 22:

nvm use 22 || nvm install 22
node -v
# Output should verify v22.x.x

Step 3: Clean Installation of Dependencies​

Use npm ci rather than npm install to ensure deterministic dependency resolution matching package-lock.json:

npm ci

Step 4: Environment Configuration​

Create a local .env.local configuration file:

cp .env.example .env.local

At a minimum, configure the following core variables in .env.local:

# Core Application URLs
NEXT_PUBLIC_APP_URL="http://localhost:3000"
NEXT_PUBLIC_APP_ENV="development"

# MongoDB Database Connection
DATABASE_URL="mongodb://127.0.0.1:27017/hitech_local"

# NextAuth v5 Authentication
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="development-secret-minimum-32-chars-long-example!"

# reCAPTCHA Test Keys (Google reCAPTCHA v2/v3 test keys)
NEXT_PUBLIC_RECAPTCHA_SITE_KEY="6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
RECAPTCHA_SECRET_KEY="6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe"

3. Database Seeding & Admin Accounts​

The application requires pre-existing administrative credentials to access /admin and initialize background collections.

# Provision all default test accounts
npm run seed:all

Administrative Scripts Directory​

NPM ScriptScript FileDescriptionDefault Test Credentials
npm run seed:super-adminscripts/seed-super-admin.tsIdempotently inserts or updates the root super_admin role user.Email: super.admin@hitechinsurance.ai
Password: Superadmin@123
npm run seed:adminsscripts/seed-admins.tsProvisions regional admin and claims manager accounts.Email: admin@hitechinsurance.ai
Password: Admin@123
npm run seed:allSequentially executes seed:super-admin and seed:admins.--
npm run admin:update-credentialsscripts/update-admin-credentials.tsSafely updates admin email and bcrypt password.Controlled via TARGET_EMAIL, NEW_PASSWORD env vars.

4. Starting the Development Server​

Execute the development server:

npm run dev

The application starts at http://localhost:3000:

  • Public Homepage: http://localhost:3000/en
  • Customer Portal: http://localhost:3000/en/dashboard
  • Admin Control Center: http://localhost:3000/en/admin
  • System Health Diagnostics: http://localhost:3000/en/admin/system-health
  • Swagger OpenAPI Docs: http://localhost:3000/api/docs
  • Health Check Probe: http://localhost:3000/api/health

5. Operational Testing & Verification Scripts​

The repository includes standalone CLI scripts in scripts/ to verify backend integrations independently of the web UI:

Testing Rate Limiting​

Verify sliding-window eviction, counter increments, and 429 enforcement:

npx tsx scripts/test-rate-limiter.ts

OpenAPI Specification Validation​

Inspect route registration and OpenAPI spec compliance:

node scripts/check-spec.js

Email Dispatch Diagnostics​

Verify local SMTP or Azure Email microservice routing:

node scripts/send-test-email.js

6. Pre-Commit Quality Standards​

Before submitting a Pull Request, all engineers must run and pass the full quality assurance pipeline:

# 1. Strict TypeScript static type checking
npm run type-check

# 2. ESLint 9 code inspection
npm run lint

# 3. Prettier style verification
npm run format:check