🛡️ AEGIS Platform - Backend

Building the Unified Digital Citadel for IIT Mandi

The AEGIS Backend is the high-performance, asynchronous core of the AEGIS Platform. Built with FastAPI, SQLModel (Async), and PostgreSQL, it serves as the central nervous system for identity management, grievance redressal, academic tracking, and real-time campus communication.

---

🏗️ Architecture Overview

The system follows a decoupled monorepo-style split. This repository handles all logic, data persistence, and security, communicating with the frontend via REST and WebSockets.

Component	Technology	Reasoning
Framework	FastAPI	High performance, native Async support, auto-OpenAPI docs.
Database	NeonDB (PostgreSQL)	Serverless scaling, managed PostgreSQL.
ORM	SQLModel + AsyncPG	Type-safe, async database interactions.
Auth	JWT + HttpOnly Cookies	Stateless, secure, XSS-proof authentication.
Real-time	WebSockets + Redis	Live updates for grievances and announcements.
Storage	AWS S3	Secure file storage (presigned URLs) for photos/resumes.

---

🚀 Features Implemented

🏛️ Pillar I: Identity & Governance

• RBAC System: Distinct roles for Student, Faculty, Authority, and Admin.
• Secure Auth: HttpOnly cookie-based JWT flow (Access + Refresh tokens).
• Institute Enforcement: Email validation restricted to @iitmandi.ac.in.

📢 Pillar II: Voice (Grievances)

• Anonymous Reporting: Submit issues without exposing identity.
• Status Tracking: Real-time updates (Submitted → Under Review → Resolved).
• Visual Evidence: Photo upload support via S3.
• Authority Dashboard: Admin tools to assign priority and resolve issues.

---

🛠️ Installation & Setup

Prerequisites

• Python 3.10+
• PostgreSQL (Local or NeonDB)
• Redis (Optional, for WebSockets/Background tasks)

1. Clone the Repository

git clone https://github.com/your-username/aegis-backend.git
cd aegis-backend

2. Environment Variables

Create a .env file in the root directory:

# App Config
PROJECT_NAME="AEGIS Platform"
ENVIRONMENT="local" # local | staging | production
API_V1_STR="/api/v1"

# Security (Generate using: openssl rand -hex 32)
SECRET_KEY="your-super-secret-key"
ACCESS_TOKEN_EXPIRE_MINUTES=15
REFRESH_TOKEN_EXPIRE_DAYS=7
DOMAIN="localhost" # Set to .yourdomain.com in prod

# Database (PostgreSQL / NeonDB)
POSTGRES_SERVER="localhost"
POSTGRES_USER="postgres"
POSTGRES_PASSWORD="password"
POSTGRES_DB="aegis"
POSTGRES_PORT=5432

# CORS (Comma separated)
BACKEND_CORS_ORIGINS="http://localhost:3000,http://localhost:8000"

# Optional: AWS S3 & Redis
# AWS_ACCESS_KEY_ID=...
# REDIS_URL=redis://localhost:6379/0

3. Install Dependencies

Using uv (recommended) or pip:

# Using uv
uv sync

# Using pip
pip install -r requirements.txt

4. Database Migrations

We use Alembic for schema management.

# Apply migrations
uv run alembic upgrade head

# Create initial data (Admin User)
uv run python -m app.initial_data

Note: Default Admin credentials will be admin@iitmandi.ac.in / admin123 (or check app/core/config.py).

5. Run the Server

uv run fastapi run app/main.py

Visit http://localhost:8000/docs to see the interactive API documentation.

---

📂 Project Structure

app/
├── alembic/            # Database migrations
├── api/
│   ├── routes/         # API Endpoints (Auth, Users, Grievances)
│   ├── deps.py         # Dependencies (RBAC, Session, CurrentUser)
│   └── main.py         # Router aggregation
├── core/
│   ├── config.py       # Settings & Env vars
│   ├── db.py           # Async Database Engine
│   └── security.py     # JWT & Password Hashing
├── models.py           # SQLModel Database Schemas & Enums
├── crud.py             # Async CRUD operations
└── main.py             # App Entrypoint

---

🔒 Security Measures

1. Strict CORS: Restricted to frontend domain only.
2. No Local Storage: JWTs are stored in HttpOnly, Secure, SameSite cookies to prevent XSS.
3. SQL Injection: Prevented via SQLModel/SQLAlchemy parameterization.
4. Rate Limiting: (Planned) Redis-backed rate limiting on Auth endpoints.

---

🧪 API Documentation

The API follows RESTful conventions. Key endpoints include:

• Auth: POST /api/v1/auth/login, POST /api/v1/auth/logout
• Users: GET /api/v1/users/me, POST /api/v1/users/signup
• Grievances:
  • POST /api/v1/grievances/ (Submit)
  • GET /api/v1/grievances/ (List - Filtered by Role)
  • PATCH /api/v1/grievances/{id} (Authority Resolution)

---