VendorShield AI

AI-Powered Third-Party Risk Management Platform

Automate vendor risk assessments, track compliance frameworks, and leverage AI-driven risk scoring to protect your organization from third-party threats.

Getting Started • API Documentation • Architecture • Deployment

---

Features

• Vendor Lifecycle Management — Onboard, monitor, and manage vendors through a centralized platform
• AI-Powered Risk Scoring — Machine learning models (scikit-learn) that analyze vendor data and assign dynamic risk scores
• Compliance Tracking — Built-in support for SOC 2, ISO 27001, HIPAA, and PCI DSS frameworks
• Risk Assessments — Create, assign, and review structured risk assessments with questionnaire templates
• Continuous Monitoring — Real-time threat intelligence and risk event tracking
• AI Auto-Fill — Intelligent form auto-completion for assessment questionnaires
• Notifications — Configurable alerts for risk changes, compliance deadlines, and vendor updates
• Dashboard Analytics — Comprehensive security insights and reporting
• Vendor Portal — Self-service portal for vendors to submit documentation
• Background Tasks — Celery workers for async processing of heavy operations

---

Tech Stack

Layer	Technology
Framework	FastAPI 0.109 with Uvicorn ASGI server
Language	Python 3.11+
Database	PostgreSQL 15 (production) / SQLite (development)
ORM	SQLAlchemy 2.0 (async) + Alembic migrations
Cache / Broker	Redis 7
Task Queue	Celery 5.3 + Flower monitoring
AI/ML	scikit-learn, NumPy
Auth	JWT (python-jose) + bcrypt password hashing
Validation	Pydantic v2
Containerization	Docker + Docker Compose
Testing	pytest + pytest-asyncio

---

Project Structure

vendorshield-api/
├── app/
│   ├── api/
│   │   ├── deps.py              # Dependency injection
│   │   └── v1/                  # API v1 route handlers
│   │       ├── assessment.py
│   │       ├── compliance.py
│   │       ├── monitoring.py
│   │       ├── notification.py
│   │       ├── organization.py
│   │       ├── risk.py
│   │       ├── user.py
│   │       └── vendor.py
│   ├── models/                  # SQLAlchemy ORM models
│   │   ├── assessment.py
│   │   ├── compliance.py
│   │   ├── dashboard.py
│   │   ├── monitoring.py
│   │   ├── notification.py
│   │   ├── organization.py
│   │   ├── risk.py
│   │   ├── user.py
│   │   └── vendor.py
│   ├── schemas/                 # Pydantic request/response schemas
│   ├── services/                # Business logic layer
│   │   ├── ai_autofill.py
│   │   ├── ai_risk_scoring.py
│   │   ├── auth.py
│   │   ├── compliance_mapping.py
│   │   ├── file_storage.py
│   │   ├── questionnaire_templates.py
│   │   └── risk_events.py
│   ├── utils/                   # Utility functions
│   ├── config.py                # Application settings
│   ├── database.py              # Database connection setup
│   ├── main.py                  # FastAPI app entry point
│   └── worker.py                # Celery worker config
├── alembic/                     # Database migrations
├── tests/                       # Test suite
│   ├── conftest.py
│   ├── test_assessments.py
│   ├── test_auth.py
│   ├── test_compliance.py
│   ├── test_health.py
│   ├── test_notifications.py
│   ├── test_risks.py
│   └── test_vendors.py
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── alembic.ini
├── pytest.ini
└── main.py                      # Dev server entry point

---

Getting Started

Prerequisites

• Python 3.11+
• PostgreSQL 15+ (or use SQLite for local dev)
• Redis 7+
• Docker & Docker Compose (optional)

Local Development

# Clone the repository
git clone https://github.com/mejba13/vendorshield-api.git
cd vendorshield-api

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
alembic upgrade head

# Start the development server
python main.py

The API will be available at http://localhost:8000.

Docker Compose (Recommended)

# Start all services (API + PostgreSQL + Redis + Celery Worker)
docker-compose up --build

# Run in detached mode
docker-compose up --build -d

This starts:

Service	Port	Description
API	8000	FastAPI application
PostgreSQL	5432	Database
Redis	6379	Cache & message broker
Celery Worker	—	Background task processing

---

API Documentation

Once the server is running, interactive documentation is available at:

Format	URL
Swagger UI	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc
OpenAPI JSON	http://localhost:8000/openapi.json

API Endpoints

All endpoints are prefixed with /api/v1:

Module	Endpoint	Description
Auth	/api/v1/auth	Registration, login, JWT token management
Users	/api/v1/users	User profile and management
Vendors	/api/v1/vendors	Vendor CRUD and lifecycle management
Assessments	/api/v1/assessments	Risk assessment workflows
Risks	/api/v1/risks	Risk scoring and event tracking
Compliance	/api/v1/compliance	Compliance framework tracking
Monitoring	/api/v1/monitoring	Continuous monitoring and alerts
Dashboard	/api/v1/dashboard	Analytics and reporting
Notifications	/api/v1/notifications	Alert management
Vendor Portal	/api/v1/vendor-portal	Vendor self-service portal
Reports	/api/v1/reports	Report generation

Authentication

The API uses JWT Bearer tokens. Include the token in the Authorization header:

Authorization: Bearer <your_access_token>

---

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│   Client     │────▶│  FastAPI     │────▶│  PostgreSQL     │
│  (Frontend)  │◀────│  (Uvicorn)  │◀────│  (Database)     │
└─────────────┘     └──────┬──────┘     └─────────────────┘
                           │
                    ┌──────┴──────┐
                    │             │
              ┌─────▼─────┐ ┌────▼────┐
              │   Redis    │ │ Celery  │
              │  (Cache)   │ │ Worker  │
              └───────────┘ └─────────┘

---

Environment Variables

Variable	Default	Description
DATABASE_URL	sqlite+aiosqlite:///./vendorshield.db	Async database connection string
DATABASE_URL_SYNC	sqlite:///./vendorshield.db	Sync database connection string
REDIS_URL	redis://localhost:6379/0	Redis connection URL
SECRET_KEY	—	JWT signing secret (change in production!)
ALGORITHM	HS256	JWT algorithm
ACCESS_TOKEN_EXPIRE_MINUTES	30	JWT access token TTL
CORS_ORIGINS	http://localhost:3000,...	Comma-separated allowed origins
CELERY_BROKER_URL	redis://localhost:6379/1	Celery broker URL
OPENAI_API_KEY	—	OpenAI API key for AI features
ENVIRONMENT	development	Runtime environment
DEBUG	false	Enable debug mode

---

Testing

# Run the full test suite
pytest

# Run with verbose output
pytest -v

# Run a specific test module
pytest tests/test_vendors.py

# Run tests with coverage
pytest --cov=app

---

Deployment

Docker (Production)

# Build the production image
docker build -t vendorshield-api .

# Run with Docker Compose
docker-compose -f docker-compose.yml up -d

Environment Setup

1. Set DEBUG=false and ENVIRONMENT=production
2. Use a strong, unique SECRET_KEY
3. Configure DATABASE_URL to point to your production PostgreSQL instance
4. Configure REDIS_URL for your Redis instance
5. Set CORS_ORIGINS to your frontend domain(s)

---

Developed By

Engr Mejba Ahmed

AI Developer | Software Engineer | Entrepreneur

---

Hire / Work With Me

I build AI-powered applications, mobile apps, and enterprise solutions. Let's bring your ideas to life!

Platform	Description	Link
Fiverr	Custom builds, integrations, performance optimization	fiverr.com/s/EgxYmWD
Mejba Personal Portfolio	Full portfolio & contact	mejba.me
Ramlit Limited	Software development company	ramlit.com
ColorPark Creative Agency	UI/UX & creative solutions	colorpark.io
xCyberSecurity	Global cybersecurity services	xcybersecurity.io

---

Built with FastAPI + AI/ML for intelligent vendor risk management