Univ

Role-aware university workspace with grounded AI, live notices, timetable intelligence, moderation controls, and admin operations.

Live scope-aware chat · role-bounded dashboards · document ingestion · appeals and audit workflows

Why UnivGPT

UnivGPT is built to feel like a real university operating layer, not just a generic chatbot. It combines:

• grounded answers from live profile, notice, course, and faculty data
• role-aware experiences for students, faculty, and admins
• document upload, parsing, embeddings, and retrieval
• moderation, appeals, dean review, audit, and notification loops
• responsive dashboards designed for daily campus workflows

What It Can Do

Student

• ask about notices, deadlines, faculty, timetable, courses, and profile-bound details
• view role-scoped notifications and timetable
• appeal chat blocks if moderation rules are violated

Faculty

• view timetable, notices, uploads, and faculty workflows
• access faculty-scoped chat grounded to department/course context

Admin / Dean

• manage users, uploads, notices, and audit logs
• review moderation appeals
• approve, reject, or reset student chat flags

Tech Stack

Backend

• FastAPI
• Supabase Auth + Postgres
• Pinecone
• SentenceTransformers with all-MiniLM-L6-v2
• OpenRouter for intent/fallback generation
• Ollama-compatible generation endpoint
• SMTP email delivery for OTP, moderation, and appeal status updates

Frontend

• React 19 + TypeScript
• Vite 7
• Tailwind CSS
• Framer Motion
• Zustand

Repository Layout

GPT/
  backend/
    app/
      routers/       # auth, agent, admin, documents
      services/      # moderation, routing, ingestion, integrations
      middleware/    # auth and RBAC
      models/        # pydantic schemas
    migrate.py
    reset_db.py
    requirements.txt
  frontend/
    src/
      pages/
      components/
      store/
      lib/

Local Setup

1. Prerequisites

• Python 3.12.x
• Node.js 20+
• npm

2. Clone the project

git clone <your-repo-url>
cd GPT

3. Backend setup

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

Fill backend/.env with your real values before starting the API.

Then run:

python migrate.py
uvicorn app.main:app --reload --port 8000

Backend docs:

• http://localhost:8000/docs

4. Frontend setup

Open a new terminal:

cd frontend
npm install
copy .env.example .env.local
npm run dev

Frontend runs at:

• http://localhost:5173

Required Environment Variables

Backend .env

These are the main variables you need:

ENVIRONMENT=development
FRONTEND_APP_URL=http://localhost:5173
CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
OAUTH_REDIRECT_PATH=/auth/callback

SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=
SUPABASE_JWT_SECRET=
SUPABASE_STORAGE_BUCKET=documents

PINECONE_API_KEY=
PINECONE_INDEX_NAME=univgpt-index

OPENROUTER_API_KEY=
OPENROUTER_INTENT_MODEL=
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_GENERATION_FALLBACK_MODELS=

OLLAMA_API_KEY=
OLLAMA_GENERATION_MODEL=
OLLAMA_BASE_URL=

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM_EMAIL=
SMTP_FROM_NAME=UnivGPT Support

DEAN_EMAILS=
PRELOAD_EMBEDDINGS_ON_STARTUP=false
MOCK_LLM=false
ENABLE_DUMMY_AUTH=false
SUPABASE_OFFLINE_MODE=false

Frontend .env.local

VITE_API_URL=http://localhost:8000
VITE_SUPABASE_URL=
VITE_SUPABASE_ANON_KEY=
VITE_ACADEMIC_EMAIL_DOMAIN=

Supabase Setup

If you are running this project yourself, configure these in Supabase:

Authentication

• enable Email/Password
• enable Google if you want Google sign-in
• set Site URL to your frontend URL
• add Redirect URLs:
  • http://localhost:5173/auth/callback
  • your production frontend callback URL

Database

Make sure your Supabase project contains the expected application tables such as:

• profiles
• documents
• conversations
• audit_logs

Then run:

cd backend
python migrate.py

to align runtime-required columns and indexes.

Production Setup

Recommended hosting

• Frontend: Vercel
• Backend: Railway

Production checklist

1. Deploy the backend and get the public Railway URL
2. Deploy the frontend and set the real VITE_API_URL
3. Update backend CORS_ORIGINS and FRONTEND_APP_URL
4. Update Supabase Site URL and Redirect URLs
5. Add real SMTP credentials so signup OTP and appeal emails work
6. Set DEAN_EMAILS so moderation alerts go to the right admin/dean recipients

Core Flows

Authentication

• email signup sends a verification OTP
• email login requires a verified account
• Google auth respects role selection and admin allowlist rules
• logout clears local chat cache so users start fresh next time

Grounded AI

• detects role and intent
• pulls structured live context from profile/course/faculty/admin data
• uses vector retrieval where appropriate
• adds role-safe navigation links into the final answer

Moderation

• student-only moderation
• warnings -> block -> apology appeal
• dean/admin can approve, reject, or reset flags
• email + in-app notifications are sent on decisions

Documents

• upload with metadata
• extract and chunk text
• generate embeddings
• store searchable context in Pinecone

Troubleshooting

Signup says verification email could not be sent

That is usually an SMTP issue, not a frontend issue.

Check:

• SMTP_HOST
• SMTP_PORT
• SMTP_USER
• SMTP_PASSWORD
• SMTP_FROM_EMAIL

Also make sure your SMTP mailbox/app password actually allows outbound mail.

Login fails from production frontend

Check:

• backend CORS_ORIGINS
• frontend VITE_API_URL
• Supabase Site URL / Redirect URLs

Chat feels slow

Check:

• production model provider latency
• Supabase query speed
• Pinecone query timeout
• PRELOAD_EMBEDDINGS_ON_STARTUP

Faculty/course answers look wrong

Check that your profiles, documents, and course/faculty mapping data are populated in Supabase.

Useful Commands

Backend

python migrate.py
python reset_db.py
uvicorn app.main:app --reload --port 8000

Frontend

npm run dev
npm run build
npm run preview

Notes

• do not commit real .env files
• rotate keys immediately if they were ever exposed
• keep DEAN_EMAILS and SMTP values correct in production

---

Built to make university operations, notices, and academic assistance feel grounded, role-aware, and actually usable in production.