🔐 ExamVault

The Enterprise-Grade, AI-Powered Examination Platform.

ExamVault is a secure, modern platform for schools and independent learners to digitize, take, and grade exams. Specialized for CIE Physics (O-Level, IGCSE, A-Level), it leverages Large Language Models (Claude 3.5 Sonnet / GPT-4o) to provide instant, human-like marking and feedback.

🚀 Key Features

🧠 AI & Automation

• AI Grading Engine: Uses multimodal LLMs to grade structured answers and handwritten diagrams against strict markschemes.
• Digitization Toolkit: Python tools to convert PDF exam papers into structured Markdown + LaTeX.
• Auto-Sync: A background service that watches the repository and hydrates the PostgreSQL database instantly.

🛡️ Enterprise Security

• Mandatory 2FA: TOTP-based Two-Factor Authentication required for all users.
• Breach Protection: Integrated Have I Been Pwned check prevents using compromised passwords.
• Hardened API: Rate limiting (5 req/min), JWT sessions, and strict Role-Based Access Control (RBAC).

🏛️ For Teachers & Schools

• Batch Management: Manage 50+ students in batches.
• Gradebook Dashboard: Real-time visualization of class performance and "At Risk" students.
• Export Tools: Download CSV/PDF reports for school administration.

🎓 For Students

• Performance Trajectory: Interactive graphs tracking scores over time.
• Weakness Analysis: AI identifies specific topics needing improvement (e.g., "Thermal Physics").
• Personalized Feedback: Constructive critique on every answer.

---

🛠️ Tech Stack

• Frontend: Next.js 15, Tailwind CSS 4, Shadcn/UI, Recharts.
• Backend: Go (Golang) 1.23, Gin Framework.
• Database: PostgreSQL 15.
• Search: Meilisearch (for sub-50ms question lookups).
• Infrastructure: Docker & Docker Compose.

---

🐳 Quick Start (Docker)

The easiest way to run ExamVault is using Docker Compose.

1. Clone the repository:

   git clone https://github.com/fam007e/examvault.git
   cd examvault

2. Configure Environment: Create a .env file (or set variables in docker-compose.yml):

   export OPENAI_API_KEY="your-key"
   export AI_PROVIDER="openai" # or "anthropic", "ollama"
   export JWT_SECRET="super-secure-secret"

3. Launch:

   docker-compose up --build

4. Access:

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8080
   • Meilisearch: http://localhost:7700

---

🪄 Digitization Workflow

We use a GitOps approach for managing questions.

1. Generate Prompt: Run the helper tool to generate a digitization prompt for an exam paper.

   python3 tools/generate_prompt.py

   Enter code e.g., 9702_s21_qp_42.

2. AI Transcription: Paste the prompt and exam images into Claude 3.5 Sonnet. It will return a formatted .md file.

3. Save & Sync: Save the file to CAIE/A-Level/9702-Physics.... The Auto-Sync Service will detect it and populate the database.

---

🤝 Contributing

We welcome contributions! Please read our CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

🔮 Roadmap & Next Steps

• Core Architecture: Go + Next.js + PostgreSQL.
• AI Grading: Support for OpenAI, Anthropic, and Local LLMs.
• Security: Mandatory 2FA and HIBP breach checks.
• Dockerization: Complete containerized deployment.
• Automated PDF Parsing: A service to directly ingest official Past Paper PDFs.
• Meilisearch Sync: Real-time synchronization of the question bank for instant search.
• Multi-Subject Expansion: Broadening beyond Physics to Mathematics, Chemistry, and more.

📄 License

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