Academic Assignment Helper & Plagiarism Detector (RAG-Powered)

AI powered academic intelligence system that detects plagiarism, generates structured insights, and automates assignment submissions with verified academic integrity — built with FastAPI, pgVector, and n8n.

---

Project Overview Video

🎥 Watch the walkthrough: 👉 Academic Assignment Helper Overview (YouTube)

---

Table of Contents

1. Overview
2. System Architecture
3. Core Features
4. Tech Stack
5. Installation Guide
6. Docker Setup
7. Database Initialization
8. API Usage (Swagger)
9. Automation Workflows (n8n)
10. Automated Assignment Submission
11. Security
12. Project Phases Summary
13. Future Roadmap
14. Credits

---

Overview

The Academic Assignment Helper is a full-stack AI platform designed to empower students, educators, and researchers with intelligent academic evaluation tools.

It automates:

• Plagiarism detection with semantic vector comparison
• Context-aware analysis using RAG (Retrieval-Augmented Generation)
• Report generation and email notifications via n8n
• Automated instructor submission with a Plagiarism-Free Testimonial

✅ This project demonstrates production level workflow orchestration, AI integration, and academic automation — all within a Dockerized microservice ecosystem.

---

System Architecture

📦 academic-assignment-helper
├── backend/
│   ├── main.py                      # FastAPI app entrypoint
│   ├── routes_upload.py             # Upload & n8n trigger
│   ├── routes_analysis.py           # AI + RAG pipeline
│   ├── plagiarism_utils.py          # Chunking, embedding, scoring
│   ├── ai_utils.py                  # LLM (Friendli/HuggingFace)
│   ├── vector_utils.py              # Embedding, similarity, pgVector
│   ├── database.py / models.py      # SQLAlchemy ORM
│   ├── data/
│   │   ├── sample_academic_sources.json
│   │   ├── uploads/
│   │   └── ...
├── n8n_workflows/
│   ├── academic-assignment-helper (flow1).json  # Upload → Text Extraction
│   ├── academic-assignment-helper (flow2).json  # AI Result → Email Workflow
│   ├── n8n_workflows_readme.md
├── docker-compose.yml
├── .env.example
├── requirements.txt
└── README.md

---

Core Features

Feature	Description
AI Plagiarism Detection	Compares chunked assignment text against vectorized academic source embeddings using cosine similarity
RAG Analysis	Retrieves top-K similar sources and uses LLMs to generate structured insights
Automated n8n Workflows	Handles text extraction, notifications, and follow-up logic asynchronously
Rich HTML Email Reports	Sends formatted analysis reports with plagiarism scores and citation suggestions
Automated Assignment Submission	Students can approve sending their analyzed assignment directly to the instructor with academic integrity verification
End-to-End Docker Setup	FastAPI, PostgreSQL (pgVector), and n8n run in orchestrated containers

---

Tech Stack

• Language: Python 3.10 +
• Backend: FastAPI + SQLAlchemy
• Database: PostgreSQL + pgVector
• LLM Integration: Friendli.ai or HuggingFace
• Automation Engine: n8n
• Embeddings Model: sentence-transformers/all-MiniLM-L6-v2
• Containerization: Docker + Docker Compose

---

Installation Guide

1️⃣ Clone Repository

git clone https://github.com/NatiSami21/Dedication.git
cd academic-assignment-helper

2️⃣ Setup Environment

cp .env.example .env

Edit .env:

DATABASE_URL=postgresql+psycopg2://postgres:postgres@db:5432/academic_db
N8N_WEBHOOK_URL=http://n8n:5678/webhook/assignment
N8N_NOTIFY_URL=http://n8n:5678/webhook/notify-analysis-done
FRIENDLI_API_KEY=your_friendli_key
FRIENDLI_ENDPOINT_ID=your_model_id

3️⃣ Install Python Dependencies

pip install -r requirements.txt

---

Docker Setup

docker-compose build
docker-compose up

This starts:

• FastAPI Backend → http://localhost:8000
• Swagger UI → http://localhost:8000/docs
• n8n Automation Engine → http://localhost:5678
• PostgreSQL (pgVector)

---

Database Initialization

1. Load Sample Academic Sources

   docker exec -it academic_fastapi bash
   python -m backend.init_sources

2. Generate Source Embeddings

   curl -X POST http://localhost:8000/analysis/embed-sources

3. Create Vector Index

   curl -X POST http://localhost:8000/analysis/index-sources

---

API Usage (Swagger)

Visit → http://localhost:8000/docs

1. Register (/auth/register)
2. Login (/auth/login) and copy JWT token
3. Upload (/upload/) assignment file (.pdf or .docx)
4. n8n automatically extracts text → triggers /analysis/ack
5. AI Analysis runs in background
6. Retrieve results: /analysis/{assignment_id}

Example response:

{
  "status": "done",
  "plagiarism_score": 12.5,
  "flagged_sections": [...],
  "suggested_sources": [...],
  "research_suggestions": [...],
  "citation_recommendations": [...]
}

---

Automation Workflows (n8n)

Flow 1 — Assignment Intake

Trigger: POST /webhook/assignment Pipeline:

1. Receive upload event from FastAPI
2. Read file from /app/data/uploads
3. Extract text from .pdf or .docx
4. Forward structured payload to /analysis/ack

→ Implements the AI processing trigger.

---

Flow 2 — Analysis Completion & Notification

Trigger: POST /webhook/notify-analysis-done Pipeline:

1. Receives AI + plagiarism results

2. Generates formatted HTML report

3. Sends email to the student using SMTP

4. Presents Send to Instructor form (Send & Wait node)

5. On approval:

   • Sends email to instructor
   • Attaches assignment file
   • Includes “Plagiarism-Free” testimonial summary

✅ Supports full automated academic submission loop.

---

Automated Assignment Submission

This is the extended feature you added in Phase 3.4.4.

Flow Logic:

1. Student receives analysis email → “Send to Instructor?” prompt

2. If approved and email field provided → n8n triggers a second email

3. Instructor receives:

   • The analyzed assignment file
   • Student details (name, ID, email)
   • Verified plagiarism-free testimonial
   • Summary metrics & citation recommendations

This process allows confidential self checking before instructor submission, preserving privacy yet supporting official submission automation.

---

Security

• JWT-based student authentication
• SQLAlchemy ORM (no raw SQL injection risk)
• Input sanitization before vector embedding
• n8n communication restricted to internal Docker network

---

Project Phases Summary

Phase	Description	Status
0	Docker & FastAPI Setup	✅
1	File Upload & Metadata	✅
2	AI Plagiarism & Similarity Engine	✅
3.1–3.3	Vector Embeddings + RAG Integration	✅
3.4.1–3.4.4	n8n Automation & Submission Flow	✅
4	Evaluation & Documentation	🔄

---

Author

Natinael Samuel Software Engineer | Dedicated fullstack developer afritioalberts1216@gmail.com Addis Ababa, Ethiopia +251904161978

---