🧠 Digital Twin AI

An AI-powered campus wellness companion that predicts burnout, stress spikes, and academic overload — personalised to your semester, branch, and daily patterns.

Built for the AWS Builder Center hackathon by Ctrl C Ctrl V Engineers.

---

✨ Features

Feature	Description
Neural Avatar	A living 3D digital twin that mirrors your academic DNA — stress patterns, sleep cycles, workload peaks
Burnout Prediction	Predicts your burnout risk 48 hours before it hits using daily check-in data
Daily Check-In	2-minute pulse check covering sleep, deadlines, and mood
Smart Coping	Hyper-personalised strategies built for your exact situation
Neural Chat	Context-aware AI chat that remembers your deadlines and patterns
Live Dashboard	Real-time stress heatmaps, workload graphs, and a 3D avatar that reflects your state
University Portal	Separate portal for universities to monitor student wellness trends
Emergency Support	Quick access to emergency mental health resources

---

🛠️ Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS v4
• Database: MongoDB via Mongoose
• Authentication: Firebase Auth (Google OAuth) + JWT (jose)
• AI: Google Gemini 1.5 Flash (@google/generative-ai)
• 3D / Animation: Three.js + Framer Motion
• Charts: Recharts
• Package Manager: pnpm

---

🚀 Getting Started

Prerequisites

• Node.js >= 18
• pnpm (npm install -g pnpm)
• A MongoDB Atlas cluster (or local MongoDB)
• Firebase project with Google Auth enabled
• Google Gemini API key

Installation

# Clone the repository
git clone https://github.com/<your-username>/DigitalTwinAI.git
cd DigitalTwinAI

# Install dependencies
pnpm install

Environment Variables

Create a .env.local file in the project root:

# MongoDB
MONGODB_URI=<your_mongodb_connection_string>

# JWT
JWT_SECRET=<your_jwt_secret>

# Google Gemini
GEMINI_API_KEY=<your_gemini_api_key>

# Firebase (public — safe to expose)
NEXT_PUBLIC_FIREBASE_API_KEY=<your_firebase_api_key>

Firebase project config (authDomain, projectId, etc.) is already set in lib/firebase.ts. Only the API key needs to be in .env.local.

Running Locally

pnpm dev

Open http://localhost:3000 in your browser.

---

📁 Project Structure

DigitalTwinAI/
├── app/                    # Next.js App Router pages & API routes
│   ├── api/                # REST API endpoints
│   │   ├── auth/           # Login, signup, logout
│   │   ├── chat/           # AI chat endpoint
│   │   ├── checkin/        # Daily check-in submission
│   │   ├── dashboard/      # Dashboard data
│   │   ├── emergency/      # Emergency resources
│   │   ├── profile/        # User profile CRUD
│   │   └── university/     # University portal APIs
│   ├── components/         # Shared UI components
│   │   ├── Avatar3D.tsx    # Three.js 3D avatar
│   │   ├── AvatarCustomiser.tsx
│   │   ├── Header.tsx
│   │   └── ParticleBackground.tsx
│   ├── dashboard/          # Student dashboard page
│   ├── chat/               # AI chat page
│   ├── checkin/            # Daily check-in page
│   ├── emergency/          # Emergency support page
│   ├── profile/            # User profile page
│   ├── university/         # University portal
│   └── ...                 # Other pages (login, signup, results, faq)
├── controllers/
│   └── authController.ts   # JWT sign/verify logic
├── lib/
│   ├── dbConnect.ts        # MongoDB connection helper
│   ├── firebase.ts         # Firebase app initialisation
│   ├── gemini.ts           # Gemini AI integration + score computation
│   └── colleges.ts         # College/university data
├── models/                 # Mongoose schemas
│   ├── userModel.ts
│   ├── moodLog.ts
│   ├── assignmentModel.ts
│   ├── alertModel.ts
│   ├── simulationModel.ts
│   ├── studentStateModel.ts
│   └── universityModel.ts
├── utils/
│   ├── auth.ts             # Auth helper utilities
│   └── token.ts            # Token utilities
└── middleware.ts           # Route protection middleware

---

🔐 Authentication Flow

• Students sign up/log in via email+password or Google OAuth (Firebase)
• On successful auth, a JWT is issued and stored as an HTTP-only cookie (token)
• middleware.ts protects all student routes and redirects unauthenticated users to /login
• University portal uses a separate uni_token cookie and is excluded from student middleware

---

🤖 AI & Scoring

The lib/gemini.ts module handles two things:

1. Score computation (computeScores) — derives stress, burnout, anxiety, sleep, and wellbeing scores (0–100) from raw check-in answers using a weighted formula
2. AI response generation (getAIResponse) — sends the computed scores, user profile, assignment load, and recent check-in history to Gemini 1.5 Flash to generate a short, personalised 2–3 sentence insight

---

📦 Available Scripts

pnpm dev        # Start development server
pnpm build      # Build for production
pnpm start      # Start production server
pnpm lint       # Run ESLint

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit your changes: git commit -m "feat: add your feature"
4. Push to the branch: git push origin feat/your-feature
5. Open a Pull Request

---

👥 Authors

• Sparsh Chaudhary — GitHub
• Arham Kachhara — GitHub

---

📄 License

This project is licensed under the MIT License.

---

_{Built with ❤️ at AWS Builder Center Hackathon, IIT Kanpur · Ctrl C Ctrl V Engineers}