Customer Portal — Service Overview

Status: populated Owner: Product Engineering (Frontend) Last updated: 2026-04-18 Companion: DOMAIN_MODEL · API_CONTRACTS · SYNC_CONTRACT · SECURITY_MODEL

1. Purpose

customer-portal is the self-service web application for Ghasi-SMS-Gateway customers. It provides a browser-based interface for account holders to manage their integration: API keys, test message dispatch, message log inspection, webhook endpoint configuration, and billing overview.

The portal is a stateless Next.js 14 frontend. It holds no persistent data of its own; all state lives in the backend services consumed via Kong.

2. Bounded Context

Customer Self-Service — sits at the product boundary between the platform's internal backend services and end-customer accounts. Does not perform business logic; orchestrates API calls and renders results.

3. Responsibilities

Area	What customer-portal owns
Authentication UI	Firebase Auth sign-in flow; JWT acquisition and refresh
Dashboard	Account summary: message volume, delivery rate, credit balance
API Key management	Create, list, revoke API keys; show raw key once in a modal
Test SMS sender	Compose and dispatch a single test SMS via POST /v1/messages
Message logs	Filterable / paginated view of sent messages
Webhook configuration	CRUD for customer webhook endpoints
Billing overview	Invoice list, usage summary
Profile	User email, password change, active session list

4. Non-Responsibilities

Area	Owner
JWT validation	Kong (edge) + Firebase Admin SDK (auth-service)
API key hashing / scoping	auth-service
SMS routing decisions	routing-engine
Billing calculation	billing-service
Operator management	admin-dashboard + operator-management-service

5. Key Flows

Login

1. User enters credentials in /login.
2. Firebase Auth SDK signs in; returns Firebase ID token.
3. Portal calls POST /v1/auth/firebase (through Kong) to exchange for a platform JWT + custom customer claim verification.
4. JWT stored in httpOnly session cookie (see SECURITY_MODEL).
5. On every page load, Next.js server component attaches Authorization: Bearer <jwt> on server-side fetch calls.

API Key Creation

1. User navigates to /api-keys → clicks "Create Key".
2. Modal collects key name and scopes.
3. POST /v1/api-keys returns { keyId, rawKey, scopes, createdAt }.
4. Raw key displayed once in a modal with a "Copy" button.
5. Key stored hashed in auth-service; raw key never persisted client-side.

Message Log

1. User sets filters (date range, status, to, from number) on /messages.
2. Next.js server component calls GET /v1/messages?from=&to=&status=&startDate=&endDate=&page=&limit=.
3. Response rendered as paginated table with delivery status badges.

6. Dependencies

Dependency	Purpose
Firebase Auth (client SDK)	Browser-side sign-in; ID token acquisition
Kong Gateway	Edge authentication, rate limiting, routing to backend services
auth-service	JWT exchange, claim verification, API key lifecycle
sms-orchestrator	Test message dispatch
billing-service	Invoice list, usage data
webhook-dispatcher	Webhook CRUD

7. Status

Active development — foundation auth flow and API key pages targeted for MVP.