🛡️ PathGuard API

Next-Generation KYC Verification System

Intelligent risk scoring • Real-time fraud detection • Enterprise-grade security

Quick Start • Features • API Docs • Examples

✨ Features

🔐 Security & Verification

Advanced Risk Scoring - ML-inspired algorithm
Real-time Analysis - Instant fraud detection
Document Validation - Multi-format support
Email Intelligence - Domain reputation checks

⚡ Developer Experience

Interactive Scalar Documentation - Live API playground
Mock Data System - Test without DB setup
Clean Architecture - Maintainable codebase
Type Safety - Zod schema validation

🎯 Core Capabilities

graph LR
    A[Client Request] --> B[Validation Layer]
    B --> C[Risk Analysis Engine]
    C --> D[Decision Engine]
    D --> E[Response + Score]
    style C fill:#4169E1
    style D fill:#339933

🛡️ Enterprise Security - Helmet, CORS, input sanitization
📊 Smart Pagination - Efficient data retrieval
🚨 Custom Middleware - Scalar pollution prevention
🏗️ Layered Design - Controllers → Services → Models
⚙️ Production Ready - Structured logging & error handling

🚀 Quick Start

Get PathGuard API running in less than 2 minutes:

# Clone repository
git clone https://github.com/thmslfb/pathguard-api.git
cd pathguard-api

# Install dependencies
npm install

# Start development server (uses mock data by default)
npm run dev

🎮 Live Playground: Open http://localhost:3000/api/v1/docs to interact with the API through Scalar

🎯 First API Call

curl -X POST http://localhost:3000/api/v1/kyc/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Dupont",
    "email": "[email protected]",
    "documentType": "id_card"
  }'

Response:

{
  "verification_id": "ver_123e4567-e89b-12d3-a456-426614174000",
  "status": "approved",
  "risk_score": 0.1,
  "checks_performed": ["name", "email", "documentType"],
  "timestamp": "2025-10-05T14:30:00.000Z"
}

🛠️ Tech Stack

Category	Technologies
Runtime
Framework
Database
Validation
Documentation
Testing
Security

📦 Installation

📋 Prerequisites

Before you begin, ensure you have:

✅ Node.js 18+ - Download
✅ PostgreSQL - Install Guide
✅ Git - Get Started

1️⃣ Clone the Repository

git clone https://github.com/thmslfb/pathguard-api.git
cd pathguard-api

2️⃣ Install Dependencies

npm install

3️⃣ Environment Configuration

cp .env.example .env

Create your .env file with the following structure:

# Database Configuration
DATABASE_URL="postgresql://username:password@localhost:5432/pathguard"

# Risk Scoring Thresholds
LOW_THRESHOLD=0.2
HIGH_THRESHOLD=0.5

# Server Configuration
PORT=3000
NODE_ENV=development

4️⃣ Database Setup

# Run migrations to create database schema
npm run migrate:apply

5️⃣ Launch Application

# Development mode with hot reload
npm run dev

# Production mode
npm start

✅ API Ready: http://localhost:3000/api/v1
📚 Scalar Documentation: http://localhost:3000/api/v1/docs

📡 API Reference

Method	Endpoint	Description	Status
`GET`	`/api/v1`	API information & health	✅
`GET`	`/api/v1/health`	System health check	✅
`POST`	`/api/v1/kyc/verifications`	Create verification	✅
`GET`	`/api/v1/kyc/verifications`	List verifications	✅
`GET`	`/api/v1/kyc/verifications/:id`	List verification by ID	✅
`DELETE`	`/api/v1/kyc/verifications/:id`	Delete verification by ID	✅
`PATCH`	`/api/v1/kyc/verifications/:id/status`	Update verification status	✅
`GET`	`/api/v1/docs`	Scalar documentation	📚

🔗 Base URL

http://localhost:3000/api/v1

🎯 Examples

Perform identity verification

POST /api/v1/kyc/verifications

✅ Low Risk - Approved

curl -X POST http://localhost:3000/api/v1/kyc/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Dupont",
    "email": "[email protected]",
    "documentType": "id_card"
  }'

Response (200 OK):

{
  "verification_id": "ver_123e4567-e89b-12d3-a456-426614174000",
  "status": "approved",
  "risk_score": 0.1,
  "checks_performed": ["name", "email", "documentType"],
  "timestamp": "2025-10-05T14:30:00.000Z"
}

🟡 Medium Risk - Pending Review

curl -X POST http://localhost:3000/api/v1/kyc/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "email": "[email protected]",
    "documentType": "passport"
  }'

Response (200 OK):

{
  "verification_id": "ver_234f5678-f90c-23e4-b567-537725285111",
  "status": "pending_review",
  "risk_score": 0.35,
  "checks_performed": ["name", "email", "documentType"],
  "timestamp": "2025-10-05T14:35:00.000Z"
}

❌ High Risk - Rejected

curl -X POST http://localhost:3000/api/v1/kyc/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "name": "X",
    "email": "[email protected]",
    "documentType": "passport"
  }'

Response (200 OK):

{
  "verification_id": "ver_345g6789-g01d-34f5-c678-648836396222",
  "status": "rejected",
  "risk_score": 0.6,
  "checks_performed": ["name", "email", "documentType"],
  "timestamp": "2025-10-05T14:40:00.000Z"
}

Response (400 Bad Request)

Name error (name too short)

{
  "error": "Validation failed",
  "details": [
    {
      "field": "name",
      "message": "Name must be at least 2 characters long"
    }
  ]
}

Email Error (invalid format)

{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Document type error (invalid value)

{
  "error": "Validation failed",
  "details": [
    {
      "field": "documentType",
      "message": "Invalid option: expected one of \"passport\"|\"id_card\"|\"driver_license\""
    }
  ]
}

List all verifications

📋 GET /api/v1/kyc/verifications

Retrieve a list of all KYC verifications with optional pagination support.

curl http://localhost:3000/api/v1/kyc/verifications?limit=10&offset=0

Response (200 OK):

[
  {
    "verification_id": "ver_123e4567-e89b-12d3-a456-426614174000",
    "status": "approved",
    "risk_score": 0.1,
    "created_at": "2025-10-05T14:30:00.000Z"
  },
  {
    "verification_id": "ver_987fcdeb-51a2-43f1-b987-123456789abc",
    "status": "approved",
    "risk_score": 0.2,
    "created_at": "2025-10-05T13:15:00.000Z"
  },
  {
    "verification_id": "ver_456def78-90ab-12cd-34ef-567890abcdef",
    "status": "pending_review",
    "risk_score": 0.35,
    "created_at": "2025-10-05T12:45:00.000Z"
  }
]

Response (400 Bad Request)

Invalid type for limit and offset

{
  "error": "Validation failed",
  "details": [
    {
      "field": "limit",
      "message": "Invalid input: expected number, received NaN"
    },
    {
      "field": "offset",
      "message": "Invalid input: expected number, received NaN"
    }
  ]
}

Limit too small

{
  "error": "Validation failed",
  "details": [
    { "field": "limit", "message": "Too small: expected number to be >=1" }
  ]
}

Limit too big

{
  "error": "Validation failed",
  "details": [
    { "field": "limit", "message": "Too big: expected number to be <=1000" }
  ]
}

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	`100`	Number of results per page (max: 1000)
`offset`	integer	`0`	Number of results to skip

Example:

curl http://localhost:3000/api/v1/kyc/verifications?limit=20&offset=40

Get verification by ID

GET /api/v1/kyc/verifications/:id

Retrieve detailed information about a KYC verification using its unique identifier.

curl http://localhost:3000/api/v1/kyc/verifications/ver_456def78-90ab-12cd-34ef-567890abcdef

Response (200 OK):

{
  "verification_id": "ver_456def78-90ab-12cd-34ef-567890abcdef",
  "status": "pending_review",
  "risk_score": 0.35,
  "created_at": "2025-10-05T14:30:00.000Z"
}

Response (400 Bad Request)

Invalid id parameter

{
  "error": "Validation failed",
  "details": [
    {
      "field": "id",
      "message": "Invalid verification ID format. Must be in format ver_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

Response (404 Not Found):

{
  "error": "Verification not found"
}

Delete verification by ID

DELETE /api/v1/kyc/verifications/:id

Delete a KYC verification using its unique identifier.

curl -X DELETE http://localhost:3000/api/v1/kyc/verifications/ver_456def78-90ab-12cd-34ef-567890abcdef

Response (200 OK):

{
  "message": "Verification deleted successfully"
}

Response (404 Not Found):

{
  "error": "Verification not found"
}

Update verification status

GET /api/v1/kyc/verifications/:id/status

Update the status of a KYC verification by its unique identifier.

curl http://localhost:3000/api/v1/kyc/verifications/ver_52042584-e3ff-43c3-a6f0-bb9923dcadb7/status \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "approved"
}'

Response (200 OK):

{
  "verification_id": "ver_52042584-e3ff-43c3-a6f0-bb9923dcadb7",
  "status": "approved"
}

Response (400 Bad Request)

Invalid status

{
  "error": "Validation failed",
  "details": [
    {
      "field": "status",
      "message": "Invalid option: expected one of \"approved\"|\"rejected\"|\"pending_review\""
    }
  ]
}

Invalid id parameter

{
  "error": "Validation failed",
  "details": [
    {
      "field": "id",
      "message": "Invalid verification ID format. Must be in format ver_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

Response (404 Not Found):

{
  "error": "Verification not found"
}

🧠 Risk Scoring Algorithm

PathGuard uses a sophisticated multi-factor risk analysis engine to evaluate KYC submissions:

📊 Scoring Methodology

The risk score is calculated by adding penalties for various risk factors:

Risk Score = Name Penalties + Email Penalties + Document Weight

Risk Factors:

Name too short (< 2 chars): +0.1
Name too long (> 50 chars): +0.05
Special characters in name: +0.1
Invalid email format: +0.2
Disposable email domain: +0.3
Generic email domain: +0.15
Document type weight: +0.1 to +0.2

👤 Name Analysis

Length validation
Special character detection
Pattern recognition
Common name database

📧 Email Verification

Format validation
Domain reputation
Temporary email detection
Business vs. personal

📄 Document Assessment

Type classification
Validity checks
Risk weighting
Forgery indicators

🎯 Decision Thresholds

Score Range	Status	Action	Visual
`0.0 - 0.2`	✅ Approved	Automatic approval	🟢
`0.2 - 0.5`	🟡 Pending Review	Manual verification required	🟡
`0.5 - 1.0`	❌ Rejected	Automatic rejection	🔴

🔬 Response Structure

Each verification response includes the following fields:

{
  "verification_id": "ver_123e4567-e89b-12d3-a456-426614174000",
  "status": "approved",
  "risk_score": 0.1,
  "checks_performed": ["name", "email", "documentType"],
  "timestamp": "2025-10-05T14:30:00.000Z"
}

Field Descriptions:

verification_id - Unique identifier with 'ver_' prefix
status - Verification result (approved/pending_review/rejected)
risk_score - Calculated risk score (0.0 - 1.0)
checks_performed - List of validation checks executed
timestamp - ISO 8601 timestamp of verification

🏗️ Architecture

pathguard-api/
├── controllers/       # HTTP request handlers
├── services/          # Business logic and risk scoring
├── models/            # Database layer with Drizzle ORM
├── middleware/        # Custom middleware (validation, security)
├── routes/            # API route definitions
├── schemas/           # Zod validation schemas
├── utils/             # Utilities and mock data
└── database/          # Database configuration and migrations

🔄 Request Flow

sequenceDiagram
    participant Client
    participant Express
    participant Middleware
    participant Controller
    participant Service
    participant Database

    Client->>Express: POST /api/v1/kyc/verifications
    Express->>Middleware: Validate Input
    Middleware->>Controller: Valid Request
    Controller->>Service: Process Verification
    Service->>Service: Calculate Risk Score
    Service->>Database: Save Verification
    Database-->>Service: Confirmation
    Service-->>Controller: Verification Result
    Controller-->>Client: JSON Response

🎨 Available Scripts

npm run dev              # Development with hot reload
npm test                 # Run test suite with coverage
npm run migrate:generate # Generate new migrations
npm run migrate:apply    # Apply database migrations
npm start                # Production server

💼 Technical Highlights

Feature	Implementation
🏛️ Clean Architecture	Separation of concerns (Routes → Controllers → Services → Models)
🔒 Security	Input validation, CORS, Helmet security headers
📖 Documentation	Interactive Scalar Documentation with live examples
🗄️ Database	PostgreSQL with Drizzle ORM and migrations
🛡️ Smart Middleware	Custom Scalar detection prevents doc pollution
⚠️ Error Handling	Centralized error management with proper HTTP codes
✨ Code Quality	Conventional commits, modular structure

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

We welcome contributions! Here's how you can help:

🍴 Fork the repository
🌿 Create your feature branch (git checkout -b feature/amazing-feature)
💾 Commit your changes (git commit -m 'feat: add amazing feature')
📤 Push to the branch (git push origin feature/amazing-feature)
🎯 Open a Pull Request

💬 Support

Need help? Please open an issue in the repository.

👏 Acknowledgments

Built with modern web development best practices and industry-standard tools:

Express.js - Fast, unopinionated web framework
Node.js - JavaScript runtime
PostgreSQL - Advanced open source database
Drizzle ORM - TypeScript ORM
Scalar - API documentation
Zod - TypeScript-first schema validation
Vitest - Next generation testing framework

⭐ If you found this project helpful, please give it a star!

Made with ❤️ by thmslfb

Name		Name	Last commit message	Last commit date
Latest commit History 61 Commits
controllers		controllers
database		database
middleware		middleware
migrations		migrations
models		models
routes		routes
schemas		schemas
services		services
tests/unit		tests/unit
utils		utils
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
drizzle.config.js		drizzle.config.js
openapi.yaml		openapi.yaml
package-lock.json		package-lock.json
package.json		package.json
server.js		server.js
vitest.config.js		vitest.config.js

License

thmslfb/pathguard-api

Folders and files

Latest commit

History

Repository files navigation

🛡️ PathGuard API

✨ Features

🔐 Security & Verification

⚡ Developer Experience

🎯 Core Capabilities

🚀 Quick Start

🎯 First API Call

🛠️ Tech Stack

📦 Installation

1️⃣ Clone the Repository

2️⃣ Install Dependencies

3️⃣ Environment Configuration

4️⃣ Database Setup

5️⃣ Launch Application

📡 API Reference

🔗 Base URL

🎯 Examples

Perform identity verification

List all verifications

Query Parameters

Get verification by ID​

Delete verification by ID

Update verification status

🧠 Risk Scoring Algorithm

📊 Scoring Methodology

👤 Name Analysis

📧 Email Verification

📄 Document Assessment

🎯 Decision Thresholds

🔬 Response Structure

🏗️ Architecture

🔄 Request Flow

🎨 Available Scripts

💼 Technical Highlights

📜 License

🤝 Contributing

💬 Support

👏 Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Get verification by ID

Packages