MAIS - Modern Academic Information System

A comprehensive Academic Information System built with Next.js 15, designed to manage student records, course registrations, grades, schedules, thesis management, accommodation, and more. Features full bilingual support (English/Slovak) and role-based access control.

---

📋 Table of Contents

• Features
• Tech Stack
• Project Structure
• Prerequisites
• Installation
• Configuration
• Running the Application
• User Roles & Permissions
• Complete Route Reference
• Testing Guide
• Internationalization
• Troubleshooting

---

✨ Features

For Students 🎓

Feature	Description
📚 Course Enrollment	Browse open course offerings and enroll with capacity tracking
📅 Schedule Management	Interactive week/list view timetable with section registration
📊 Grade Tracking	View grades, GPA calculation, and earned credits
📄 Course Details	Access course materials, assessment components, and grades
🎯 Exam Registration	Register for exam terms (final, practical, presentation)
📝 Thesis Management	Browse topics, request assignment, track milestones, submit work
🏠 Accommodation	Apply for dormitory, track application status, view payments
📜 Certificates	Request study confirmations and accommodation contracts (PDF)
✉️ Messages	Receive and send messages with file attachments
👤 Profile	Manage personal information and avatar

For Teachers 👨‍🏫

Feature	Description
📖 Course Offerings	Create and manage course offerings for semesters
📋 Sections & Meetings	Define class sections with time slots, rooms, and meeting types (Lecture, Lab, Exercise, Seminar, etc.)
📝 Thesis Topics	Create, publish, and manage thesis topics
✅ Assignment Requests	Review and approve/reject student thesis requests
👥 Thesis Supervision	Monitor student progress, create milestones, review submissions
📊 Student Management	View enrolled students and their progress

For Administrators 🔐

Feature	Description
👥 User Management	Manage users and assign roles (admin, teacher, student)
🏠 Accommodation Admin	Review applications, manage payments, process requests
📜 Certificate Admin	Fulfill official certificate requests
📊 System Statistics	Dashboard with system-wide analytics

System Features 🌐

Feature	Description
🌍 Bilingual Support	Full English and Slovak language support
🎨 Theme Toggle	Light/Dark mode support
📱 Responsive Design	Mobile-friendly interface
🔒 Role-Based Access	Secure access control per user role
📎 File Attachments	Upload and download files with signed URLs
📄 PDF Generation	Generate certificates with Puppeteer

---

🛠️ Tech Stack

Frontend

Technology	Purpose
Next.js 15.5.6	React framework with App Router & Turbopack
React 19.1.0	UI library
TypeScript	Type-safe development
Tailwind CSS 4	Utility-first styling
Shadcn/ui	Accessible component library (built on Radix UI)
Lucide React	Icon library
React Hook Form	Form handling
Zod	Schema validation
Zustand	State management
Sonner	Toast notifications
date-fns	Date utilities

Backend

Technology	Purpose
Supabase	Backend-as-a-Service (PostgreSQL, Auth, Storage)
PostgreSQL	Relational database
Row Level Security	Database-level access control
Server Actions	Next.js server-side mutations
Puppeteer	PDF generation

---

📁 Project Structure

mais-clone/
├── app/                          # Next.js App Router
│   ├── globals.css               # Global styles
│   ├── layout.tsx                # Root layout
│   ├── [lang]/                   # Locale-prefixed routes
│   │   ├── layout.tsx            # Dashboard layout with sidebar
│   │   ├── (auth)/               # Authentication pages
│   │   │   └── login/            # Login page
│   │   ├── (dashboard)/          # Protected dashboard routes
│   │   │   ├── page.tsx          # Home dashboard
│   │   │   ├── accommodation/    # Student accommodation
│   │   │   ├── admin/            # Admin panel
│   │   │   │   ├── accommodation/# Accommodation admin
│   │   │   │   ├── certificates/ # Certificate admin
│   │   │   │   └── users/        # User management
│   │   │   ├── appointments/     # Exam appointments
│   │   │   ├── certificates/     # Certificate requests
│   │   │   ├── enrollment/       # Course enrollment
│   │   │   ├── messages/         # Messaging system
│   │   │   ├── profile/          # User profile
│   │   │   ├── schedule/         # Class schedule
│   │   │   ├── studies/          # My courses & grades
│   │   │   ├── teaching/         # Teacher portal
│   │   │   │   ├── offering/     # Course offerings
│   │   │   │   └── thesis/       # Thesis management
│   │   │   ├── terms/            # Exam terms
│   │   │   └── thesis/           # Student thesis
│   └── api/                      # API routes
│       └── thesis/               # Thesis API endpoints
├── components/                   # React components
│   ├── ui/                       # Shadcn/ui components
│   ├── layout/                   # Layout components
│   ├── data/                     # Data display components
│   └── form/                     # Form components
├── hooks/                        # Custom React hooks
├── lib/                          # Utility libraries
│   ├── auth/                     # Authentication utilities
│   ├── i18n/                     # Internationalization
│   │   └── dictionaries/         # Translation files (en.json, sk.json)
│   ├── pdf/                      # PDF generation
│   ├── supabase/                 # Supabase clients
│   └── validators/               # Zod schemas
├── types/                        # TypeScript type definitions
│   └── db.ts                     # Database types
├── public/                       # Static assets
├── middleware.ts                 # i18n routing middleware
├── components.json               # Shadcn/ui configuration
├── next.config.ts                # Next.js configuration
└── tsconfig.json                 # TypeScript configuration

---

📦 Prerequisites

Before you begin, ensure you have the following installed:

Requirement	Version	Download
Node.js	v18.0.0+	nodejs.org
pnpm	v8.0.0+	npm install -g pnpm
Git	Latest	git-scm.com

System Requirements

Resource	Minimum	Recommended
RAM	4GB	8GB
Disk	500MB	1GB
OS	Windows 10+, macOS 10.15+, Linux	Any

---

🚀 Installation

1. Clone the Repository

git clone <repository-url>
cd mais-clone

2. Install Dependencies

pnpm install

3. Configure Environment Variables

Create a .env.local file in the project root:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

---

⚙️ Configuration

Environment Variables

The .env.local file should contain:

Variable	Description	Required
NEXT_PUBLIC_SUPABASE_URL	Supabase project URL	✅
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anonymous key	✅

Note: Environment variables will be provided separately. The database uses Row Level Security (RLS) policies for all tables to ensure proper access control.

---

🏃 Running the Application

Development Mode

pnpm dev

The application will be available at: http://localhost:3000

Uses Turbopack for fast refresh

---

👥 User Roles & Permissions

The system supports three main user roles with distinct permissions:

🎓 Student Role

Students have access to academic features focused on their studies:

Permission	Description
View Dashboard	Access main dashboard with quick stats
Enroll in Courses	Browse and enroll in open offerings
Manage Schedule	Register for class sections, view timetable
View Grades	See component grades and final grades
Access Materials	Download course materials
Exam Registration	Register/unregister for exam terms
Thesis Work	Browse topics, request assignment, submit milestones
Accommodation	Apply for housing, track status, view payments
Certificates	Request study confirmations
Messages	Send/receive messages with attachments
Profile	Update personal information and avatar

👨‍🏫 Teacher Role

Teachers manage courses and supervise student work:

Permission	Description
All Student Permissions	Teachers retain student-level access
Create Offerings	Create course offerings for semesters
Manage Sections	Create sections with meetings (day, time, room, type)
Edit Meetings	Modify meeting details with collision detection
Delete Sections/Meetings	Remove sections or individual meetings (with confirmation dialog)
Create Thesis Topics	Define thesis topics with capacity
Publish/Unpublish Topics	Control topic visibility
Review Requests	Approve/reject student thesis requests
Supervise Theses	View progress, create milestones, review submissions
Provide Feedback	Accept or request changes on submissions

🔐 Administrator Role

Administrators have full system access:

Permission	Description
All Permissions	Full access to all features
User Management	View all users, assign/remove roles
Accommodation Admin	Review applications, manage payments
Certificate Admin	Fulfill official certificate requests
System Statistics	View system-wide analytics

---

🗺️ Complete Route Reference

Public Routes

Route	Description
/	Redirects to /en or /sk based on preference
/en/login	English login page
/sk/login	Slovak login page

Student Routes

Route	Access	Description
/en or /sk	All	Dashboard home with stats overview
/en/enrollment	Student	Browse and enroll in courses
/en/studies	Student	View enrolled courses and grades
/en/studies/[offeringId]	Student	Course detail with materials and grades
/en/schedule	Student	Weekly/list view timetable with row-spanning meetings
/en/appointments	Student	Exam term registration
/en/terms	Student	Alternative exam terms view
/en/thesis	Student	Thesis dashboard (redirects to topics if no thesis)
/en/thesis/topics	Student	Browse available thesis topics
/en/thesis/[thesisId]	Student	Thesis detail with milestones, settings, file uploads
/en/accommodation	Student	Accommodation application with academic year selector
/en/certificates	Student	Request study/accommodation certificates
/en/messages	Student	Inbox with compose, attachments, image preview
/en/profile	All	Edit profile and avatar

Teacher Routes

Route	Access	Description
/en/teaching	Teacher	Teacher dashboard with course offerings list
/en/teaching/offering/new	Teacher	Create new course offering
/en/teaching/offering/[id]	Teacher	Manage sections and meetings for an offering
/en/teaching/thesis	Teacher	Thesis management dashboard with stats
/en/teaching/thesis/topics	Teacher	Create, edit, publish/unpublish thesis topics
/en/teaching/thesis/requests	Teacher	Review and approve/reject student requests
/en/teaching/thesis/supervise	Teacher	List of supervised theses with progress
/en/teaching/thesis/[thesisId]	Teacher	Supervise specific thesis, manage milestones, review submissions

Admin Routes

Route	Access	Description
/en/admin	Admin	Admin dashboard with system statistics
/en/admin/users	Admin	User role management table
/en/admin/accommodation/applications	Admin	Review accommodation applications with filters
/en/admin/accommodation/payments	Admin	Manage accommodation payments
/en/admin/certificates/requests	Admin	Fulfill certificate requests

---

🧪 Testing Guide

Demo Accounts

The following demo accounts are pre-configured and ready to use:

Role	Email	Password
🎓 Student	[email protected]	student123
👨‍🏫 Teacher	[email protected]	teacher123
🔐 Admin	[email protected]	admin123

Tip: These credentials are also displayed on the login page for quick access.

Testing Workflows

Student Workflow

1. Login → Go to /en/login, enter student credentials
2. Enrollment → Navigate to /en/enrollment, enroll in a course
3. Schedule → Go to /en/schedule, register for a section
4. Studies → Check /en/studies to see enrolled courses
5. Course Detail → Click a course to view materials and grades
6. Exam Registration → Go to /en/appointments, register for an exam
7. Thesis → Navigate to /en/thesis/topics, request a topic
8. Accommodation → Go to /en/accommodation, submit an application
9. Certificates → Request a certificate at /en/certificates
10. Messages → Send a test message at /en/messages

Teacher Workflow

1. Login → Use teacher credentials
2. Teaching Dashboard → Go to /en/teaching
3. Create Offering → Click "New Offering", fill in details
4. Manage Sections → Click an offering, add sections
5. Add Meetings → Add meetings with day, time, room, type (Lecture/Lab/Exercise/Seminar)
6. Edit Meeting → Click pencil icon to edit a meeting
7. Delete Meeting → Click trash icon with AlertDialog confirmation
8. Thesis Topics → Go to /en/teaching/thesis/topics, create a topic
9. Publish Topic → Toggle the publish status
10. Review Requests → Check /en/teaching/thesis/requests
11. Supervise → Go to /en/teaching/thesis/supervise, click a thesis
12. Add Milestone → Create milestones for the thesis
13. Review Submission → Accept or request changes

Admin Workflow

1. Login → Use admin credentials
2. Admin Dashboard → Go to /en/admin
3. User Management → Navigate to /en/admin/users
4. Assign Roles → Add/remove roles for users
5. Accommodation → Go to /en/admin/accommodation/applications
6. Review Application → Change status, add notes
7. Payments → Go to /en/admin/accommodation/payments
8. Add Payment → Create a payment record
9. Certificates → Go to /en/admin/certificates/requests
10. Fulfill Request → Mark as fulfilled with file

Feature Testing Checklist

Schedule Features

• Week view displays meetings correctly
• Meetings spanning multiple hours show with rowSpan
• Meeting names (Lecture, Lab, etc.) are displayed
• List view shows all meetings
• Available sections show unregistered options
• Can register for a section
• Can unregister from a section

Teaching Features

• Can create a new offering
• Can add sections to offering
• Can add meetings to sections with name/type
• Can edit meetings (room, time, name)
• Collision detection works (room/time conflicts show error)
• AlertDialog shows for delete confirmation
• Can delete meetings and sections

Thesis Features

• Can browse available topics
• Can request topic assignment
• Teacher can approve/reject requests
• Student can view assigned thesis
• Student can submit milestones with files
• Teacher can create milestones
• Teacher can review submissions (accept/request changes)

Messages Features

• Can compose new message
• Can add recipients
• Can attach files (images and documents)
• Image attachments preview correctly (hover to enlarge)
• Sender can see their own attachments
• Can download attachments
• Unread indicator works
• Can archive messages

---

🌍 Internationalization

The application supports English and Slovak languages.

Switching Languages

1. Click the language toggle in the header
2. Select "English" or "Slovenčina"
3. The URL updates to reflect the locale (/en/... or /sk/...)

---

🔧 Troubleshooting

Common Issues

"Unable to connect to Supabase"

# Check your environment variables
cat .env.local

# Ensure URL and key are correct
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=eyJhbG...

"Port 3000 already in use"

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

"Module not found"

# Clear node_modules and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

"Hydration mismatch"

This usually happens with client-side date formatting. Ensure dates are formatted consistently:

// Use suppressHydrationWarning for dynamic content
<time suppressHydrationWarning>
  {new Date(date).toLocaleDateString()}
</time>

"Access denied" or data not loading

This is likely due to Row Level Security (RLS) policies. Make sure you are:

• Logged in with valid credentials
• Using an account with the appropriate role for the feature
• The database has RLS policies configured for all tables

---

Made with ❤️ by Matej Bendik for TUKE students and faculty