# CLAUDE.md

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

## Project Overview

Admin panel for ITI student fee payment tracking. Built for a single client — no public-facing pages. All routes are protected behind authentication.

**Stack:** PHP 8.2+, Laravel 12, Laravel Breeze (authentication), Bootstrap 5 + Bootstrap Icons (UI), MySQL 8.4, Blade templates, Vite 7, Axios, DataTables (datatables.net-bs5), Select2 + select2-bootstrap-5-theme, SweetAlert2, barryvdh/laravel-dompdf.

---

## Commands

**First-time setup:**
```bash
composer run setup
```

**Development (runs server, queue, logs, and Vite simultaneously):**
```bash
composer run dev
```

**Run all tests:**
```bash
composer run test
```

**Run a single test:**
```bash
php artisan test --filter TestClassName
```

**Code style (Laravel Pint):**
```bash
./vendor/bin/pint
```

**Frontend build:**
```bash
npm run build
```

---

## Architecture

**Request flow:** `public/index.php` → `routes/web.php` → Controllers in `app/Http/Controllers/` → Models in `app/Models/` → Blade views in `resources/views/`.

**Authentication:** Laravel Breeze. All admin routes must sit behind the `auth` middleware. Breeze scaffolds routes in `routes/auth.php` and controllers in `app/Http/Controllers/Auth/`.

**Database:** MySQL 8.4, database `iti_students`, user `root` (no password) via Laragon. Sessions, cache, and job queues are all database-backed. Run `php artisan migrate` after pulling new migrations.

**Frontend:** Bootstrap 5 (via npm) for UI. Vite bundles `resources/css/app.css` and `resources/js/app.js`. jQuery, DataTable, Select2, and SweetAlert2 are all imported in `app.js` and exposed as globals (`window.$`, `window.DataTable`, `window.Swal`). Always run `npm run dev` alongside the PHP server (or use `composer run dev`).

**Layout system:** Authenticated pages extend `layouts.app` (sidebar + topbar + footer). Guest pages extend `layouts.guest` (centered card). Partials live in `resources/views/partials/` (topbar, sidebar, footer). Add new sidebar links to `partials/sidebar.blade.php`. Use `@stack('scripts')` for page-level JS.

**Queue:** Database-backed. Worker starts automatically via `composer run dev`.

**Testing:** PHPUnit — `tests/Feature/` for HTTP-level tests, `tests/Unit/` for isolated unit tests. Test environment uses in-memory SQLite (configured in `phpunit.xml`).

---

## Project Context Files

The `.claude/` directory holds living documentation about how this project's modules connect to each other. These files are the source of truth for cross-module relationships and are **not** tracked in terms of UI — only data flow, model relationships, service dependencies, and route ownership.

**Location:** `.claude/modules/`

**Rule: Every time a new module is created, the relevant context file(s) in `.claude/modules/` must be updated or created in the same session before the task is considered complete.** A "module" means any meaningful group of related models, controllers, routes, and services (e.g., Students, Payments, Courses). The context file must document:
- What the module owns (models, tables, routes)
- How it connects to other modules (foreign keys, service calls, shared middleware)
- Any non-obvious business rules baked into the code

---

## Working Rules

### Never take shortcuts

Do not patch symptoms. If something is broken, trace it to its actual root cause before making any change. Do not comment out failing code, add workarounds, or suppress errors to make things appear to work.

### Root cause first

When an error occurs: read the full stack trace, identify the exact file and line where it originates, understand *why* it happens, then fix it there. Do not fix it at the call site if the bug lives deeper.

### Ask when blocked

If the root cause cannot be determined from the code alone — for example, a runtime error that requires seeing logs, a database state, or environment output — **stop and ask explicitly**. State:
1. What information is needed
2. Where it likely lives (e.g., `storage/logs/laravel.log`, `php artisan tinker`, a specific DB query)
3. Exactly what the user needs to run or copy to provide it

Do not guess or assume when the answer requires runtime data.