🎓 Smart Assignment Checker

Smart Assignment Checker is a sophisticated, AI-powered platform designed to revolutionize the way educators manage and evaluate student submissions. By leveraging advanced Large Language Models (LLMs) and a robust full-stack architecture, it automates the grading process, providing detailed feedback, performance insights, and administrative efficiency.

---

🚀 Key Features

👨‍🏫 For Educators (Teachers)

• Intelligent Dashboard: At-a-glance view of total assignments, submission rates, AI evaluation progress, and class-wide average scores.
• AI-Driven Insights: Receives periodically generated recommendations based on student performance trends to help adjust teaching strategies.
• Bulk Submission Processing: upload multiple student PDFs in one go. The system automatically maps files to students based on naming conventions.
• Automated Evaluation Engine: Assignments are automatically evaluated using AI agents once the deadline passes, ensuring fair and consistent grading.
• Customizable Marking: Define specific evaluation instructions and "Marking Modes" for the AI to follow.
• Data Export: Export all submission results, including detailed score breakdowns, directly to CSV for external record-keeping.

🎓 For Students

• Seamless Submissions: Clean interface to upload PDF assignments with instant confirmation.
• Submission History: Track the status of all submitted assignments and view AI-generated feedback once released.

🤖 Core AI Technology

• Multi-Agent Orchestration: Powered by OpenAI's latest agentic frameworks for deep content analysis.
• Smart PDF Parsing: High-fidelity text extraction from PDF documents for precise evaluation.
• Granular Feedback: Generates not just a score, but a detailed breakdown and qualitative remarks for every submission.

---

🛠️ Tech Stack

Frontend

• Framework: Next.js 15+ (App Router, React 19)
• Styling: Tailwind CSS 4.0 (High-performance, modern CSS)
• State Management: Zustand
• Data Fetching: TanStack Query v5
• Forms & Validation: React Hook Form & Zod

Backend

• Framework: NestJS 11+ (Node.js)
• Database: MongoDB with Mongoose
• Authentication: Passport.js (JWT Strategy)
• File Storage: Cloudinary (Secure PDF hosting)
• Task Scheduling: NestJS Schedule (CRON jobs for auto-evaluation)
• AI Integration: OpenAI SDK (Agent-based evaluation)

---

📁 Project Structure

├── client/                 # Next.js Frontend
│   ├── app/                # App Router (Pages & Layouts)
│   ├── components/         # Atomic design (Atoms, Molecules, Organisms)
│   ├── hooks/              # Custom React hooks (Auth, API)
│   ├── store/              # Zustand state stores
│   └── lib/                # API clients and utilities
├── server/                 # NestJS Backend
│   ├── src/
│   │   ├── ai/             # AI Agents, Runners, and Model Config
│   │   ├── assignments/    # Core logic (Assignments, Submissions, Evaluation)
│   │   ├── auth/           # JWT & Passport Authentication
│   │   ├── users/          # User management
│   │   └── common/         # Global filters, interceptors, Cloudinary service
│   └── test/               # E2E and Unit tests
└── README.md               # You are here!

---

⚙️ Setup & Installation

Prerequisites

• Node.js (v18+)
• MongoDB (Local or Atlas)
• OpenAI API Key
• Cloudinary Account (Cloud Name, API Key, API Secret)

1. Clone the Repository

git clone https://github.com/your-username/smart-assignment-checker.git
cd smart-assignment-checker

2. Backend Configuration

cd server
npm install

Create a .env file in the server directory:

PORT=5000
MONGO_URI=your_mongodb_uri
JWT_SECRET=your_secret_key
OPENAI_API_KEY=your_openai_key
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

Run the server:

npm run start:dev

3. Frontend Configuration

cd ../client
npm install

Create a .env.local file in the client directory:

NEXT_PUBLIC_API_URL=http://localhost:5000

Run the client:

npm run dev

---

🔄 Project Flow

1. Teacher Creates Assignment: Sets instructions, deadline, and marking mode.
2. Student Submits: Uploads a PDF. The file is securely stored on Cloudinary.
3. Deadline Monitoring: The backend's CRON service monitors deadlines.
4. AI Evaluation: Once the deadline is reached, the AI Agent fetches the PDF content, evaluates it against the teacher's instructions, and stores the scores/remarks.
5. Results Published: Students can view their feedback, and teachers can export the data or view collective insights.

---

📝 License

This project is licensed under the MIT License.

---

Built with ❤️ for educators who want to focus more on teaching and less on manual grading.