GSSB e-Invoice System - Client Portal

Public-facing portal for regular users to submit and manage e-invoice requests.

Overview

This is the client portal application for the GSSB e-Invoice System. It allows regular users (individuals and businesses) to:

• Login via email + OTP authentication
• Submit invoice requests with TIN validation
• View request history and status
• Download approved invoices (PDF/Excel)
• Manage user profile
• View notifications

Tech Stack

• Framework: Next.js 16.0.1 (App Router + Turbopack)
• Language: TypeScript
• UI Library: shadcn/ui (Radix UI + TailwindCSS)
• Forms: React-Hook-Form + Zod
• State: Context API + Zustand
• HTTP Client: Axios

Quick Start

Prerequisites

• Node.js 18+ installed
• npm or yarn package manager

Installation

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

Development Server

The application will run on http://localhost:3000

Test Accounts

Public Users (Demo Mode):

• Email: demo.user1@example.com | OTP: 123456
• Email: demo.user2@example.com | OTP: 123456
• Email: demo.user3@example.com | OTP: 123456

Environment Variables

Create a .env.local file in the root:

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:8000/api
NEXT_PUBLIC_API_TIMEOUT=30000

# Application Settings
NEXT_PUBLIC_APP_NAME=GSSB e-Invoice System
NEXT_PUBLIC_APP_ENV=development

# Demo Mode (remove for production)
NEXT_PUBLIC_ENABLE_MOCK_API=true
NEXT_PUBLIC_DEMO_MODE=true

Project Structure

gssb-einvoicing-client/
├── app/                    # Next.js App Router pages
│   ├── login/             # OTP login page
│   ├── history/           # Request history & dashboard
│   ├── profile/           # User profile management
│   ├── request/           # Invoice submission form
│   └── layout.tsx         # Root layout
├── components/
│   ├── ui/                # shadcn/ui components
│   ├── portal/            # Portal-specific components
│   └── shared/            # Shared components
├── contexts/              # React contexts (auth, etc.)
├── lib/                   # Utilities, API client, schemas
├── types/                 # TypeScript types
└── public/                # Static assets

Features

Authentication

• Email + OTP login flow
• HTTP-only cookie-based JWT
• Automatic token refresh
• Role-based redirect

Profile Management

• Individual/Business profiles
• Multiple payment methods support
• Address management
• TIN validation

Invoice Submission

• Full Invoice / Tax Invoice Only modes
• TIN validation via API
• PDPA consent checkbox
• File upload support
• Transaction date range selection

Request History

• List all submissions
• Filter by status (Approved, Rejected, Pending, Queued)
• Search by Request ID, Payment ID, or Name
• Export to PDF/Excel
• Download approved invoices

Notifications

• Bell icon with unread count badge
• Mark as read/unread
• Remove notifications
• Click to navigate

Available Scripts

npm run dev          # Start development server
npm run dev:turbo    # Start with Turbopack
npm run build        # Create production build
npm run start        # Start production server
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint errors
npm run format       # Format code with Prettier
npm run format:check # Check code formatting

Adding shadcn/ui Components

# Add specific components
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add form

# Add multiple at once
npx shadcn@latest add button input form card table

Deployment

Vercel (Recommended)

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

Environment Variables (Production)

Ensure these are set in your deployment platform:

• NEXT_PUBLIC_API_URL - Production API URL
• Remove NEXT_PUBLIC_ENABLE_MOCK_API or set to false
• Remove NEXT_PUBLIC_DEMO_MODE or set to false

Related Repositories

• Admin Dashboard: gssb-einvoicing-admin
• Backend API: (To be provided)

Support

For issues and questions, please create an issue in the GitHub repository.

License

ISC