# 📘 BookMyMandabam – Copilot Instructions

This repository contains a **Laravel 12** backend and a **React+Vite** frontend. The API and UI are split into two folders:

- `app/`, `routes/`, `database/`, `resources/views` etc. for the PHP backend.
- `bookmymandabam-frontend/` for the React single‑page application.

Use the guidelines below to help AI agents jump straight in and produce useful code.

---

## 🏗 Architecture Overview

1. **Backend (Laravel)**
   * REST API under `routes/api.php` with version prefix `v1`.
   * Sanctum powers token auth.  `app/Http/Middleware/RoleMiddleware.php` gates customer/owner/admin routes with `role:…` middleware.
   * Domain models live in `app/Models` (e.g. `Booking`, `Mandabam`, `User`).  Controllers in `app/Http/Controllers` and API controller equivalents in `app/Http/Controllers/Api`.
   * Custom helpers (e.g. `App\Helpers\ApiResponse`) format JSON.
   * Policies exist under `app/Policies` (see `BookingPolicy` for example).
   * Database migrations under `database/migrations` follow Laravel naming conventions; look for `2026_*` to see recent schema changes.
   * Seeders live in `database/seeders/DatabaseSeeder.php`.
   * Composer scripts (`composer.json`) include `setup`, `dev`, `test` balloons – `composer dev` boots server + queue listener + pail + vite concurrently.
   * Payments integrate with Razorpay; remember to set `RAZORPAY_KEY`/`RAZORPAY_SECRET` (not present in `.env.example`).

2. **Frontend (React + Vite)**
   * Entry point is `bookmymandabam-frontend/src/main.jsx` with `react-router-dom` routes.
   * API layer is a single axios instance at `src/api/axios.js` using `import.meta.env.VITE_API_URL` and an interceptor that reads `localStorage.token`.
   * Authentication context in `src/context/AuthContext.jsx` exposes `user`, `login`, and `logout`; components access it via `useContext(AuthContext)`.
   * Layouts in `src/layouts/` (e.g. `DashboardLayout.jsx`) branch UI based on `user.role` (customer/owner/admin).
   * Pages live in `src/pages/` and may further nest (e.g. `pages/owner/`).
   * Styling uses Tailwind classes; configuration is in root `tailwind.config.js` and `postcss.config.js`.
   * Environment: `.env` file in the frontend folder should define `VITE_API_URL` (e.g. `http://localhost:8000/api/v1`).

3. **Data & Flow**
   * Users register/login via `/api/v1/register` and `/login` (POST) – response includes `token` and `user`.
   * Frontend stores token and fetches `/user` on mount to populate context.
   * Customers can create bookings via `/bookings` and view `/customer/bookings`.
   * Owners manage halls (`/owner/halls`) and bookings (`/owner/bookings`), and mark payments/approve/reject.
   * Admin routes under `/admin/...` provide dashboards and approval workflows.
   * Paid vs pending booking statuses drive date-blocking logic (see `src/pages/HallDetail.jsx` for sample calendar algorithm).

---

## ⚙️ Developer Workflow

### Backend Setup & Commands

```bash
# clone and cd into project
composer setup           # runs install, env copy, key:generate, migrate, npm build
# or if you already have vendor/node modules
composer install
cp .env.example .env     # configure DB, RAZORPAY_*, MAIL etc.
php artisan key:generate
php artisan migrate      # run migrations
php artisan db:seed      # optional
```

Run development server with:

```bash
composer dev             # starts php artisan serve + queue listener + pail + vite
# or individually:
php artisan serve --port=8000
npm --prefix bookmymandabam-frontend run dev
```

Tests use Pest; execute with `composer test` or `php artisan test`.

### Frontend Setup & Commands

```bash
cd bookmymandabam-frontend
npm install
# set VITE_API_URL in .env
npm run dev              # start Vite development server
npm run build            # production bundle
```

Linting is configured via ESLint in the frontend; back end uses `php artisan pint` for style.

### Environment Notes

* Backend `.env` (copied from `.env.example`) holds database, mail, queue, and payment credentials.
* Frontend `.env` must expose `VITE_API_URL`.  After changing it, restart Vite.
* The composer `setup` script will run `npm run build` automatically – be cautious if you only want backend assets.

---

## 📐 Conventions & Patterns

* **Role-based routing** – both API and React navigation rely on `user.role` to control access.  See `RoleMiddleware.php` and `DashboardLayout.jsx`.
* **API responses** always wrap data in `{success, message, data}` via `ApiResponse`; errors return `{success:false,message}`.  Frontend components should inspect `response.data.success`.
* **Calendar logic** for booking availability is implemented manually in `HallDetail.jsx`; reusable helper functions go in components or context directories if needed.
* Blade views under `resources/views` are still present but mostly for server-rendered parts (e.g. owner/admin dashboard pages).  API is preferred for new features.
* Use Laravel policies (`BookingPolicy`) for authorization on server side.
* Migrations often add enum‑like string columns (status, payment_type); check recent migration files when modifying.
* The queue connection is set to `database` and used for Pail logs; logs are written to `storage/`.  `composer dev` launches `php artisan queue:listen`.
* Frontend uses localStorage for token; logging out must clear it and reset context.

---

## 🔗 Integration Points

* **Sanctum** – ensure CSRF is disabled for API requests or call `/sanctum/csrf-cookie` if using SPA.
* **Razorpay** – backend uses `razorpay/razorpay` library.  Check `app/Http/Controllers/PaymentController` (if exists) or look for `\\Razorpay` usages when implementing payment flows.
* **External APIs** – none elsewhere.
* **Storage** – hall images go to `public/hall_images`; backend controllers may save files via `Storage::disk('public')`.

---

## 🧩 Key Files & Folders

| Path | Purpose |
|------|---------|
| `routes/api.php` | Defines all REST endpoints with role middleware. |
| `app/Http/Controllers/Api` | API controllers for auth, halls, bookings, owner/admin dashboards. |
| `app/Models` | Eloquent models (Booking, Mandabam, HallImage, etc.). |
| `src/context/AuthContext.jsx` | React auth wrapper. |
| `src/api/axios.js` | Axios instance configuration. |
| `src/layouts/DashboardLayout.jsx` | Role‑aware sidebar and header. |
| `composer.json` scripts | Useful shortcuts for setup/dev/test. |
| `bookmymandabam-frontend/.env` | frontend environment; must set `VITE_API_URL`. |

---

## ✅ How to Help with PRs

* Stick to role-based conventions, update both frontend and backend when APIs change.
* Add tests (Pest) for any new backend logic; follow existing auth tests in `tests/Feature/Auth`.
* Update migrations rather than editing existing tables (use new migration files).
* When adding axios calls, always guard with `try/catch` and show `response.data.message` on error.
* For UI additions, reuse Tailwind utility classes and follow existing component style; use `src/components/` for shared pieces.

---

✍️ **Feedback?** If any part of these instructions seems vague or incomplete, let me know and I can refine the guidance.