Admin Dashboard — Local Dev Setup

Status: populated Owner: Platform Engineering (Frontend) Last updated: 2026-04-18

1. Prerequisites

Tool	Version	Install
Node.js	20 LTS	nvm install 20
pnpm	9.x	npm install -g pnpm
Docker Desktop	latest	docker.com
Firebase CLI	latest	npm install -g firebase-tools

2. Clone and Install

git clone https://github.com/ghasitech/ghasi-sms-gateway.git
cd ghasi-sms-gateway/services/admin-dashboard
pnpm install

3. Environment Configuration

cp .env.example .env.local

Edit .env.local:

# API (local Kong or mock)
API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000

# Firebase (use a dev Firebase project)
NEXT_PUBLIC_FIREBASE_API_KEY=AIza...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=ghasi-dev.firebaseapp.com
FIREBASE_PROJECT_ID=ghasi-dev

# Session encryption
SESSION_SECRET=<32-byte-hex: openssl rand -hex 32>
SESSION_COOKIE_SECURE=false

# Polling interval (reduce for local dev)
POLL_INTERVAL_MS=5000

4. Set Up Admin Test Account

# Using Firebase CLI with the emulator
firebase emulators:start --only auth

# Create a test admin user with the admin custom claim
node scripts/seed-admin-user.js \
  --email admin@ghasi.io \
  --password admin123 \
  --project ghasi-dev

Or, if using the live dev Firebase project, set the custom claim manually:

firebase auth:set-custom-claims <UID> '{"admin": true}' --project ghasi-dev

5. Local Backend Options

Option A: Full stack with Docker Compose

# From repo root
docker compose up kong auth-service analytics-service operator-management-service routing-engine billing-service

Option B: Mock API server (MSW)

pnpm dev:mock

MSW handlers in src/mocks/handlers/admin/. Mock data includes:

• 3 sample SMPP operators
• 24h of mock throughput data
• 5 routing rules
• 50 cross-tenant messages

6. Run Development Server

pnpm dev

Available at http://localhost:3001 (port 3001 to avoid conflict with customer-portal on 3000).

7. Running Tests

pnpm test          # Vitest unit tests
pnpm test:coverage # Coverage check
pnpm e2e           # Playwright E2E (against mock backend)

8. Storybook

pnpm storybook
# Available at http://localhost:6007

9. Common Issues

Issue	Fix
admin claim not set	Use seed-admin-user.js script or Firebase console
Dashboard charts not rendering	Check MSW handlers are returning ThroughputPoint[] array
Drag-and-drop not working in dev	Ensure @dnd-kit peer deps installed; check browser touch events
SMPP password visible after edit	Intended — password field is blank on edit; backend ignores blank