A full-stack web application that analyzes writing patterns and provides evidence-based insights about whether portions of an essay resemble AI-generated text. The app features a complete integrated Machine Learning pipeline using a hybrid Fusion Model combining deep learning DistilBERT transformer logits and hand-crafted linguistic features.
- User Authentication — Secure session-based authentication using iron-session (with bcryptjs password hashing and SHA-256 forgot password token hashing).
- Essay Submission — Paste essay text directly or upload files (.txt, .docx, .pdf).
- Real AI Analysis — Dynamic integration with a FastAPI Python service running the trained Fusion Random Forest classifier (Experiment D, 98.89% Test Accuracy).
- Signal Breakdown — Detailed measurements across 5 custom features: Perplexity, Sentence Variation, Vocabulary Diversity, Repetition, and Stylometric Consistency.
- Visual Sentence Highlights — Color-coded highlights classifying each sentence (
ai-likein red,human-likein green,uncertainin yellow) with detailed explanation panels. - Short-Text Safeguards — Built-in word count safety filters that default essays shorter than 15 words to a neutral 50.0 score with warning disclaimers to prevent false positives.
- Analysis History & Documents — Manage uploaded documents, view, filter, search, and sort past analyses.
- MySQL Persistence — Database tracking for users, essays, analyses, signals, and text segments via Prisma ORM.
| Layer | Technology |
|---|---|
| Frontend | Next.js 16 (App Router), React 19, Tailwind CSS v4, JavaScript |
| Backend | Next.js API Routes (Server-side) + iron-session |
| ML Inference | Python 3.11, FastAPI, Uvicorn, Hugging Face Transformers |
| ML Algorithms | TF-IDF LR (A), Linguistic RF (B), DistilBERT (C), Fusion Random Forest (D) |
| Database | MySQL v8.0 + Prisma ORM |
| Email Service | Nodemailer + Ethereal SMTP fallback (logs reset URLs locally to scratch/reset-emails.log) |
ai-essay-detector/
│
├── frontend/ # Next.js Full-Stack Web Application
│ ├── app/ # App Router Views, Layouts, and API Routes
│ │ ├── api/ # Next.js API Routes (Auth, Essays, Analysis)
│ │ └── ... # Frontend Pages (Dashboard, Reset Password)
│ ├── components/ # React UI Components
│ ├── hooks/ # Custom Client React Hooks
│ ├── lib/ # Next.js Shared Core Utilities (Auth, Session)
│ ├── services/ # Next.js Service Layers (ai-detector, storage)
│ ├── public/ # Static Public Assets and Document Uploads
│ ├── package.json # Next.js Package Dependencies and Config
│ ├── next.config.mjs # Next.js Config (reads parent .env)
│ └── ... # Tooling configurations (eslint, postcss, jsconfig)
│
├── backend/ # Architectural Placeholders
│ ├── api/
│ ├── routes/
│ ├── services/
│ └── middleware/
│
├── ml/ # Python Machine Learning Pipeline & FastAPI Service
│ ├── src/ # ML Inference Code & Feature Extractors
│ │ ├── data/ # Ingestion, Schema, and Partition Scripts
│ │ ├── features/ # Perplexity, Burstiness, and Stylometry Heuristics
│ │ ├── models/ # Classifiers (Baseline, Linguistic, Fusion)
│ │ ├── evaluation/ # Calibration and Retraining Experiments
│ │ └── inference_service.py # FastAPI Service Endpoint
│ ├── data/ # Data Assets (raw, processed, models)
│ │ ├── raw/ # Example & Balanced HC3 JSONL Datasets
│ │ ├── splits/ # Train, Validation, and Test Manifests
│ │ └── processed/ # Trained Weights & Transformer Checkpoints
│ └── requirements.txt # Python ML Package Requirements
│
├── database/ # Database ORM Layout
│ ├── prisma/ # Prisma Schema & Migrations Folder
│ │ ├── schema.prisma # Active Database Schema Definition
│ │ └── migrations/ # Database Migration SQL Scripts
│ └── README.md # Database instructions
│
├── tests/ # Integration and E2E Test Suite
│ └── integration/ # JS & Python E2E flow tests
│ ├── test-flow.js # Authentication flow test runner
│ ├── test_ml_flow.py # FastAPI endpoint tests
│ ├── test_next_integration.js # Integration connection tests
│ └── test_user_flow.py # Unified E2E flow test runner
│
├── scratch/ # Transient log directory (git-ignored)
│ └── reset-emails.log # Password reset email log
│
├── .env # Active Environment Variables Configuration
├── .env.example # Environment Variables Example Template
├── .gitignore # Core Git Ignore configuration
├── README.md # Project Root Setup Documentation
└── FINAL_STATUS.md # Last verification audit log
- Node.js 18+ (recommended: 20+)
- Python 3.11.x
- MySQL 8.0+ running locally
- npm package manager
- Install Next.js dependencies inside the
frontend/directory:cd frontend npm install cd ..
- Set up the Python virtual environment and install ML pipeline dependencies:
python -m venv .venv # Windows PowerShell: .venv\Scripts\Activate.ps1 # Upgrade pip & install: pip install -r ml/requirements.txt
Copy .env.example to .env at the root directory and update with your credentials:
cp .env.example .envEnsure it contains:
DATABASE_URL="mysql://root:YOUR_PASSWORD@localhost:3306/ai_essay_detector"
SESSION_SECRET="your-32-char-random-session-secret-key"
NEXT_PUBLIC_APP_URL="http://localhost:3000"
DETECTOR_MODE="real"
ML_API_URL="http://localhost:8000"- Run MySQL and create the database:
CREATE DATABASE ai_essay_detector;
- Generate the Prisma Client inside
frontend/node_modules/by running from the root:npx --prefix frontend prisma generate --schema=database/prisma/schema.prisma
- Push the schema to MySQL:
npx --prefix frontend prisma db push --schema=database/prisma/schema.prisma
From the project root:
$env:PYTHONPATH="."
.venv\Scripts\python ml/src/inference_service.pyFrom the project root:
npm run dev(Runs the Next.js dev server on port 3000 via script delegation. The app will be live at http://localhost:3000).
To run automated pipeline and integration tests, ensure both ports are clean and execute:
- ML Pipeline Unit Tests:
.venv\Scripts\python -m pytest ml/src/tests/test_pipeline.py
- Unified E2E Integration Suite:
$env:PYTHONPATH="." .venv\Scripts\python tests/integration/test_user_flow.py