Student Grievances Platform

A production-hardened, high-performance platform for academic institutions to manage, track, and resolve student grievances. Engineered with a focus on security, atomic reliability, and modern user experience.

---

Key Features

Core Reliability & Security

• Atomic Operations: SQL-level atomic updates for upvotes to prevent race conditions.
• Robust Auth: JWT-based authentication with Refresh Tokens and secure password hashing.
• RBAC: Role-Based Access Control (Admin vs. Student) enforced at the API level.
• Data Integrity: Enforced unique constraints for upvote prevention and strict Pydantic input validation.

Grievance Management

• Dashboard: Unified interface for submission, tracking, and management.
• Admin Panel: Full visibility and status control (Pending → In Progress → Resolved).
• Topic System: Categorized grievances with pre-seeded institutional topics.
• Anonymity: Support for anonymous reporting to protect student privacy.

Advanced Infrastructure

• Vector Search Ready: Integrated pgvector for future AI-driven duplicate detection.
• Background Tasks: Celery workers for email notifications and heavy processing.
• Health Probes: Docker health checks ensuring zero-downtime dependency readiness.
• Optimized builds: Multi-stage Docker builds with optimized context transfers.

---

Tech Stack

• Backend: FastAPI, SQLAlchemy (Async), Alembic, Pydantic v2.
• Frontend: React, Vite, Tailwind CSS, Heroicons.
• Storage: PostgreSQL (with pgvector), Redis.
• Task Queue: Celery.
• Monitoring/Dev: MailHog (SMTP testing).

---

Getting Started

1. Prerequisites

• Docker Desktop (v20.10+)
• Git

2. Installation

# Clone the repository
git clone https://github.com/yourusername/student-grievances.git
cd student-grievances

# Initialize environment
cp .env.example .env

# Start the platform
docker compose up --build -d

3. Service Access

Service	URL	Description
Frontend UI	http://localhost:8001	Main user dashboard
API Docs	http://localhost:8001/docs	Interactive Swagger UI
MailHog	http://localhost:8025	Catch-all email testing
Database	localhost:5434	PostgreSQL instance

---

Initial Setup

Create an Admin User

To access the Admin Panel, register an account on the UI and then promote it via the CLI:

docker compose exec app python -c "from app.db import AsyncSessionLocal; from app.models import User; from sqlalchemy import select; import asyncio; async def promote(): session = AsyncSessionLocal(); user = (await session.execute(select(User).where(User.email == 'your@email.com'))).scalar_one_or_none(); if user: user.is_admin = True; await session.commit(); print('Success!'); else: print('User not found'); await session.close(); asyncio.run(promote())"

---

Architecture Overview

graph TD
    User((User/Admin)) -->|React UI| WebApp[App Container]
    WebApp -->|API Requests| FastAPI[FastAPI Backend]
    FastAPI -->|Async Queries| DB[(PostgreSQL + pgvector)]
    FastAPI -->|Enqueue| Redis{Redis Queue}
    Redis -->|Process| Worker[Celery Worker]
    Worker -->|Send Email| MailHog(MailHog)

Loading

---

Maintenance & Development

Database Migrations

Always use Alembic for schema changes:

# Create migration
docker compose exec app alembic revision --autogenerate -m "description"

# Apply migration
docker compose exec app alembic upgrade head

Troubleshooting Docker

If you encounter "container marked for removal" or build hangs:

1. Restart Docker Desktop.
2. Run docker system prune -f.
3. Run docker compose down -v followed by docker compose up --build -d.

---

License

Distributed under the MIT License.