MAJD AYOUB.SYS
ENGINEERING METHODOLOGY & CASE STUDIES

Projects & Open Source

terminal FLAGSHIP PROJECT
GRADUATION PROJECT • DEFENDED JAN 2026

TruthLens: An AI-Assisted Credibility Assessment Platform

Senior Capstone Project • Al-Balqa Applied University • Supervised by Eng. Nawal Al-Zabin • Defended Jan 2026
Python FastAPI Redis Celery Docker ChromaDB Ollama RAG NLP

Strategic Vision: Built as a Decision Support System (DSS) that augments human judgment rather than replacing it. It delivers multi-dimensional, bilingual (Arabic & English) analysis synthesizing linguistic patterns, contextual cues, and source credibility against high-velocity misinformation.

TruthLens Interface Preview
Interface_Preview_01.png Res: 1080p
query_stats

Key Metrics & Impact

SYSTEM_IMPACT // SCALE
66.5% Latency Reduction 9.70s → 3.25s
59.7% Docker Reduction 15.4GB → 6.2GB
70 REST APIs Clean endpoints
14 API Routers Modular gateways
19 Backend Services System topology
8 Concurrent Services Parallel analysis
info

Project Overview

SYSTEM_CONTEXT // OBJECTIVES
// THE PROBLEM

High-Velocity Misinformation

Misinformation spreads faster than verification can keep up. Arabic content lacks automated credibility tools, and manual fact-checking cannot scale against modern platforms.

// THE MISSION

Bilingual Decision Support

Build a Decision Support System that augments human judgment, delivering bilingual (Arabic & English) credibility analysis by synthesizing linguistic patterns, sources, and AI.

// TECHNICAL OWNERSHIP

End-to-End Implementation

Led the end-to-end software engineering implementation, owning architecture design, backend services, Celery/Redis async orchestration, ChromaDB RAG, and Docker setup.

// INGESTION LAYER

Hybrid Document Pipeline

Intelligent ingestion using pdfplumber for digital PDFs (~100x faster than OCR) and falling back to pytesseract OCR (configured for dual eng+ara) for scanned files.

engineering

Technical Highlights

SOLUTIONS // METRICS
// SOLUTION_01 Concurrency

⚡ 66.5% Latency Reduction

Problem: Sequential execution of independent verification tasks.

Solution: Concurrent execution via asyncio.gather.

Result: 9.70s → 3.25s.

// SOLUTION_02 VRAM Limit

🧠 < 5 GB VRAM Deploys

Problem: Concurrent model loading causing OOM crashes.

Solution: Dynamic lifecycle swapping via Ollama.

Result: Deployed on 6 GB consumer GPUs.

// SOLUTION_03 Image Size

📦 59.7% Smaller Docker

Problem: Image bundled CUDA and weights inflating size to 15.40 GB.

Solution: CPU PyTorch + volume weight mounts + uv optimization.

Result: 15.40 GB → 6.20 GB.

// SOLUTION_04 Inference Boot

⏱️ Near-Instant Cold Starts

Problem: Model loading introducing up to 45 seconds of delay on cold start.

Solution: Pre-warm Qwen3 on boot + OLLAMA_KEEP_ALIVE=-1.

Result: Immediate inference response.

// SOLUTION_05 Resource Save

🔍 < 5 ms Early Exit

Problem: Escalating simple inputs to full LLM reasoning is resource-heavy.

Solution: Lightweight TF-IDF + Logistic Regression pre-classification.

Result: Under 5 ms classification skips LLM when confidence is high.

// SOLUTION_06 Resilient Parsing

🛠️ Resilient JSON Parsing

Problem: Local LLMs outputting malformed JSON schemas causing parser crashes.

Solution: 4-stage JSON recovery (brace count, regex, Phi-3 syntax fallback).

Result: Highly resilient structured reports.

// SOLUTION_07 Fail-Safe HTTP

🛡️ Fail-Safe HTTP Clients

Problem: External OSINT API failures causing cascading backend blocks.

Solution: Central client + circuit breakers + retry transports.

Result: Outages isolated without halting pipeline.

// SOLUTION_08 PROTOTYPE

🧩 Chrome Extension Popup

Problem: Making assessments accessible without leaving webpage contexts.

Solution: Scraper scripts enqueuing background tasks to FastAPI.

Result: One-click credibility metrics overlay over active articles.

// SOLUTION_09 Automated QA

🧪 Automated QA Testing

Problem: Concurrency issues and response timeouts during peaks.

Solution: Pytest suites, Locust load test scripts, and execution benchmarks.

Result: 100% execution safety verified under simulated workloads.

Architecture Status Multi-Model Consensus + RAG Pipeline
HUD_GAUGE_01 // SYSTEM_VALIDATED
Technical Report description LinkedIn Article article
settings_suggest

Engineering Decisions

DESIGN_CHOICES // WHY_NOT_WHAT
🧠 Local LLMs Privacy & Offline
⚙️ Microservices Independent Scaling
📈 SSE Streaming Real-time Progress
✉️ Redis + Celery Background Tasks
📦 ChromaDB RAG Semantic Retrieval
🔒 Privacy-First PII Redacted
📝 Composite Prompts Fewer VRAM Swaps
🔗 Blockchain OSINT Wallet Analysis
🏆 Tiered Reputation Weighted Scoring
📖 Entity Enrichment Wikipedia Context
play_circle

Watch Demo

DEMO_SCREENCAST // METADATA
Architecture Local RAG Pipeline
Technical Report Zenodo DOI open_in_new
Chrome Extension Popup Client
Deployment Stack Docker Compose (FastAPI, Celery, Redis, Ollama)
Google Drive Video Mirror (Download Fallback) open_in_new Academic Project • Augments human workflows
school What I Learned Building This expand_more
  • • Orchestration focus: AI systems are orchestration problems more than model problems.
  • • Architecture impact: Clean boundaries and design have a greater impact than just upgrading model weights.
  • • Explainability: Direct structured output and source reputation are core product requirements, not just AI features.
  • • Responsiveness: Decoupling tasks asynchronously via Celery and Redis dramatically improves user experience.
  • • Local deployment constraints: Managing hardware resources like VRAM is a major bottleneck not found in cloud deployments.
psychology What I'd Improve Next expand_more
  • • Database Session Pooling: Refactor worker DB hooks to utilize connection pools to prevent socket exhaustion during concurrent load spike events.
  • • VRAM Offloading Engines: Deploy quantized models (AWQ/GPTQ) using vLLM to scale multi-user processing safely.
  • • Micro-Frontends Structure: Decouple dashboard UI into separate micro-frontends (scrapers, charts) to minimize core asset weights.
  • • Mock testing integration: Expand integration tests to simulate LLM endpoints to allow faster continuous builds without GPUs.

Curious about the technologies behind these systems?

See the technologies behind these systems →
// Merged Open Source Contribution

OpenSSF cve-bin-tool

terminal
What it is: Merged Python pull request to OpenSSF cve-bin-tool, an open-source security scanner.
Problem: "cve bin tool.log.LOGGER is not a valid type" mypy logger typing issue (Issue #2870).
Fix: Explicit logging.Logger typing and restored centralized shared logger usage across files.
Result: Successfully resolved type checking errors and aligned related test coverage, resulting in a merged PR.
Stack: Python · mypy · logging · unit tests · security scanning

PhishGuard Pro

security
What it is: AI/NLP powered detector for phishing emails, SMS scams, and financial fraud.
What I built: BERT based classification engine and security guidance utility.
Stack: BERT, RAG, Python, PyTorch
Proof / Links:
GitHub open_in_new
Quick Demo:

AI-powered phishing and scam email analysis with threat probability, indicators, and explainable guidance.

BayForge AI

architecture
What it is: Educational AI prototype for exploring California ADU zoning data.
What I built: Frontend interface and API routes for property analysis. ⚠️ Not legal advice; development stopped due to data integrity and legal risk concerns.
Stack: Next.js, TypeScript, Tailwind CSS
Proof / Links:
GitHub open_in_new

MCP Notebook

library books
What it is: Reference guide and development suite for Anthropic's Model Context Protocol (MCP).
What I built: Transport pattern simulators, interactive Vercel prototype, and notion engineering docs.
Stack: MCP API, Next.js, Vercel, Notion

Clickbait Detector

warning
What it is: Automated classification engine to identify and flag sensationalized headlines.
What I built: Machine learning classifier achieving 96.39% test accuracy.
Stack: NLP, Python, Scikit-learn

Fake News Detector

policy
What it is: Machine learning model trained to evaluate veracity and potential bias in news articles.
What I built: TF-IDF feature pipeline and logistic regression classifier packaged using Skops.
Stack: Scikit-learn, TF-IDF, Skops, Gradio, Hugging Face Spaces

Full Stack Intern

terminal
What it is: Structured 280-hour Full-Stack Web Development Internship at Jordan Computer Society.
What I built: Flask/Jinja2 server-side prototypes, responsive layouts, SQL CRUD interfaces, and custom DOM logic.
Stack: Flask, Jinja2, SQL, Bootstrap, JavaScript
Proof / Links:
JCS Internship Certificate Verified

Curious about the technologies behind these systems?

Explore my Engineering Stack →
terminal TruthLens Engineering Workspace
// TruthLens Key Engineering Summary
66.5% Faster Pipeline
59.7% Smaller Image
< 5 ms Early Exit
4-Serv Deployment
65+ Endpoints
// Interactive System Topology

Interactive Flow & Process Sequence

Hover over the sequence cards below to highlight downstream execution paths and see how asynchronous broker routines decouple computationally heavy operations from the client request loop.

language
Browser
  • • Vanilla JavaScript
  • • REST + SSE
bolt
FastAPI Gateway
  • • Authentication
  • • Validation
  • • REST API Routing
dns
Redis
  • • Caching
  • • Task Queue
  • • Pub/Sub
settings_suggest
Celery Workers
  • • Background Tasks
  • • Retry Logic
  • • Async Processing
psychology
Qwen3
  • • Deep Reasoning
  • • Claim Analysis
memory
Phi-3 Mini
  • • JSON Repair
  • • Structured Output
analytics
NLP Pipeline
  • • CAMeL-BERT
  • • Sentiment
  • • Toxicity
folder_open
Knowledge Layer
  • • ChromaDB
  • • OCR
  • • OSINT Sources
check_circle
Results
  • • Credibility Assessment
  • • PDF Report
  • • JSON API

Explore middleware, model orchestration, Redis messaging, asynchronous workers, OCR pipeline, RAG workflow, caching strategy, and deployment architecture.

// SYSTEM_DETAIL // AUDITED

Complete System Architecture

★ FULL DETAIL
Client / API
FastAPI Gateway
Redis Layer
Celery Workers
GPU: Qwen3 8B
CPU Models
OSINT APIs
Report Output

Layer 01 // Client Interface

User Experience
🌐 Client Browser (PWA)

Vanilla JavaScript progressive web app interface featuring Server Sent Events (SSE) live progress updates.

Layer 02 // API & Routing Gateway

FastAPI Core · main.py
🛡️ Security Middlewares

SecurityHeaders (HSTS, CSP, XSS protection), GZip compressions (min 1KB), and CORS policies.

🚦 Rate Limiter & Sentry

Protects endpoints (5 analyze/min, 200 poll/min limit) and integrates Sentry for error telemetry.

📡 14 API Routers & validation

Authenticates routes and validates inputs against 40+ Pydantic models.

Layer 03 // Memory Cache & Broker

Redis 7 Alpine
💾 Result Cache

Stores analysis reports mapped by MD5 body hash parameters (24h TTL cache skip).

📬 Task Broker Queue

Manages Celery message distribution queuing for background analysis threads.

📢 Pub/Sub Bus

Directs real-time task progress events instantly back to SSE event listeners.

Layer 04 // Async Celery Workers

celery worker.py
⚙️ Task Handlers

Handles process analysis task and query llm task workflows with automatic retry rules and 600s timeouts.

🧠 Process Preloaders

Initializes and pre loads ML models in worker memory at startup to avoid subsequent cold start delays.

Layer 05 // Unified Model Cortex

Models
// GPU Inference Path
💜 Qwen3 (8B) LLM

Primary semantic reasoning engine. Performs claim extraction, logical fallacy checks, bias auditing, timeline mapping, and processes output via a custom 4 strategy JSON schema recovery.

// CPU Inference Path
💚 Phi 3 Mini (3.8B) Executes JSON schema repair tasks and structured response validation formatting.
🧡 CAMeL BERT & RoBERTa Linguistic sentiment analysis (CAMeL BERT for Arabic, Cardiff NLP for English).
🖤 Detoxify & Skops Multilingual toxicity screening and machine learning based clickbait detection pipeline.

Layer 06 // Data & Evidence Sources

RAG & Crawling
📚 Vector Stores (RAG)
  • • ChromaDB: RAG context index (threshold 0.45).
  • • FAISS: Sentence Transformers indexing.
🔍 OSINT APIs & Scrapers
  • • APIs: Google FactCheck, RSS, DDGS, VirusTotal, Wikipedia.
  • • Scrapers: Newspaper3k, Trafilatura, ScraperAPI (anti bot tier).
📄 Multimodal OCR Ingest
  • • Tesseract: Arabic and English image text scanning.
  • • pdfplumber: PDF reader + visual fallback.

Layer 07 // Outputs & Persistent Services

Evaluation & Storage
🎯 Credibility Scoring

Logic evaluation formula producing final credibility grade tiers.

🎓 Socratic Coaching

Personalized critical thinking guidance generated for users.

📑 PDF & JSON Exports

Formatted ReportLab PDF generator and detailed JSON structures.

☁️ Firestore Cache Proxy

Saves finalized analysis records permanently to database.

Architecture Status Multi-Model Consensus + RAG Pipeline
HUD_GAUGE_01 // SYSTEM_VALIDATED
Technical Report description LinkedIn Article article