Learnixo
All Projects
Healthcareadvanced View on GitHub

Enterprise Verification System

Production KYC/KYP microservice — AI confidence scoring, human-in-the-loop review, state machines, and GDPR compliance

1–2 hours to run standalone15 technologies9 guided steps

About This Project

Originally built as an isolated bounded context inside MedScribe AI, the Enterprise Verification System is a standalone microservice for identity and credential verification at scale. It implements a full KYC/KYP pipeline: users submit documents, an AI pipeline scores confidence, human admins make the final call. The architecture uses DDD bounded contexts, a strict state machine (no invalid transitions possible), optimistic locking for concurrent reviews, and a full GDPR-compliant audit trail. Built to EU AI Act Article 14 standards — AI signals, humans decide.

What You'll Learn

Implement a DDD bounded context with no cross-domain imports
Build a state machine that makes invalid transitions structurally impossible
Apply optimistic locking to prevent concurrent update conflicts
Design a human-in-the-loop AI pipeline compliant with EU AI Act Article 14
Build a GDPR-compliant audit trail with AI vs human decision recording
Structure a FastAPI service with repository pattern and clean domain models

Key Features

✓AI confidence scoring on submitted documents — never makes the final decision
✓Human-in-the-loop review: admin approves or rejects with reason
✓Strict state machine: PENDING → IN_REVIEW → APPROVED / REJECTED — no invalid transitions
✓Optimistic locking with version counter prevents concurrent review conflicts
✓Full audit trail: every status change, reviewer ID, AI suggestion vs human decision
✓AI–human divergence logging: records every case where human overrides AI
✓GDPR-compliant: personal data purge endpoint, data minimisation by design
✓10 REST endpoints: submit, upload documents, list, review, resubmit, audit log
✓Typed React frontend: submit form, admin list with filters, detail view with all panels
✓File security: MIME type allowlist, 10 MB limit, storage abstraction (swap to Azure Blob/S3)
✓Fully isolated bounded context — zero imports from other domains
✓RBAC via JWT role claim: regular users see own cases, admins see all

Project Structure

directory tree
MedScribe-AI/
└── src/medscribe/verification/   ← The entire module (bounded context)
    ├── enums.py                  ← VerificationStatus, DocumentType, VerificationAction
    ├── models.py                 ← Domain models (pure Python, no DB imports)
    ├── repository.py             ← 4 repository classes, all DB I/O here
    ├── service.py                ← State machine, optimistic locking, AI scoring
    ├── security.py               ← File validation — MIME allowlist, size limits
    ├── storage.py                ← File I/O abstraction (swap local → Azure Blob/S3)
    └── __init__.py

    src/medscribe/api/
    └── verification_routes.py   ← 10 REST endpoints

    frontend/src/verification/
    ├── types.ts                  ← TypeScript interfaces matching backend exactly
    ├── api.ts                    ← Typed fetch wrappers
    ├── VerificationUpload.tsx    ← Submit form with drag-and-drop
    ├── VerificationList.tsx      ← Admin/user list with status filters
    └── VerificationDetail.tsx    ← Detail view: AI panel, audit timeline, review actions

Setup Guide

1

Clone the MedScribe AI repository

The verification system lives in its own isolated bounded context inside the repo. Clone and navigate in.

bash
git clone https://github.com/asmanasir/MedScribe-AI.git
cd MedScribe-AI
2

Create a Python virtual environment and install dependencies

The verification module uses FastAPI, SQLAlchemy async, Pydantic v2, and structlog.

bash
python -m venv .venv

# Activate — Linux/macOS:
source .venv/bin/activate

# Activate — Windows:
.venv\Scripts\activate

pip install -e ".[dev]"
3

Configure environment variables

Copy the example .env. For the verification module, SQLite is the default dev database — no PostgreSQL setup needed locally.

bash
cp .env.example .env

# Key settings for the verification module:
# DATABASE_URL=sqlite+aiosqlite:///./medscribe.db   (default)
# JWT_SECRET_KEY=change-this-in-production
# STORAGE_BACKEND=local
# UPLOAD_DIR=./uploads
# MAX_FILE_SIZE_MB=10
4

Install frontend dependencies

The React frontend for the verification module is in /frontend. Install npm packages.

bash
cd frontend
npm install
cd ..

Running the Project

1

Start the FastAPI backend

The backend starts on port 8000. The verification endpoints are under /api/v1/verification/.

bash
# Ensure venv is activated
source .venv/bin/activate

python -m medscribe

# Swagger UI available at:
# http://localhost:8000/docs
2

Start the React frontend

In a second terminal, start the Vite dev server on port 3000.

bash
cd frontend
npm run dev

# Open http://localhost:3000
3

Register two users — one regular, one admin

Use the API to register a regular user and an admin. The role claim in the JWT determines what each user can see.

bash
# Register a regular user
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"Test1234!","role":"user"}'

# Register an admin
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"Admin1234!","role":"admin"}'
4

Submit a verification case and observe the state machine

Log in as the regular user, submit a case, then log in as admin and move it through the states. Every transition is validated — try PENDING → APPROVED directly and watch the 409.

bash
# 1. Login as user → get token
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -d "username=user@example.com&password=Test1234!" | jq -r '.access_token')

# 2. Submit a verification case
CASE=$(curl -s -X POST http://localhost:8000/api/v1/verification/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document_type":"passport","notes":"Initial submission"}')

CASE_ID=$(echo $CASE | jq -r '.id')

# 3. Login as admin and start review
ADMIN_TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -d "username=admin@example.com&password=Admin1234!" | jq -r '.access_token')

# Move to IN_REVIEW
curl -X PUT http://localhost:8000/api/v1/verification/admin/$CASE_ID/review \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"action":"start_review"}'

# Approve
curl -X PUT http://localhost:8000/api/v1/verification/admin/$CASE_ID/review \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -d '{"action":"approve"}'

# View full audit trail
curl http://localhost:8000/api/v1/verification/$CASE_ID/audit \
  -H "Authorization: Bearer $TOKEN"
5

Run the test suite

The verification module has full unit test coverage — service logic, state machine, and repository layer.

bash
pytest tests/ -v -k "verification"

Project Info

CategoryHealthcare
Difficultyadvanced
Setup time1–2 hours to run standalone
Technologies15 tools

Tech Stack

Python 3.11+FastAPISQLAlchemy 2.0 (async)Pydantic v2pydantic-settingsaiosqlite (dev)PostgreSQL (prod)React 18TypeScriptViteTailwind CSS v4JWT (HS256)structlogCelery + Redis (prod jobs)Docker

Prerequisites

  • Python 3.11+ installed
  • Node.js 18+ installed
  • Git installed
  • Basic familiarity with Python async and React
View Source on GitHub
AN

Asma Nasir

Project Author

Extracted from MedScribe AI as a reusable enterprise pattern. The bounded context isolation, state machine, optimistic locking, and GDPR audit trail are directly applicable to any system requiring identity verification — healthcare, fintech, legal, or enterprise onboarding.

Related Courses

AI for Developers Python & FastAPI Docker & Kubernetes