TranscriptEnhance

Transform plain AUI (Al Akhawayn University) transcripts into professional PDF reports with GPA trends, grade analytics, and academic insights.

---

What It Does

Upload an AUI transcript PDF and get back:

• Structured JSON with student info, courses, grades, and GPA calculations
• Professional PDF report with charts, tables, and academic insights — ready for job applications or grad school submissions

Report Highlights

Section	Details
Header	Student identity, cumulative GPA, credit hours
GPA Analysis	Semester vs cumulative GPA line chart, best/worst semesters
Grade Distribution	Donut chart + statistics table
Credit Hours	Grouped bar chart (attempted / earned / GPA hours)
Subject Breakdown	Horizontal bar chart by subject area
Course Tables	Semester-grouped tables with color-coded grades
Degree Progress	Visual progress bar, GPA projections
Academic Insights	Dean's List, top courses, heaviest loads, efficiency

---

Tech Stack

Layer	Technology
Backend API	Python 3.11+, FastAPI, Pydantic
PDF Parsing	pdfplumber
Report Generation	ReportLab, Matplotlib, Pillow
Frontend	Next.js 16, React 19, TypeScript
Styling	Tailwind CSS v4, shadcn/ui, Radix UI

---

Quick Start

Prerequisites

• Python 3.11+ and pip
• Node.js 18+ and pnpm (or npm/yarn)
• Or just Docker (see below)

1. Clone the repo

git clone https://github.com/IhabProjects/TranscriptEnhance.git
cd TranscriptEnhance

2. Backend

cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env

uvicorn app.main:app --reload --port 8000

API docs are live at http://localhost:8000/docs

3. Frontend

cd frontend
pnpm install
cp .env.example .env.local

pnpm dev

Open http://localhost:3000

4. Docker (one command)

docker compose up --build

Backend → http://localhost:8000
Frontend → http://localhost:3000

---

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
POST	/extract	Upload PDF → get structured JSON
POST	/extract/file	Local file path → JSON
POST	/generate-report	Upload PDF → get professional PDF report
POST	/generate-report/file	Local file path → PDF report
GET	/docs	Interactive Swagger UI

Examples

# Extract transcript data as JSON
curl -X POST http://localhost:8000/extract \
  -F "file=@transcript.pdf"

# Generate PDF report
curl -X POST http://localhost:8000/generate-report \
  -F "file=@transcript.pdf" -o report.pdf

---

Project Structure

TranscriptEnhance/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py          # FastAPI app, endpoints, CORS
│   │   ├── models.py         # Pydantic data models
│   │   ├── parser.py         # PDF text extraction (pdfplumber)
│   │   ├── grades.py         # Grade-point mapping & GPA helpers
│   │   └── report.py         # PDF report generator (ReportLab + Matplotlib)
│   ├── pdf_files/             # Drop transcripts here for local testing
│   ├── requirements.txt
│   ├── Dockerfile
│   └── .env.example
├── frontend/
│   ├── app/                   # Next.js app router pages
│   ├── components/            # React components + shadcn/ui
│   ├── lib/                   # API client, types, utils
│   ├── package.json
│   ├── Dockerfile
│   └── .env.example
├── docker-compose.yml
├── Makefile
└── README.md

---

Environment Variables

Backend (backend/.env)

Variable	Description	Default
HOST	Server bind address	0.0.0.0
PORT	Server port	8000
ALLOWED_ORIGINS	CORS origins (comma-separated)	http://localhost:3000
LOG_LEVEL	Logging level	INFO

Frontend (frontend/.env.local)

Variable	Description	Default
NEXT_PUBLIC_API_URL	Backend API base URL	http://localhost:8000

---

Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with care for AUI students.