[Submission] WYM - Smart Exam Preparation Planner

teams/WYM/.gitignore

@@ -0,0 +1,32 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment Variables
+.env
+.env.*
+
+# Python Backend
+venv/
+__pycache__/

teams/WYM/README.md

@@ -0,0 +1,80 @@
+# Aegis: Kinetic Archive
+
+## Team Name
+WYM
+
+## Team Members
+- Love Yadav (GitHub: @loveyadav1015)
+- Ayush Kumar (GitHub: @GOLDEN-DEVIL)
+- Piyansh Shukla (GitHub: @P1yansh)
+- Rajmohan Verma (GitHub: @rajv20)
+
+## Idea Chosen
+Smart Exam Preparation Planner with an interactive node-based learning roadmap.
+
+## Problem Statement
+Students often struggle with overloaded syllabi, missed study sessions, and last-minute cramming. Fixed timetables do not adapt well when a day is missed, which can quickly create stress, poor prioritization, and burnout. Aegis addresses this by organizing study work into a flexible, priority-based system that helps students stay on track even when plans change.
+
+## Tech Stack
+**Frontend**
+- React 19 & Vite
+- TypeScript
+- Tailwind CSS v4
+- React Router
+- Zustand (State Management)
+- Lucide React
+
+**Backend & Database**
+- Python 3
+- FastAPI & Uvicorn (Web Framework & Server)
+- MongoDB & Motor (Asynchronous NoSQL Database)
+- Pydantic (Data Validation)
+
+**AI & Integrations**
+- Groq API (`llama-3.1-8b-instant`)
+
+## Implementation Details
+
+Aegis is built as a full-stack application featuring a React-based frontend dashboard and a robust FastAPI backend. 
+
+**Frontend Architecture:**
+The UI is a multi-page dashboard with a shared layout shell, featuring views for the main dashboard, adaptive calendar, interactive syllabus map, and creation flows. State management is handled with Zustand, which connects to the backend API (`/api/*`) for data persistence. The UI focuses on visual planning—highlighting core metrics like burnout risk, efficiency, and daily focus.
+
+**Backend & System Architecture:**
+The backend uses a Modular Router & Service pattern served by FastAPI. It connects to a MongoDB database via the Motor async driver, automatically seeding collections (`sessions`, `nodes`, `connections`) on startup if empty. Request and response payloads are strictly validated using Pydantic models.
+
+Key backend services driving the app's logic include:
+- **Self-Healing Scheduler (`services/scheduler.py`):** Automatically recalculates the study schedule when a user misses a session. It finds open slots between 08:00–21:00 and reschedules missed tasks based on priority (high → medium → low).
+- **Burnout & Metrics Engine (`services/burnout.py`):** Computes real-time metrics for the dashboard. Burnout risk (0-100) is calculated dynamically based on missed ratios, schedule density, late penalties, and consecutive misses. It also calculates overall efficiency and peak output hours.
+- **Node Map Graph Management (`routers/nodes.py`):** Manages the syllabus nodes and connections. Creating nodes with a `parentId` automatically generates edge relationships, simulating a directed graph for prerequisites.
+- **AI Integration (`services/ai_generator.py`):** Utilizes the Groq API to generate mission briefs and task descriptions based on study topics and priorities (with built-in fallback templates if API keys are missing).
+
+## How to Run Locally
+1. Open the project folder:
+   ```bash
+   cd DevStakes/teams/WYM
+   ```
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+3. Start the development server:
+   ```bash
+   npm run dev
+   ```
+4. Build for production:
+   ```bash
+   npm run build
+   ```
+
+### Prerequisites
+- Node.js installed
+- Python 3.9+ installed
+- MongoDB running locally (or a MongoDB Atlas connection string)
+- Groq API Key (Optional, for AI features)
+
+## Live Demo
+(https://silly-paprenjak-720283.netlify.app/)
+
+## Screenshots / Demo
+(https://drive.google.com/file/d/1T2iowKmj4HrRalTDpcN7jDS4QC6DK5nu/view?usp=sharing)

teams/WYM/backend/database.py

@@ -0,0 +1,38 @@
+"""
+Database — MongoDB connection via Motor (async driver)
+"""
+
+import os
+from motor.motor_asyncio import AsyncIOMotorClient
+from dotenv import load_dotenv
+
+load_dotenv()
+
+MONGODB_URL = os.getenv("MONGODB_URL", "mongodb://localhost:27017")
+MONGODB_DB_NAME = os.getenv("MONGODB_DB_NAME", "aegis_kinetic_archive")
+
+client: AsyncIOMotorClient = None
+db = None
+
+
+async def connect_to_mongo():
+    """Initialize the MongoDB connection."""
+    global client, db
+    client = AsyncIOMotorClient(MONGODB_URL)
+    db = client[MONGODB_DB_NAME]
+    # Verify the connection
+    await client.admin.command("ping")
+    print(f"Connected to MongoDB: {MONGODB_DB_NAME}")
+
+
+async def close_mongo_connection():
+    """Close the MongoDB connection."""
+    global client
+    if client:
+        client.close()
+        print("🔌 MongoDB connection closed.")
+
+
+def get_database():
+    """Return the database instance."""
+    return db

teams/WYM/backend/main.py

@@ -0,0 +1,75 @@
+"""
+Aegis: Kinetic Archive — FastAPI Backend
+Main entry point with CORS, router mounts, and database lifecycle.
+"""
+
+import os
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from dotenv import load_dotenv
+
+from database import connect_to_mongo, close_mongo_connection
+from seed import seed_database
+from routers import sessions, nodes, ai
+
+load_dotenv()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifecycle: connect to MongoDB on startup, close on shutdown."""
+    await connect_to_mongo()
+    await seed_database()
+    yield
+    await close_mongo_connection()
+
+
+app = FastAPI(
+    title="Aegis: Kinetic Archive API",
+    description="Backend API for the AI-powered adaptive Learning Operating System.",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+# CORS — allow frontend dev server and deployed origins
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:5173",       # Vite dev server
+        "http://localhost:4173",       # Vite preview
+        "http://127.0.0.1:5173",
+        "*",                           # Allow all in dev (tighten for production)
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Mount routers
+app.include_router(sessions.router)
+app.include_router(nodes.router)
+app.include_router(ai.router)
+
+
+@app.get("/")
+async def root():
+    return {
+        "name": "Aegis: Kinetic Archive API",
+        "version": "1.0.0",
+        "status": "operational",
+        "message": "The Kinetic Archive is online. All systems nominal.",
+    }
+
+
+@app.get("/api/health")
+async def health_check():
+    return {"status": "healthy"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    host = os.getenv("HOST", "0.0.0.0")
+    port = int(os.getenv("PORT", "8000"))
+    uvicorn.run("main:app", host=host, port=port, reload=True)

teams/WYM/backend/requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.115.12
+uvicorn[standard]==0.34.3
+motor==3.7.1
+pymongo==4.12.1
+pydantic==2.11.3
+pydantic-settings==2.9.1
+httpx==0.28.1
+python-dotenv==1.1.0
+groq==0.25.0

teams/WYM/backend/routers/__init__.py

@@ -0,0 +1 @@
+# Routers package

teams/WYM/backend/routers/ai.py

@@ -0,0 +1,24 @@
+"""
+AI Router — Groq-powered description generation
+"""
+
+from fastapi import APIRouter
+from schemas import AIGenerateRequest, AIGenerateResponse
+from services.ai_generator import generate_description
+
+router = APIRouter(prefix="/api/ai", tags=["AI"])
+
+
+@router.post("/generate-description", response_model=AIGenerateResponse)
+async def generate_project_description(request: AIGenerateRequest):
+    """
+    Generate a project description using Groq's LLM.
+    Falls back to a template if the API key is not configured.
+    """
+    text = await generate_description(
+        task_name=request.taskName,
+        priority=request.priority or "medium",
+        context=request.context or "",
+    )
+
+    return AIGenerateResponse(generatedText=text)