# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

EduSol Backend is a Laravel 12 (PHP 8.2+) REST API for an educational institution management system. It covers student management, academics, finance/billing, admissions, attendance, grades, and communications. Authentication uses Laravel Sanctum (token-based).

## Common Commands

```bash
# Full project setup (install deps, generate .env & key, migrate, build frontend)
composer run setup

# Development server (runs artisan serve, queue:listen, pail, and vite dev concurrently)
composer run dev

# Run tests (clears config cache first, then runs PHPUnit)
composer run test

# Run a single test file
./vendor/bin/phpunit tests/Feature/SomeTest.php

# Run a single test method
./vendor/bin/phpunit --filter=test_method_name

# Code formatting (Laravel Pint)
./vendor/bin/pint

# Database migrations
php artisan migrate

# Frontend build
npm run build
```

## Architecture

### Domain-Organized Controllers

Controllers in `app/Http/Controllers/` are grouped by domain subdirectory:
- **Academic/** — Program, Course, Session, Semester, Lecturer
- **Admission/** — Applicant, Criteria, Form
- **Attendance/** — Attendance tracking
- **Communication/** — Message, Announcement
- **Finance/** — Fee, Payment, Invoice, Scholarship, Discount, RevenueHead/SubHead
- **Grade/** — Grade management
- **Institution/** — Faculty, Department, InstitutionProfile
- **Student/** — Student, Biodata, StudentCourse, StudentGrade, StudentFee
- **User/** — User management
- **Auth/** — Login

Controllers are thin — they interact directly with Eloquent models and return JSON responses.

### Models (26 in `app/Models/`)

Key relationships:
- **Student** belongsTo User, Program; belongsToMany Course (pivot); hasMany Grade
- **Course** belongsTo Program, Department; belongsToMany Student
- **Fee/Payment/Invoice** form the billing chain
- **Faculty → Department → Program** is the institutional hierarchy

Models use enum casting (`app/Enums/`) for type-safe fields like UserRole, FeeStatus, AttendanceStatus, CourseType, etc.

### Routing (`routes/api.php`)

- All authenticated routes are grouped under `auth:sanctum` middleware
- Role-based access uses `CheckRole` middleware (`app/Http/Middleware/CheckRole.php`)
- Public endpoints: login, admission application, admission status check
- API responses follow `{ data: ... }` format via API Resources (`app/Http/Resources/`)

### User Roles (UserRole enum)

Admin, Finance, Lecturer, Student, Parent

### Database

MySQL (`edusol` database). 20+ migrations with foreign key constraints and cascade deletes. Pivot tables handle many-to-many relationships (e.g., student-course enrollments).