📄 Document Verification System (DVS)

An enterprise-grade full-stack Document Verification System built with FastAPI, React, PostgreSQL, and Docker.

The application enables organizations to securely manage document verification workflows through Role-Based Access Control (RBAC), JWT Authentication, Email OTP Verification, OCR-powered document processing, Audit Logging, and a modern responsive dashboard for Employees, Verifiers, and Administrators.

Designed with scalability, maintainability, and security in mind, this project demonstrates industry-standard backend architecture and modern frontend development practices.

🖼️ Application Preview

✨ Table of Contents

Overview
Key Features
Role-Based Access Control
Technology Stack
System Architecture
Project Structure
Installation
Backend Setup
Frontend Setup
Docker Deployment
Database Migration
API Documentation
OCR Support
Screenshots
Security Features
Future Improvements
Contributing
License
Author

🚀 Overview

The Document Verification System simplifies and secures document verification processes by providing separate dashboards for different user roles.

Employees can upload and manage their documents, Verifiers can review and approve submitted files, while Administrators have complete control over users, verification workflows, audit logs, and system monitoring.

The application follows modern software engineering practices including:

Clean architecture
RESTful APIs
Secure authentication
Token-based authorization
OCR document extraction
Comprehensive audit logging
Responsive React frontend
Docker containerization

⭐ Key Features

🔐 Authentication & Security

Email Registration
Secure Login
Strong Password Policy
Email OTP Verification
JWT Authentication
Refresh Token Rotation
Token Revocation
Account Lockout Protection
Password History Validation
Forgot Password Workflow
Security Questions Verification
Date of Birth Verification
BCrypt Password Hashing
Security Headers Middleware
Rate Limiting
CORS Protection

👥 Role-Based Access Control (RBAC)

Three independent roles are supported throughout the application.

Role	Responsibilities
👤 Employee	Upload and manage personal documents
✅ Verifier	Review, approve and reject submitted documents
👑 Administrator	Complete system administration and monitoring

Administrators can promote users, manage permissions, monitor verification activities, and oversee the entire platform.

📂 Document Management

Secure File Upload
PDF Support
Image Support
File Type Validation
MIME Validation
File Size Validation
Filename Sanitization
OCR Text Extraction
Document Preview
Download Documents
Delete Documents
Verification Status Tracking

✅ Verification Workflow

The verification lifecycle includes:

Pending Queue
Review Requests
Document Approval
Document Rejection
Verification Remarks
Verification History
Audit Trail

👨‍💼 Administration

Administrators have access to:

User Management
Role Management
Account Activation
Account Deactivation
User Profiles
Verification Statistics
Document Oversight
Audit Log Viewer
Security Monitoring

📊 Audit Logging

Every important activity is securely recorded, including:

User Login
Logout
Registration
Password Changes
Password Reset Requests
Document Uploads
Verification Decisions
User Management
Role Changes
Administrative Operations
Client IP Address
Browser Information

🎨 Frontend Features

React 18
Vite
Tailwind CSS
Responsive Design
Dark Mode
Glassmorphism UI
Animated Components
OTP Input Component
Charts & Analytics
Drag & Drop Uploads
Protected Routes
Role-Based Navigation

🛠️ Technology Stack

Category	Technology
Backend	FastAPI
Frontend	React 18
Styling	Tailwind CSS
Database	PostgreSQL
ORM	SQLAlchemy 2.0
Validation	Pydantic v2
Authentication	JWT
Password Hashing	BCrypt
OCR Engine	Tesseract OCR
Database Migration	Alembic
Charts	Recharts
Testing	Pytest
Containerization	Docker
Version Control	Git & GitHub

🏗️ System Architecture

                        React Frontend
                              │
                              │ REST API
                              ▼
                     FastAPI Backend
                              │
     ┌───────────────┬───────────────┬───────────────┐
     ▼               ▼               ▼
 Authentication   Business Logic   OCR Processing
     │               │               │
     └───────────────┼───────────────┘
                     ▼
             SQLAlchemy ORM
                     │
                     ▼
               PostgreSQL

📁 Project Structure

document-verification-system/
│
├── backend/
│   ├── routers/
│   ├── services/
│   ├── middleware/
│   ├── models.py
│   ├── schemas.py
│   ├── database.py
│   ├── config.py
│   ├── auth.py
│   ├── dependencies.py
│   ├── main.py
│   ├── requirements.txt
│   ├── seed.py
│   ├── Dockerfile
│   └── .env.example
│
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   ├── components/
│   │   ├── context/
│   │   ├── hooks/
│   │   ├── routes/
│   │   └── services/
│   │
│   ├── public/
│   ├── package.json
│   ├── vite.config.js
│   ├── tailwind.config.js
│   ├── Dockerfile
│   └── nginx.conf
│
├── images_folder/
│   ├── admin_dashboard.jpg
│   ├── employee_dashboard.jpg
│   ├── verifier_dashboard.jpg
│   ├── verify_document.jpg
│   ├── upload_document.jpg
│   └── ...
│
├── docker-compose.yml
├── README.md
└── LICENSE

🔒 Security Highlights

✅ JWT Authentication
✅ Refresh Token Rotation
✅ Email OTP Verification
✅ BCrypt Password Hashing
✅ Secure Password Reset Workflow
✅ Password History Validation
✅ Account Lockout Protection
✅ Role-Based Authorization (RBAC)
✅ Audit Logging
✅ Security Headers
✅ Rate Limiting
✅ CORS Protection

⚙️ Local Development Setup

📋 Prerequisites

Before running the project, ensure the following software is installed:

Software	Recommended Version
Python	3.11+
Node.js	18+
npm	Latest
PostgreSQL	15+
Git	Latest
Docker Desktop (Optional)	Latest
Tesseract OCR	Latest

📥 Clone the Repository

git clone https://github.com/HuzaifaAIDev/document-verification-system.git

cd document-verification-system

🖥️ Backend Setup

Navigate to the backend directory:

cd backend

Create Virtual Environment

Windows

python -m venv .venv

.venv\Scripts\activate

Linux / macOS

python3 -m venv .venv

source .venv/bin/activate

Install Dependencies

pip install --upgrade pip

pip install -r requirements.txt

Configure Environment Variables

Create a local environment file:

cp .env.example .env

For Windows (PowerShell), if cp is unavailable:

copy .env.example .env

Open the .env file and configure the required values.

Example:

DATABASE_URL=postgresql://username:password@localhost:5432/document_verification

SECRET_KEY=your-generated-secret-key

ACCESS_TOKEN_EXPIRE_MINUTES=30

REFRESH_TOKEN_EXPIRE_DAYS=7

ALGORITHM=HS256

SMTP_SERVER=smtp.gmail.com

SMTP_PORT=587

SMTP_USERNAME=your-email@gmail.com

SMTP_PASSWORD=your-app-password

EMAIL_FROM=your-email@gmail.com

FRONTEND_URL=http://localhost:5173

Important: Never commit your .env file to GitHub. Only commit .env.example.

Generate a Secure Secret Key

Generate a secure secret key:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Copy the generated key into:

SECRET_KEY=

Create the Development Administrator

Run:

python seed.py

This script creates the default administrator account for local development.

Change the default credentials before deploying the application to production.

Run the Backend Server

uvicorn main:app --reload

Backend will be available at:

http://localhost:8000

📚 API Documentation

FastAPI automatically generates interactive API documentation.

Documentation	URL
Swagger UI	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc
OpenAPI Schema	http://localhost:8000/openapi.json

🌐 Frontend Setup

Open a new terminal.

Navigate to the frontend:

cd frontend

Install Dependencies

npm install

Configure Frontend Environment

Create the environment file:

cp .env.example .env

Example:

VITE_API_URL=http://localhost:8000

Start Development Server

npm run dev

Frontend:

http://localhost:5173

🐳 Docker Deployment

Docker allows the complete application stack to run inside containers.

Configure Backend Environment

cp backend/.env.example backend/.env

Update all required environment variables before deployment.

Build Containers

docker compose build

Start Containers

docker compose up

or

docker compose up --build

Run in Detached Mode

docker compose up -d

Stop Containers

docker compose down

🗄️ Services

Service	URL
React Frontend	http://localhost:5173
FastAPI Backend	http://localhost:8000
Swagger UI	http://localhost:8000/docs
PostgreSQL	localhost:5432

🗃️ Database Migration

This project uses Alembic for version-controlled database migrations.

Generate Migration

alembic revision --autogenerate -m "Initial Migration"

Apply Migration

alembic upgrade head

Roll Back One Migration

alembic downgrade -1

Show Current Migration

alembic current

🧪 Running Tests

Navigate to the backend directory:

cd backend

Run all tests:

pytest

Run with verbose output:

pytest -v

Generate a coverage report (if configured):

pytest --cov=.

📡 API Modules

Endpoint	Description
`/auth`	User authentication and authorization
`/users`	User profile management
`/documents`	Upload and document management
`/verifier`	Document verification workflow
`/admin`	Administrative operations

🔄 Verification Workflow

Employee
    │
    ▼
Upload Document
    │
    ▼
Pending Verification
    │
    ▼
Verifier Review
    │
 ┌──┴────────────┐
 │               │
 ▼               ▼
Approved      Rejected
 │               │
 ▼               ▼
Visible to User with Status

📁 Supported File Types

The application currently supports:

PDF (.pdf)
PNG (.png)
JPG (.jpg)
JPEG (.jpeg)

Additional formats can be integrated in future releases.

🔍 OCR Processing

The system integrates Tesseract OCR for extracting text from uploaded documents.

Extracted text can be utilized for:

Document verification
Search functionality
Metadata extraction
Data validation
Future AI-powered document analysis

OCR supports both scanned images and PDF documents.

📸 Application Screenshots

The following screenshots demonstrate the primary workflows and interfaces available within the Document Verification System.

🔐 Sign In

📝 Sign Up

🔑 Reset Password

👤 Employee Dashboard

📤 Upload Document

📂 My Documents

👤 Employee Profile

✅ Verifier Dashboard

📄 Verify Document

📜 Verification History

👥 Verifier User Details

👤 Verifier Profile

👑 Admin Dashboard

⚙️ Admin Console

👥 User Management

📋 Audit Logs

👤 Admin Profile

🔒 Security Features

The application has been designed with security as a primary objective.

Authentication

JWT Access Tokens
Refresh Token Rotation
Secure Logout
Token Revocation
Email OTP Verification
Password Reset Workflow

Password Protection

BCrypt Password Hashing
Password History Validation
Strong Password Policy
Account Lockout Protection

API Security

Role-Based Access Control (RBAC)
Security Headers Middleware
CORS Protection
Request Validation
Rate Limiting

Monitoring

Audit Logging
User Activity Tracking
Login History
Verification History
Administrative Action Logging

🚀 Future Improvements

The project roadmap includes several enhancements aimed at improving scalability, security, and user experience.

Planned Features

Multi-Factor Authentication (MFA)
Redis Caching
Elasticsearch Integration
AI-Powered Document Validation
Automatic Fraud Detection
Virus & Malware Scanning
Digital Signatures
Watermarking
WebSocket Notifications
Email Notifications
SMS Notifications
Kubernetes Deployment
CI/CD Pipeline
Cloud Storage Integration
Background Task Processing
Monitoring with Prometheus & Grafana
API Rate Analytics
Mobile Application Support

🌍 Production Deployment Recommendations

Before deploying to production, it is recommended to:

Enable HTTPS using a trusted SSL certificate.
Store secrets securely using environment variables or a secrets manager.
Use a managed PostgreSQL database.
Configure automated database backups.
Use a production SMTP provider.
Enable centralized logging.
Monitor application health.
Configure reverse proxy (Nginx or Traefik).
Enable firewall rules.
Rotate secrets regularly.
Restrict CORS origins.
Configure secure cookies.
Enable automatic security updates.

🤝 Contributing

Contributions are welcome and appreciated.

If you would like to contribute:

Fork the repository.
Create a feature branch.

git checkout -b feature/your-feature

Commit your changes.

git commit -m "Add new feature"

Push your branch.

git push origin feature/your-feature

Open a Pull Request.

Please ensure that:

Code follows the existing style.
New functionality includes appropriate tests where applicable.
Documentation is updated for any new features.

📜 License

This project is licensed under the MIT License.

See the LICENSE file for additional details.

👨‍💻 Author

Hafiz Muhammad Huzaifa

Bachelor of Science in Artificial Intelligence

Passionate about building secure, scalable, and production-ready AI and Full-Stack applications using modern software engineering practices.

Connect With Me

GitHub: https://github.com/HuzaifaAIDev

⭐ Acknowledgements

Special thanks to the open-source community and the maintainers of the technologies used in this project.

This project is powered by:

FastAPI
React
PostgreSQL
SQLAlchemy
Pydantic
Docker
Tesseract OCR
Tailwind CSS
Alembic
Pytest

💡 Support

If you find this project helpful:

⭐ Star the repository

🍴 Fork the repository

🐞 Report issues

💬 Share suggestions

📢 Share the project with others

Your support helps improve the project and motivates future development.

❤️ Thank You

Thank you for taking the time to explore the Document Verification System.

Feedback, suggestions, and contributions are always welcome.

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
backend		backend
frontend		frontend
images_folder		images_folder
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

📄 Document Verification System (DVS)

🖼️ Application Preview

✨ Table of Contents

🚀 Overview

⭐ Key Features

🔐 Authentication & Security

👥 Role-Based Access Control (RBAC)

📂 Document Management

✅ Verification Workflow

👨‍💼 Administration

📊 Audit Logging

🎨 Frontend Features

🛠️ Technology Stack

🏗️ System Architecture

📁 Project Structure

🔒 Security Highlights

⚙️ Local Development Setup

📋 Prerequisites

📥 Clone the Repository

🖥️ Backend Setup

Create Virtual Environment

Windows

Linux / macOS

Install Dependencies

Configure Environment Variables

Generate a Secure Secret Key

Create the Development Administrator

Run the Backend Server

📚 API Documentation

🌐 Frontend Setup

Install Dependencies

Configure Frontend Environment

Start Development Server

🐳 Docker Deployment

Configure Backend Environment

Build Containers

Start Containers

Run in Detached Mode

Stop Containers

🗄️ Services

🗃️ Database Migration

Generate Migration

Apply Migration

Roll Back One Migration

Show Current Migration

🧪 Running Tests

📡 API Modules

🔄 Verification Workflow

📁 Supported File Types

🔍 OCR Processing

📸 Application Screenshots

🔐 Sign In

📝 Sign Up

🔑 Reset Password

👤 Employee Dashboard

📤 Upload Document

📂 My Documents

👤 Employee Profile

✅ Verifier Dashboard

📄 Verify Document

📜 Verification History

👥 Verifier User Details

👤 Verifier Profile

👑 Admin Dashboard

⚙️ Admin Console

👥 User Management

📋 Audit Logs

👤 Admin Profile

🔒 Security Features

Authentication

Password Protection

API Security

Monitoring

🚀 Future Improvements

Planned Features

🌍 Production Deployment Recommendations