Content
# SchoolMind AI — Intelligent School Operating System
> **The AI-powered pedagogy, fee intelligence, and lesson generation platform for Indian schools.**
SchoolMind AI is a production-grade educational management platform built on a **Model Context Protocol (MCP) microservices architecture**. Principals, Coordinators, and Class Teachers can assess students, analyse fees, generate lesson content, and query an AI Copilot in natural language — all from one cohesive dashboard.
---
## 🌐 Live Deployment
| Service | URL |
|---|---|
| 🎛️ Main Dashboard (Orchestrator) | [schoolmind-ai-nmdp.onrender.com](https://schoolmind-ai-nmdp.onrender.com) |
| 🧠 Pedagogy MCP | [schoolmind-pedagogy.onrender.com](https://schoolmind-pedagogy.onrender.com) |
| 💰 Fee Analytics MCP | [schoolmind-fee-analytics.onrender.com](https://schoolmind-fee-analytics.onrender.com) |
| 📚 LessonCraft MCP | [schoolmind-lessoncraft.onrender.com](https://schoolmind-lessoncraft.onrender.com) |
---
## 📂 Project Resources & Documentation
- 📊 **System Presentation PPT**: [SchoolMind_AI_Presentation.pptx](SchoolMind_AI_Presentation.pptx)
- 📝 **Technical Documentation Manual**: [SchoolMind_AI_Documentation.docx](SchoolMind_AI_Documentation.docx)
---
## 📌 Table of Contents
1. [Platform Architecture](#️-platform-architecture)
2. [Workflow Diagrams](#-workflow-diagrams)
3. [Project Resources & Documentation](#-project-resources--documentation)
4. [MCP Tool Catalog](#-mcp-tool-catalog)
5. [User Roles & Access Control](#-user-roles--access-control)
6. [Key Features](#-key-features)
7. [Tech Stack](#-tech-stack)
8. [Environment Variables](#-environment-variables)
9. [Local Installation Guide](#-local-installation-guide)
10. [Production Deployment (Render)](#-production-deployment-render)
---
## 🏗️ Platform Architecture
SchoolMind AI is structured as an **npm workspace monorepo** of four independent Node.js services, orchestrated through a central ReAct agent loop backed by Google Gemini AI.
```
SchoolMind-AI/ ← npm workspace root
├── apps/
│ ├── orchestrator-agent/
│ │ ├── frontend/ ← React 18 + Vite (SchoolMind AI Dashboard)
│ │ └── backend/ ← Express orchestrator + auth + DB models
│ ├── pedagogy-mcp/ ← MCP Server: student records & SGI engine
│ ├── fee-analytics-mcp/ ← MCP Server: billing & default risk analytics
│ └── lessoncraft-mcp/ ← MCP Server: AI lesson/worksheet generator
└── packages/
└── shared-types/ ← Shared TypeScript types & utilities
```
### Full System Architecture
```mermaid
graph TD
subgraph Browser["🌐 Browser (React 18 + Vite SPA)"]
UI["Dashboard Views\nAssess · FeeAnalytics · LessonCraft · Settings · AI Copilot"]
end
subgraph Orchestrator["🧠 Orchestrator Agent (Express + Node.js)"]
Router["Express Router\n/api/auth · /api/students\n/api/pedagogy · /api/ai"]
Auth["JWT Auth Middleware"]
AICtrl["AI Controller\nReAct Loop (5 turns max)"]
Gemini["Gemini 1.5 Flash\nAPI Key Rotation Pool\n(KEY_1 → KEY_2 → KEY_3)"]
Fallback["Heuristic Fallback\nRouter (offline mode)"]
Assembly["AssemblyAI\nVoice Transcription"]
end
subgraph MCPs["⚙️ MCP Microservices (JSON-RPC over HTTP)"]
PedMCP["📋 Pedagogy MCP :5001\n– student CRUD\n– SGI calculation\n– learning gap scan"]
FeeMCP["💰 Fee Analytics MCP :5003\n– fee CSV ingestion\n– default risk scoring\n– manual fee entry"]
LsnMCP["📚 LessonCraft MCP :5002\n– lesson plan generator\n– worksheet & quiz maker\n– homework & revision AI"]
end
subgraph Storage["🗄️ Storage Layer"]
Mongo[("MongoDB Atlas\nStudents · PedagogyRecords\nFeeRecords · Teachers\nAcademicYears")]
end
UI -->|"/api/* (relative)"| Router
Router --> Auth --> AICtrl
AICtrl -->|"Tool calls (JSON-RPC)"| PedMCP & FeeMCP & LsnMCP
AICtrl --> Gemini
Gemini -->|"All keys fail"| Fallback
AICtrl --> Assembly
PedMCP --> Mongo
FeeMCP --> Mongo
Orchestrator --> Mongo
```
---
## 🔄 Workflow Diagrams
### 1. Teacher Onboarding & Security Setup
Security questions are hashed with bcrypt at registration. During password reset and academic year archiving, answers are compared case-insensitively.
```mermaid
graph LR
Reg["Teacher Registration\nName · Email · EmpID\nPassword · Role · Class"] --> QA["Select 3 Security Questions\n& Enter Answers"]
QA --> Hash["bcrypt.hash(answer.toLowerCase().trim())"]
Hash --> DB[("Save to MongoDB")]
Rst["Settings → Reset Password"] --> Verify["Verify 3 Security Answers\n(case-insensitive bcrypt compare)"]
Verify -->|"✅ Match"| NewPwd["Hash & Save New Password"]
Verify -->|"❌ Fail"| Err["Return 400 Incorrect Answers"]
```
### 2. AI Copilot — ReAct Orchestration Loop
```mermaid
sequenceDiagram
autonumber
participant Teacher
participant Orch as Orchestrator (ReAct Loop)
participant Gemini as Gemini 1.5 Flash
participant MCP as MCP Servers
Teacher->>Orch: Natural Language Query
Orch->>Orch: Mask PII (Aadhaar / Mobile)
loop Up to 5 turns
Orch->>Gemini: Prompt (query + tool catalog + history)
Gemini-->>Orch: JSON action: call_tool | respond
alt call_tool
Orch->>MCP: JSON-RPC tools/call (with x-mcp-token)
MCP-->>Orch: Tool result JSON
Orch->>Orch: Append result to history
else respond
Orch-->>Teacher: Final markdown response + trace log
end
end
Note over Orch,Gemini: If Gemini fails → Heuristic Fallback Router
```
### 3. MCP Cold-Start Retry (Render Free Tier)
```mermaid
graph TD
Call["callMcpTool(server, tool, args)"] --> Req["HTTP POST /mcp\n(JSON-RPC 2.0)"]
Req -->|"200 OK"| Parse["Parse result.content[0].text"]
Req -->|"502/503/504"| Retry{"Attempt ≤ 5?"}
Retry -->|"Yes"| Wait["Exponential Backoff\n2s → 4s → 8s → 16s → 32s"]
Wait --> Req
Retry -->|"No"| Throw["Throw last error\n→ Fallback Router"]
```
### 4. Academic Year Archiving (Principal Only)
```mermaid
sequenceDiagram
autonumber
participant Principal
participant Controller as Year Controller
participant DB as MongoDB
Principal->>Controller: Archive Request (securityAnswers, confirmYear, newYear)
Controller->>DB: Fetch Principal Security Hashes
DB-->>Controller: Hashed QA answers
Controller->>Controller: bcrypt.compare (case-insensitive)
alt Verification fails
Controller-->>Principal: 401 Unauthorized
else Verification passes
Controller->>DB: Set AcademicYear.archived=true, isCurrent=false
Controller->>DB: Flag all students in year as archived=true
Controller->>DB: Create new AcademicYear, isCurrent=true
Controller-->>Principal: 200 Success — New Year Active
end
```
---
## 🛠️ MCP Tool Catalog
### 📋 Pedagogy MCP (`/mcp` · port 5001)
| Tool | Arguments | Description |
|---|---|---|
| `search_student_by_name` | `name` | Case-insensitive name search → returns student ID |
| `get_student_complete_profile` | `studentId` | Full profile: metadata + all term pedagogy + fee records |
| `create_student_profile` | `rollNo, name, class, section, teacherId` | Onboard new student with blank term records |
| `upload_class_csv` | `csvString, teacherId` | Bulk onboard students from raw CSV string |
| `submit_term_assessment` | `studentId, teacherId, term, academics, participation, behaviour, learningStyle, observations, teacherRemarks` | Save/update term assessment and recalculate SGI |
| `calculate_student_growth_index` | `studentId` | Calculate SGI from saved assessment data |
| `generate_growth_report` | `studentId` | SGI trend lines and academic progression across terms |
| `identify_learning_gaps` | `class, section` | Scan classroom for low SGI or weak academic scores |
### 💰 Fee Analytics MCP (`/mcp` · port 5003)
| Tool | Arguments | Description |
|---|---|---|
| `upload_fee_csv` | `csvContent` | Ingest fee CSV into database |
| `validate_fee_csv` | `csvContent` | Validate CSV structure without saving |
| `fee_collection_trend` | *(none)* | Term-wise collection totals |
| `identify_fee_defaulters` | *(none)* | Students with outstanding balances |
| `generate_fee_summary` | *(none)* | School-wide financial KPIs |
| `class_fee_report` | `class, section` | Per-student fee audit for a classroom |
| `predict_fee_risk` | *(none)* | Default probability scores for pending accounts |
| `generate_recovery_plan` | `studentId` | Personalised payment recovery notice |
| `save_manual_fee` | `rollNo, name, class, section, term, totalDue, amountPaid, dueDate` | Manual fee entry with PK/FK student lookup |
### 📚 LessonCraft MCP (`/mcp` · port 5002)
| Tool | Arguments | Description |
|---|---|---|
| `upload_chapter_card` | `fileContent (base64), mimeType, fileName` | Extract learning objectives from a chapter card PDF/image |
| `extract_chapter_data` | `text` | Extract objectives from a raw text description |
| `generate_lesson_plan` | `class, subject, topic, difficulty` | CBSE-compliant lesson plan |
| `generate_worksheet` | `topic, count` | Student evaluation worksheet with answer guide |
| `generate_quiz` | `topic, count, type` | MCQ/short-answer quiz with answer keys |
| `generate_homework` | `topic, durationMinutes` | Curriculum-aligned homework tasks |
| `generate_revision_plan` | `studentNames, weakSubject, topic` | Personalised revision roadmap for weak students |
---
## 👥 User Roles & Access Control
| Role | Capabilities |
|---|---|
| **Principal** | School-wide analytics, academic year archive/restore (security-gated), all class access |
| **Academic Coordinator** | Student assessments overview, learning style distributions, parent summaries |
| **Class Teacher** | CSV roster import, pedagogy form fill & save, AI student diagnostics for own class |
| **Subject Teacher** | View student reports, submit subject-specific evaluations |
All roles authenticate via JWT. Role is enforced server-side on every protected route.
---
## 🌟 Key Features
### 🤖 AI Copilot (ReAct Agent)
- **Token-Efficient Prompt Builder**: Dynamic, contextual prompt generation that reduces context-token window usage by over 70% per turn.
- **AssemblyAI LeMUr Intent Detection**: Direct classification of user intents (student, staff, fees, lesson, quiz, gaps, or general) from audio transcriptions.
- **Formatted Layout Rule**: Mandates a ~50-word summary at the top, followed by structured markdown tables and graphical progress bars (e.g. `[████████░░] 80%`).
- Multi-turn orchestration loop (up to 8 turns) over 3 MCP servers
- Conversation history persistence (`localStorage`) — switching tabs does not clear chat
- Exponential backoff retry for Render cold-start 502/503/504 errors
- Quadruple Gemini API key rotation pool (including base `GEMINI_API_KEY`) with dummy key filtering
- Offline heuristic fallback router for student profiles, learning gaps, fee defaulters, and lesson plans
- Overall student personality and behavioural verdict queries supported natively and in fallback
- PII masking (Aadhaar / Indian mobile numbers) before any Gemini prompt
- Voice input via AssemblyAI transcription API with instant mic track release and closure-safe mute checks
### 📋 Student Assessment
- 25-field pedagogy form: academics (5 sliders), participation, behaviour, learning style, observation tags, teacher remarks
- Roster sidebar and main Dashboard sorting (Roll Number, Alphabetical name, and Assessment Completion %)
- Auto-fetching class roster based on teacher role / active student class & section on mount
- CSV bulk onboarding with column validation and pre-created blank term records
- SGI (Student Growth Index) auto-calculated on every save
### 💰 Fee Intelligence
- Manual fee entry form with Primary/Foreign Key student lookup (roll no → `_id`)
- CSV fee ingestion pipeline with validation preview
- Default risk scoring, term trend charts, and recovery plan generation
- School-wide financial KPI summary
### 📚 LessonCraft
- CBSE-compliant lesson plan, worksheet, quiz, homework, and revision plan generation
- Chapter card upload (PDF/image) to auto-extract learning objectives
### 🔐 Security & Access
- Profile picture upload (Base64 saved directly to MongoDB and persistently synced with front-end auth safeStorage) with hover/click edit overlay
- Security questions hashed with bcrypt at registration (case-insensitive comparison)
- In-app password reset via security question verification (Settings panel)
- JWT 30-day tokens, Bearer auth header on all protected routes
- Academic year archiving with security question double-verification (Principal only)
### 🎨 UI / UX
- **Decorated File Upload Button**: Native inputs replaced by a beautiful custom dashed upload zone with dynamic status badges.
- **Microphone Hardware Auto-Release**: Instant release of mic hardware tracks on toggle-off to prevent browser red-dot lock.
- Pure custom CSS design system (no Tailwind) with a robust dual-theme architecture
- **Obsidian / Midnight Dark Mode**: Deeper, richer midnight-black gradients that feel premium and immersive
- **Soothing Light Mode**: Glare-free slate-cream bases (`#F4F6F9`) and soft white surfaces (`#FFFFFF`) designed to prevent eye strain during long hours
- **Theme Context & Toggle**: Clean, state-driven global theme toggle (Sun/Moon icons) with instant `localStorage` choice persistence
- Stable prompt input box layout (eliminating layout shift/movement when toggling views or states)
- Collapsible overlay sidebar starting just below the 64 px header
- Mobile sidebar with blurred backdrop overlay
- URL hash routing (`#dashboard`, `#assess`, etc.) for native browser/mobile back button
- Professional disclaimer footer, `@keyframes spin` loading states throughout
---
## 💻 Tech Stack
| Layer | Technology |
|---|---|
| **Frontend** | React 18, Vite, Phosphor Icons, pure custom CSS (design tokens) |
| **Backend** | Node.js 18+, Express 5, Multer, CSV-Parser |
| **Database** | MongoDB Atlas (Mongoose ODM) |
| **AI Engine** | Google Gemini 1.5 Flash (3-key rotation pool) |
| **Voice** | AssemblyAI Transcription API |
| **Auth** | JWT (jsonwebtoken), bcryptjs |
| **Monorepo** | npm workspaces |
| **Deployment** | Render (4 separate Web Services from one repo) |
---
## 🔑 Environment Variables
> [!WARNING]
> Never commit `.env` files to GitHub — they are already in `.gitignore`.
### Orchestrator Agent (`apps/orchestrator-agent/backend/.env`)
```env
PORT=5000
NODE_ENV=development
MONGO_URI=your_mongodb_atlas_connection_string
JWT_SECRET=your_jwt_signing_secret
MCP_SHARED_SECRET=your_shared_mcp_token # same value across all 4 services
GEMINI_API_KEY=your_single_gemini_api_key # optional (checks this first)
GEMINI_API_KEY_1=your_primary_gemini_api_key
GEMINI_API_KEY_2=your_secondary_gemini_api_key
GEMINI_API_KEY_3=your_tertiary_gemini_api_key
ASSEMBLYAI_API_KEY=your_assemblyai_api_key
MCP_PEDAGOGY_URL=http://localhost:5001/mcp # override with Render URLs in prod
MCP_LESSONCRAFT_URL=http://localhost:5002/mcp
MCP_FEEANALYTICS_URL=http://localhost:5003/mcp
```
### Pedagogy MCP (`apps/pedagogy-mcp/.env`)
```env
PORT=5001
MONGO_URI=your_mongodb_atlas_connection_string
MCP_SHARED_SECRET=your_shared_mcp_token
```
### Fee Analytics MCP (`apps/fee-analytics-mcp/.env`)
```env
PORT=5003
MONGO_URI=your_mongodb_atlas_connection_string
MCP_SHARED_SECRET=your_shared_mcp_token
```
### LessonCraft MCP (`apps/lessoncraft-mcp/.env`)
```env
PORT=5002
MCP_SHARED_SECRET=your_shared_mcp_token
GEMINI_API_KEY_1=your_primary_gemini_api_key
GEMINI_API_KEY_2=your_secondary_gemini_api_key
GEMINI_API_KEY_3=your_tertiary_gemini_api_key
```
---
## 🚀 Local Installation Guide
### Prerequisites
- **Node.js** v18 or higher
- **npm** v9 or higher
- A **MongoDB Atlas** cluster (free tier works fine)
- At least one **Google Gemini API key** (free tier available at [aistudio.google.com](https://aistudio.google.com))
### Setup Steps
1. **Clone the repository:**
```bash
git clone https://github.com/nomaantalib/SchoolMind-AI.git
cd SchoolMind-AI
```
2. **Install all workspace dependencies:**
```bash
npm install
```
3. **Configure environment files:**
Copy `.env.example` to each service's directory and fill in your credentials (see [Environment Variables](#-environment-variables) above).
4. **Run all services concurrently (development mode):**
```bash
npm run dev
```
This starts:
- Frontend: `http://localhost:5173`
- Orchestrator API: `http://localhost:5000`
- Pedagogy MCP: `http://localhost:5001`
- LessonCraft MCP: `http://localhost:5002`
- Fee Analytics MCP: `http://localhost:5003`
5. **Build for production:**
```bash
npm run build
```
---
## 🌐 Production Deployment (Render)
See the full step-by-step guide: [render_deployment.md](render_deployment.md)
**Quick summary — deploy 4 Web Services from the same GitHub repo:**
| Service | Start Command | Key Env Vars |
|---|---|---|
| Pedagogy MCP | `npm start -w apps/pedagogy-mcp` | `MONGO_URI`, `MCP_SHARED_SECRET` |
| LessonCraft MCP | `npm start -w apps/lessoncraft-mcp` | `GEMINI_API_KEY_*`, `MCP_SHARED_SECRET` |
| Fee Analytics MCP | `npm start -w apps/fee-analytics-mcp` | `MONGO_URI`, `MCP_SHARED_SECRET` |
| Orchestrator (Main) | `npm start` | All of the above + `JWT_SECRET` + `MCP_*_URL` pointers |
> [!IMPORTANT]
> Leave **Root Directory blank** on all Render services so that npm workspace symlinks resolve correctly.
> [!TIP]
> The Orchestrator retries MCP calls up to **5 times with exponential backoff** (2 s → 32 s) to handle Render free-tier cold-start delays automatically.
---
## 📄 License
MIT © 2025 SchoolMind AI — Authorized Personnel Only.
