🎓 AcademiaOS - Intelligent College Management System

AcademiaOS is a production-grade backend system designed to modernize educational administration. Unlike standard student projects, this system is built to handle real-world scale with decoupled background processing, caching strategies, and strict security protocols.

Live API Docs: https://academia-api-53fz.onrender.com/docs

---

⚡ Key Technical Features

🔐 Security & Auth

• HttpOnly Cookie Authentication: Mitigates XSS attacks by storing tokens securely.
• RBAC (Role-Based Access Control): Middleware-enforced permissions for Student, Teacher, Staff, and Admin.
• OAuth2 / SSO: Support for Google and GitHub Login.

🚀 Performance Architecture

• Redis Caching (Cache-Aside): High-traffic endpoints (Routines, Public Notices) are cached with TTLs to reduce DB load.
• Asynchronous Workers: Celery handles heavy tasks (Email delivery, Report generation) off the main thread.
• Database Optimization: SQLModel (SQLAlchemy) with eager loading to prevent N+1 query issues.

🤖 AI Integration

• Gemini AI Assistant: An integrated chatbot endpoint that answers student queries about syllabus and exam rules using Google's Generative AI.

---

🛠️ Tech Stack

• Framework: FastAPI (Python)
• Database: PostgreSQL (Neon.tech)
• Job Queue: Celery + Redis (Upstash)
• Caching: Redis (Upstash)
• Deployment: Docker (Render Free Tier)
• Email: Resend API

---

🏃‍♂️ How to Run Locally

Prerequisites

• Docker & Docker Compose

1. Clone & Configure

git clone https://github.com/yourusername/academia-api.git
cd academia-api
cp .env.example .env

2. Start Services

docker-compose up --build

• API: http://localhost:8000
• Docs: http://localhost:8000/docs

---

☁️ Deployment (Free Tier Stack)

This project is optimized to run on a $0 Cost Stack using Neon, Upstash, and Render.

1. Database: Create a Postgres DB on Neon.tech. Get the connection string.
2. Redis: Create a Redis database on Upstash. Get the rediss:// URL.
3. Deploy:
   • Push this repo to GitHub.
   • Create a New Web Service on Render.
   • Connect your repo.
   • Runtime: Docker.
   • Environment Variables:
     • DATABASE_URL: (Your Neon URL)
     • CELERY_BROKER_URL: (Your Upstash URL)
     • CELERY_RESULT_BACKEND: (Your Upstash URL)
     • CACHE_REDIS_URL: (Your Upstash URL)
     • SECRET_KEY: (Any random string)
   • Deploy.

The Dockerfile includes a script that runs both the API and the Celery Worker in the same container, allowing full background processing on a single free instance.

---

Made with ❤️ by Bibek Dhakal | GitHub