UniComplaints

A full-stack university complaint management platform built with Next.js and NestJS in a pnpm monorepo.

Tech Stack

• Monorepo: pnpm workspaces
• Frontend: Next.js 15 (App Router), React 19, TypeScript, Tailwind CSS
• Backend: NestJS 11, TypeORM, SQLite
• Authentication: JWT with bcrypt password hashing
• Storage: MinIO for file attachments
• Deployment: Docker & Docker Compose

Quick Start with Docker

The easiest way to run the entire system is with Docker Compose:

# Build and start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop everything
docker compose down

This starts:

• Web at http://localhost:3000 - Next.js frontend
• API at http://localhost:3001 - NestJS backend
• MinIO Console at http://localhost:9001 - Object storage admin

The database is automatically seeded with sample users and complaints on first startup.

Default Login Credentials

Email	Password	Role
admin@unicomplaints.com	@Password1	Admin
director@unicomplaints.com	@Password1	Complaint Director
staff@unicomplaints.com	@Password1	Staff
student@unicomplaints.com	@Password1	Student

Custom Ports

If the default ports are in use, you can specify alternatives:

API_PORT=4001 WEB_PORT=4000 MINIO_API_PORT=9002 MINIO_CONSOLE_PORT=9003 docker compose up -d

Local Development

Prerequisites

• Node.js >= 20.0.0
• pnpm >= 10.0.0

Setup

Install dependencies:

pnpm install

Copy environment files:

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

Start MinIO for file storage (optional):

docker compose up minio -d

Seed the database:

pnpm --filter @uni-complaints/api seed

Start both apps in development mode:

pnpm dev

Or start them individually:

pnpm dev:api   # Backend at http://localhost:3001
pnpm dev:web   # Frontend at http://localhost:3000

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

Testing

Run tests for both frontend and backend:

# Backend tests
pnpm --filter @uni-complaints/api test

# Frontend tests
pnpm --filter @uni-complaints/web test

Project Structure

/
├── apps/
│   ├── api/                  # NestJS backend
│   │   ├── src/
│   │   │   ├── auth/         # Authentication (register, login, JWT)
│   │   │   ├── complaint/    # Complaint management
│   │   │   ├── storage/      # MinIO file storage
│   │   │   ├── user/         # User management
│   │   │   └── seed.ts       # Database seeding
│   │   ├── Dockerfile
│   │   └── entrypoint.sh
│   └── web/                  # Next.js frontend
│       ├── src/
│       │   ├── app/          # Pages (login, dashboard, complaints, admin)
│       │   ├── components/   # Reusable UI components
│       │   └── lib/          # API client, auth context, utilities
│       ├── middleware.ts     # Route protection
│       └── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.base.json

Complaint Workflow

Complaints follow a defined status flow:

open ──────┬──────► in_progress ◄─────► resolved ──────► closed (terminal)
           │
           └──────► rejected (terminal)

• open: Initial state when complaint is submitted
• in_progress: Being actively reviewed
• resolved: Issue has been addressed
• closed: Complaint officially closed (terminal - no further changes)
• rejected: Complaint was not valid (terminal - no further changes)

API Endpoints

Method	Path	Auth	Description
GET	/	Public	Health check
POST	/auth/register	Public	Register a new user
POST	/auth/login	Public	Login
GET	/auth/me	Required	Get current user
GET	/complaints	Required	List complaints
POST	/complaints	Required	Create complaint
GET	/complaints/:id	Required	Get complaint details
PATCH	/complaints/:id/status	Admin/Director	Update complaint status
GET	/users	Admin	List all users
PATCH	/users/:id/status	Admin	Update user account status
PATCH	/users/:id/role	Admin	Update user role

Environment Variables

Root .env

Variable	Default	Description
JWT_SECRET	change-me-in-production	JWT signing secret
JWT_EXPIRATION	1d	Token expiry
CORS_ORIGIN	http://localhost:3000	Allowed CORS origin
API_PORT	3001	Host port for API
WEB_PORT	3000	Host port for web
MINIO_API_PORT	9000	Host port for MinIO API
MINIO_CONSOLE_PORT	9001	Host port for MinIO console
MINIO_ACCESS_KEY	minioadmin	MinIO access key
MINIO_SECRET_KEY	minioadmin	MinIO secret key
MINIO_BUCKET	avatars	MinIO bucket name

Backend apps/api/.env

Variable	Default	Description
JWT_SECRET	dev-secret-change-in-production	JWT signing secret
JWT_EXPIRATION	1d	Token expiry
PORT	3001	API server port
DATABASE_PATH	data.db	SQLite database file path
CORS_ORIGIN	http://localhost:3000	Allowed CORS origin
MINIO_ENDPOINT	localhost	MinIO server hostname
MINIO_PORT	9000	MinIO server port
MINIO_ACCESS_KEY	minioadmin	MinIO access key
MINIO_SECRET_KEY	minioadmin	MinIO secret key
MINIO_BUCKET	avatars	MinIO bucket name
MINIO_USE_SSL	false	Use SSL for MinIO

Frontend apps/web/.env

Variable	Default	Description
NEXT_PUBLIC_API_BASE_URL	http://localhost:3001	Backend API URL