# 🏫 School Management System

<p align="center">
  <img src="https://img.shields.io/badge/Laravel-12.0-red?style=for-the-badge&logo=laravel" alt="Laravel">
  <img src="https://img.shields.io/badge/PHP-8.2+-blue?style=for-the-badge&logo=php" alt="PHP">
  <img src="https://img.shields.io/badge/MySQL-Database-orange?style=for-the-badge&logo=mysql" alt="MySQL">
  <img src="https://img.shields.io/badge/TailwindCSS-3.1-38bdf8?style=for-the-badge&logo=tailwindcss" alt="TailwindCSS">
</p>

## 📋 About The Project

A comprehensive school management system built with Laravel 12 and TailwindCSS. This system provides integrated tools for managing students, teachers, classes, attendance, grades, fees, and the school library.

### ✨ Key Features

#### 👥 User Management
- **Multi-level Permission System** (Admin, Teacher, Student, Parent)
- **Secure Authentication** for users
- **User Profile Management**

#### 🎓 Student Management
- Student registration and data management
- Link students to parents
- Track attendance and absences
- Manage grades and assessments
- Student fee records and payments

#### 👨‍🏫 Teacher Management
- Teacher profiles
- Assign subjects to teachers
- Class schedules
- Homework management

#### 📚 Curriculum Management
- **Grades**: Manage academic levels and classes
- **Subjects**: Link subjects to grades and teachers
- **Schedules**: Organize daily class periods
- **Exams**: Manage examinations and test scheduling
- **Marks**: Record and track student grades

#### 💰 Financial Management
- **Fees**: Define tuition fees for each grade
- **Payments**: Track payments and advance payments
- **Financial Reports**

#### 📖 Library System
- **Books Management**: School book database
- **Borrowing System**: Book lending and return system
- **Track** available and borrowed books

#### 📝 Additional Features
- **Notes**: Note system for students and teachers
- **Assignments**: Homework management and tracking
- **Events**: School events and activities calendar
- **Settings**: Flexible settings system (key-value)
- **Attendance System**: Daily student attendance recording

---

## 🛠 Technologies Used

### Backend
- **Framework**: Laravel 12.0
- **PHP**: 8.2+
- **Database**: MySQL
- **Authentication**: Laravel Breeze
- **Permissions**: Spatie Laravel Permission
- **Excel Import/Export**: Maatwebsite Excel

### Frontend
- **CSS Framework**: TailwindCSS 3.1
- **JavaScript Framework**: Alpine.js
- **Build Tool**: Vite
- **Icons & UI**: Tailwind Forms

### Development Tools
- **Testing**: PHPUnit 11.5
- **Code Style**: Laravel Pint
- **Local Development**: Laravel Sail (Docker)
- **Logging**: Laravel Pail

---

## 📊 Database Schema

### Main Tables

#### 👤 Users & Authentication
- `users` - Users (Admin, Teachers, Students, Parents)
- `cache` - Cache storage
- `jobs` - Job queue
- `password_reset_tokens` - Password reset tokens

#### 🔐 Permissions (Spatie)
- `permissions` - Permissions
- `roles` - Roles
- `model_has_permissions` - Link permissions to models
- `model_has_roles` - Link roles to models
- `role_has_permissions` - Link permissions to roles

#### 🎓 Academic Management
- `grades` - Academic grades/classes
- `students` - Students
- `teachers` - Teachers
- `subjects` - Subject courses
- `schedules` - Class schedules
- `exams` - Examinations
- `marks` - Student grades
- `assignments` - Homework assignments

#### 📋 Student Services
- `attendances` - Attendance records
- `fees` - Tuition fees
- `payments` - Payment records
- `parent_models` - Parents/Guardians
- `notes` - Notes and comments

#### 📚 Library Management
- `books` - Books catalog
- `borrowings` - Borrowing records

#### ⚙️ System
- `settings` - General settings
- `events` - Events and activities

---

## 📁 Project Structure

```
school_system/
├── app/
│   ├── Http/
│   │   ├── Controllers/      # Controllers
│   │   ├── Middleware/        # Middleware
│   │   └── Requests/          # Form Requests
│   ├── Models/                # Eloquent Models
│   │   ├── User.php
│   │   ├── Student.php
│   │   ├── Teacher.php
│   │   ├── Grade.php
│   │   ├── Subject.php
│   │   ├── Attendance.php
│   │   ├── Mark.php
│   │   ├── Fee.php
│   │   ├── Payment.php
│   │   ├── Assignment.php
│   │   ├── Exam.php
│   │   ├── Book.php
│   │   ├── Borrowing.php
│   │   ├── ParentModel.php
│   │   ├── Note.php
│   │   ├── Schedule.php
│   │   ├── Event.php
│   │   └── Setting.php
│   └── Providers/             # Service Providers
├── database/
│   ├── migrations/            # Migration Files (27 files)
│   ├── seeders/               # Database Seeders
│   └── factories/             # Model Factories
├── resources/
│   ├── views/                 # Blade Templates
│   ├── css/                   # CSS Files
│   └── js/                    # JavaScript Files
├── routes/
│   ├── web.php                # Web Routes
│   ├── api.php                # API Routes
│   └── console.php            # Console Commands
├── public/                    # Public Files
├── storage/                   # Storage Files
├── tests/                     # Tests
├── .env                       # Environment Variables
├── composer.json              # PHP Dependencies
├── package.json               # JS Dependencies
└── vite.config.js             # Vite Configuration
```

---

## 🚀 Quick Start

### Prerequisites
- **PHP**: 8.2 or higher
- **Composer**: For PHP package management
- **Node.js & NPM**: For JavaScript package management
- **MySQL**: 5.7 or higher
- **Git**: For version control

### Quick Installation

```bash
# 1. Clone the repository
git clone <repository-url>
cd school_system

# 2. Install dependencies
composer install
npm install

# 3. Setup environment
cp .env.example .env
php artisan key:generate

# 4. Setup database (see DATABASE_SETUP.md)
# Update .env with your database credentials

# 5. Run migrations
php artisan migrate

# 6. (Optional) Seed database
php artisan db:seed

# 7. Build assets
npm run build

# 8. Start the application
php artisan serve
```

For detailed instructions, see [DATABASE_SETUP.md](DATABASE_SETUP.md)

---

## 🔒 Permission System

The project uses **Spatie Laravel Permission** for roles and permissions management:

### Default Roles
- **Admin**: Full system access
- **Teacher**: Manage classes, attendance, grades, and assignments
- **Student**: View personal information
- **Parent**: Monitor their children

### Available Permissions
- User management (Create, Read, Update, Delete)
- Student management
- Teacher management
- Grade and subject management
- Attendance and marks management
- Fee and payment management
- Library management
- Settings management

---

## ⚙️ Configuration

### Environment Variables (.env)

#### Application
```env
APP_NAME="School Management System"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000
```

#### Database
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=school_db
DB_USERNAME=root
DB_PASSWORD=
```

#### Sessions and Storage
```env
SESSION_DRIVER=file
CACHE_STORE=database
QUEUE_CONNECTION=database
FILESYSTEM_DISK=local
```

#### Email
```env
MAIL_MAILER=log
MAIL_FROM_ADDRESS="hello@example.com"
MAIL_FROM_NAME="${APP_NAME}"
```

---

## 🧪 Testing

```bash
# Run all tests
composer test
# Or
php artisan test

# Run specific test
php artisan test --filter=TestName
```

---

## 🛠 Custom Composer Scripts

```bash
# Complete project setup
composer setup

# Run development environment (Server + Queue + Logs + Vite)
composer dev

# Run tests
composer test
```

---

## 📝 NPM Scripts

```bash
# Build assets for production
npm run build

# Run development environment (Hot Reload)
npm run dev
```

---

## 📦 Queue Management

To process background jobs (like schedule auto-generation), you need to run a queue worker.

```bash
# Start the queue worker
php artisan queue:work
```

> [!IMPORTANT]
> If the `.env` is set to `QUEUE_CONNECTION=sync`, jobs will run synchronously during the request. For true background processing on a server, set this to `database` or `redis` and ensure a worker is running.

---

## 📂 Important Files

- **composer.json**: PHP package definitions
- **package.json**: JavaScript package definitions
- **.env**: Environment settings (not committed to Git)
- **.env.example**: Environment file template
- **DATABASE_SETUP.md**: Database setup and installation guide
- **phpunit.xml**: Testing configuration
- **vite.config.js**: Vite configuration
- **tailwind.config.js**: TailwindCSS configuration

---

## 🤝 Contributing to the Project

### How to Contribute
1. **Fork** the project
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a **Pull Request**

### Code Standards
- Follow PSR-12 standards for PHP
- Use `php artisan pint` to format code
- Write tests for any new features
- Document code clearly

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

---

## 🐛 Reporting Issues

If you encounter any issues:
1. Check existing [Issues](../../issues)
2. Open a new Issue with a clear description
3. Provide environment details (PHP version, Laravel version, etc.)
4. Attach screenshots if possible

---

## 📚 Useful Resources

### Official Documentation
- [Laravel Documentation](https://laravel.com/docs)
- [TailwindCSS Documentation](https://tailwindcss.com/docs)
- [Alpine.js Documentation](https://alpinejs.dev)
- [Spatie Permission Documentation](https://spatie.be/docs/laravel-permission)

### Tutorials and References
- [Laravel Breeze](https://laravel.com/docs/starter-kits#breeze)
- [Vite Documentation](https://vitejs.dev)
- [MySQL Documentation](https://dev.mysql.com/doc/)

---

## 📧 Support and Contact

For support and inquiries:
- Open an Issue in the project
- Contact the development team

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- **Laravel Team** - For the amazing framework
- **Spatie** - For the permissions package
- **TailwindCSS Team** - For the excellent CSS framework
- **All Contributors** to this project

---

<p align="center">
  Made with ❤️ for better school management
</p>