Fypguard

Automated Document Blueprint Verification & Content Relevance Auditor
Compare student final year project (FYP) reports and postgraduate theses against departmental templates (.docx / .pdf) with engineering precision.

🧭 Overview

FYPGuard is a full-stack automated compliance auditor built for university FYP coordinators, supervisors, and students. Instead of manually inspecting hundreds of pages for font drift, missing mandatory sections, or leftover boilerplate placeholders, FYPGuard extracts a structured Specification Schema from your university template and verifies submitted documents against it.

Core Capabilities

• V1 Format & Fill-Compliance Checker:

  • Hierarchical Outline & Numbering Matching: Compares submitted document structure against template specifications using exact code matching, exact title matching, and fuzzy string distance.
  • Typography & Dimensional Tolerances: Inspects heading and body font family, point size (pt), and line spacing tolerances.
  • Placeholder & Instructional Content Detection: Scans for unreplaced template text (e.g. [Write Project Title Here], <Insert Student ID>, SESSION 2022-2026).
  • Content Ownership (direct vs container): Understands parent chapter headers (e.g., Chapter 1: Introduction) that serve purely as container groupings for subsections and should not be flagged as empty.
  • Word Field-List Intelligence: Recognizes Table of Contents, List of Figures, and List of Tables as Word field-generated paragraph lists, preventing false-positive table/figure missing alerts.
  • Neutral Appendix & Optional Short-Circuiting: Automatically marks appendices and optional sections as non-mandatory (is_required = False), ensuring they never trigger red alarms or drag down the compliance score.

• V2 AI Content Relevance Checker:

  • Evaluates whether the written prose in each section aligns with the declared project title and domain.
  • Supports Google Gemini, Anthropic Claude, OpenAI GPT, or a built-in Local Semantic Heuristic Model (no API key required).

• Three Non-Destructive Export Modes:

  1. Mode 1 — Annotated Reference Copy (.docx): Injects native Word comments (word/comments.xml) anchored directly to flagged paragraphs and headings in the review panel, preserving 100% of original layout, margins, and formatting.
  2. Mode 2 — Read-Only Reference Specimen (.pdf): Generates an official locked PDF inspection record with audit metadata, compliance score, and discrepancy matrix that cannot be edited.
  3. Mode 3 — Issues-Only Summary Report (.docx): A standalone engineering discrepancy checklist table for quick remediation.

• Dual-Contrast Architectural Blueprint UI:

  • Light Mode: High-contrast architectural drafting paper (#eef2f6), visible cyan gridlines, crisp white cards, and WCAG AA contrast text.
  • Dark Mode: Deep navy CAD inspection console with cyan glowing vectors and technical dimension-line callouts (⊢──────⊣).

⚡ Quick Start

Option A: 1-Click Launch (Windows)

Simply double-click the start.bat file in the project root:

start.bat

What start.bat does automatically:

1. Checks Python and Node.js prerequisites.
2. Creates the Python virtual environment (.venv) and installs requirements.txt if not present.
3. Installs frontend dependencies (npm install) if missing.
4. Starts both FastAPI and Vite servers concurrently in a single terminal.
5. Automatically opens your browser to http://127.0.0.1:5173/.

Option B: Unified Python Runner (Cross-Platform)

# Run with Python
python run.py

Press Ctrl+C in the terminal to cleanly terminate both backend and frontend servers simultaneously.

Option C: Manual Setup

1. Backend Setup

# Create and activate virtual environment
python -m venv .venv

# Windows
.\.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start FastAPI server
uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload

2. Frontend Setup

cd frontend
npm install
npm run dev

Open http://127.0.0.1:5173/ in your web browser.

🏗️ System Architecture

FYPGuard/
├── backend/
│   ├── main.py                     # FastAPI routes & export handlers
│   ├── models.py                   # Pydantic data schemas & compliance models
│   ├── extraction/
│   │   ├── docx_extractor.py       # OOXML AST parser for headings, fonts, styles
│   │   └── pdf_extractor.py        # PDF text, table, and structure extractor
│   ├── engine/
│   │   ├── matching_engine.py      # Section alignment & fuzzy matching pipeline
│   │   ├── compliance_checker.py   # Rule evaluation, tolerances & scoring logic
│   │   ├── relevance_checker.py    # V2 scope & title relevance evaluator
│   │   └── docx_annotator.py       # OOXML Word comment injection & PDF generation
│   └── storage/
│       └── template_store.py       # JSON template and report persistence
│
├── frontend/
│   ├── src/
│   │   ├── App.tsx                 # Root application component
│   │   ├── api.ts                  # Backend REST API client
│   │   ├── types.ts                # TypeScript interface definitions
│   │   ├── index.css               # Blueprint design system tokens & themes
│   │   └── components/
│   │       ├── Navbar.tsx          # Engineering header & contrast toggle
│   │       ├── CheckRunner.tsx     # Intake station (specimen + target blueprint)
│   │       ├── ComplianceReportViewer.tsx # Interactive blueprint inspection report
│   │       ├── VisualRemapEditor.tsx      # Interactive template calibration editor
│   │       ├── TemplateHub.tsx     # University specification catalogue
│   │       └── LLMSettingsModal.tsx# AI relevance engine calibration
│
├── data/
│   ├── templates/                  # Stored department template schemas
│   ├── uploads/                    # Uploaded submitted documents
│   └── reports/                    # Cached compliance reports & exports
│
├── requirements.txt                # Python backend dependencies
├── start.bat                       # Windows 1-click startup script
├── run.py                          # Unified multi-process runner
└── .gitignore                      # Git exclusion rules

📊 Evaluation & Scoring Model

Compliance scores are computed against mandatory template sections only (optional sections and appendices are excluded from the score denominator):

$$\text{Overall Score} = \left( 0.40 \times S_{\text{structure}} \right) + \left( 0.40 \times S_{\text{fill}} \right) + \left( 0.20 \times S_{\text{typography}} \right)$$

• Structure Score ($S_{\text{structure}}$): Proportion of mandatory sections detected and aligned.
• Fill Score ($S_{\text{fill}}$): Absence of unreplaced instructional placeholders and empty body content.
• Typography Score ($S_{\text{typography}}$): Adherence to specified font families, font sizes (pt), and line spacings within calibrated tolerances ($\pm 1.0\text{ pt}$, $\pm 0.35\text{ line}$).

📡 API Reference

| Method | Endpoint | Description | | :--- | :--- | :--- | | GET | /api/templates | List all registered department specifications | | GET | /api/templates/{id} | Retrieve full section schema for a blueprint | | POST | /api/templates/upload | Ingest a new .docx or .pdf guideline template | | PUT | /api/templates/{id} | Update section hierarchy, ownership, or tolerances | | POST | /api/check | Execute compliance audit on uploaded specimen | | GET | /api/reports/{id} | Fetch JSON audit report data | | GET | /api/reports/{id}/export-annotated | Mode 1: Download .docx with native Word comments | | GET | /api/reports/{id}/export-readonly | Mode 2: Download locked, unmodifiable .pdf record | | GET | /api/reports/{id}/export-summary | Mode 3: Download .docx discrepancy checklist table |

🧪 Included Sample Files

The repository includes pre-configured reference files for immediate testing:

• AI_DS_Thesis_Template_Final.docx: Sample Department of AI & Data Science postgraduate thesis specification.
• Updated Template-07 - Final Project Report-2.docx: Complete 105-section Software Engineering FYP specification.
• Robo-Litation Report.docx: Realistic FYP submission specimen containing formatting drift, tables, figures, and placeholders for evaluation testing.

📄 License

MIT License. Designed for academic institutions and software engineering capstone audit automation.