eKYC App

A full-stack mobile eKYC (Electronic Know Your Customer) application built with React Native (Expo) and Node.js (Express).

Tech Stack

Backend

• Runtime: Node.js with TypeScript
• Framework: Express 5
• Database: SQLite with Prisma ORM
• Authentication: JWT with refresh token rotation
• Logging: Pino with structured logging
• Validation: Zod

Mobile

• Framework: React Native with Expo
• Navigation: Expo Router (file-based routing)
• State Management: Zustand
• HTTP Client: Axios with interceptors
• Secure Storage: expo-secure-store

Prerequisites

• Node.js >= 18.x
• npm >= 9.x
• Expo CLI: npm install -g expo-cli
• iOS Simulator (macOS) or Android Emulator or physical device with Expo Go

Getting Started

1. Clone the Repository

git clone <repository-url>
cd ekyc-app

2. Install Dependencies

npm install

This installs dependencies for both backend and mobile packages (npm workspaces).

3. Environment Setup

Backend (.env)

Create packages/backend/.env:

# Server
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL="file:./dev.db"

# JWT
JWT_SECRET=your-secure-jwt-secret-here
JWT_ACCESS_EXPIRES_IN=600
JWT_REFRESH_EXPIRES_IN=2592000

# Security
REFRESH_TOKEN_SECRET=your-secure-refresh-secret-here

# Logging
LOG_LEVEL=debug

# Demo (optional)
DEMO_AUTO_APPROVE_DELAY_MS=60000

Mobile (.env)

Create packages/mobile/.env:

# Use your machine's local IP for physical devices
# Use localhost for iOS Simulator
EXPO_PUBLIC_API_URL=http://192.168.x.x:3000

To find your local IP:

# macOS
ipconfig getifaddr en0

# Linux
hostname -I | awk '{print $1}'

4. Database Setup

Generate Prisma client:

npm run prisma:generate

Run migrations:

npm run prisma:migrate

Seed the database with a test user:

npm run prisma:seed

This creates a test user:

• Email: omar@test.com
• Password: password123

Running the Application

Start Backend Server

npm run dev:backend

Server runs at http://localhost:3000

Start Mobile App

npm run dev:mobile

This opens Expo DevTools. Then:

• Press i for iOS Simulator
• Press a for Android Emulator
• Scan QR code with Expo Go app on physical device

Running Tests

All Tests

npm test

Backend Tests Only

npm run test:backend

Mobile Tests Only

npm run test:mobile

Project Structure

ekyc-app/
├── package.json              # Workspace root
├── packages/
│   ├── backend/              # @ekyc/backend
│   │   ├── src/
│   │   │   ├── app.ts        # Express app setup
│   │   │   ├── server.ts     # Server entry point
│   │   │   ├── config/       # Environment configuration
│   │   │   ├── routes/       # API route handlers
│   │   │   ├── services/     # Business logic
│   │   │   ├── middleware/   # Express middleware
│   │   │   ├── schemas/      # Zod validation schemas
│   │   │   ├── lib/          # Utilities (db, jwt, crypto, logger)
│   │   │   └── types/        # TypeScript types
│   │   ├── prisma/
│   │   │   ├── schema.prisma # Database schema
│   │   │   └── seed.ts       # Database seeder
│   │   └── tests/            # Jest tests
│   │
│   └── mobile/               # @ekyc/mobile
│       ├── app/              # Expo Router pages
│       │   ├── _layout.tsx   # Root layout
│       │   ├── index.tsx     # Entry redirect
│       │   ├── (auth)/       # Auth screens (login)
│       │   └── (app)/        # Protected screens
│       │       ├── (tabs)/   # Tab navigation (home, settings)
│       │       └── onboarding/ # Onboarding flow
│       ├── components/       # Reusable components
│       ├── store/            # Zustand stores
│       ├── lib/              # Utilities (api client, storage)
│       ├── hooks/            # Custom React hooks
│       └── constants/        # Theme, config

API Endpoints

Authentication

Method	Endpoint	Description
POST	/v1/auth/login	User login
POST	/v1/auth/register	User registration
POST	/v1/auth/refresh	Refresh access token

Protected Routes (require Bearer token)

Method	Endpoint	Description
GET	/v1/me	Get current user
POST	/v1/onboarding/submit	Submit KYC data
GET	/v1/verification/status	Get verification status

Health Check

Method	Endpoint	Description
GET	/health	Server health check

Security Features

• JWT Access Tokens: Short-lived (10 min default), signed with HS256
• Refresh Token Rotation: New refresh token issued on each refresh
• Token Reuse Detection: Detects and revokes sessions on token reuse
• Device Binding: Sessions bound to device ID
• Single Device Policy: New login revokes all previous sessions
• Secure Token Storage: Refresh tokens hashed with HMAC-SHA256
• Password Hashing: bcrypt with cost factor 12
• Structured Logging: No PII or tokens in logs

Available Scripts

Command	Description
npm run dev:backend	Start backend dev server
npm run dev:mobile	Start Expo mobile app
npm run build:backend	Build backend for production
npm run test:backend	Run backend tests
npm run test:mobile	Run mobile tests
npm test	Run all tests
npm run prisma:generate	Generate Prisma client
npm run prisma:migrate	Run database migrations
npm run prisma:seed	Seed database with test user

Demo Mode

For demo purposes, KYC verification is auto-approved after 1 minute (configurable via DEMO_AUTO_APPROVE_DELAY_MS).

Troubleshooting

Metro bundler cache issues

cd packages/mobile && npx expo start --clear

Database issues

# Reset database
rm packages/backend/prisma/dev.db
npm run prisma:migrate
npm run prisma:seed

Port conflicts

# Kill process on port 3000
lsof -ti:3000 | xargs kill -9

# Kill process on port 8081 (Expo)
lsof -ti:8081 | xargs kill -9