# AGENTS.md

## Project overview

This repository is a Laravel 9 application for the Astra Digital marketing site and CMS/admin panel. The app serves a public marketing website plus an admin dashboard for content management, leads, settings, and uploads.

Relevant references:
- [README.md](README.md)
- [SETUP.md](SETUP.md)
- [composer.json](composer.json)
- [package.json](package.json)
- [routes/web.php](routes/web.php)

## Local setup and commands

- Preferred local setup is SQLite, not MySQL.
- Use the project docs for exact local credentials and setup steps: see [SETUP.md](SETUP.md).
- Typical commands:
  - `composer install`
  - `php artisan key:generate`
  - `php artisan storage:link`
  - `php artisan migrate --seed`
  - `php artisan serve`
  - `npm install`
  - `npm run build`

## Architecture and conventions

- Backend: Laravel app under `app/`, `routes/`, `database/`, `config/`
- Public site: `WebsiteController` and public routes in [routes/web.php](routes/web.php)
- Admin area: grouped under `Route::middleware('auth.admin')->prefix('admin')` in [routes/web.php](routes/web.php)
- Admin auth is custom and uses session-based checks (`admin_id`) via [app/Http/Middleware/AdminAuth.php](app/Http/Middleware/AdminAuth.php) and [app/Http/Kernel.php](app/Http/Kernel.php)
- Content/admin controllers live under `app/Http/Controllers/Admin/`
- Models live under `app/Models/`
- Blade templates live under `resources/views/`
- Public assets and uploaded files are stored in `public/` and `storage/`

## Working expectations for AI coding agents

- Prefer minimal, surgical changes that match the existing Laravel patterns.
- When editing a feature, start from the matching route, controller, model, and view for that feature.
- Keep admin CRUD patterns consistent with the existing admin controllers and route naming (`admin.*`).
- For new pages or features, reuse the existing admin structure instead of creating a separate framework.
- Keep DB work migration-first; if a change affects seeded content or admin settings, update the relevant seeder or setup documentation.
- Prefer route names and controller actions already used in the project over introducing a new pattern.

## Common gotchas

- Do not assume MySQL. The project is configured for SQLite-first local development.
- The admin area is protected by a custom middleware, not the default Laravel auth guard.
- Many admin screens use toggle, reorder, and upload flows; follow the existing CRUD patterns rather than inventing separate conventions.
- The site mixes marketing pages, CMS content, and dynamic sections; keep changes scoped to the relevant section and avoid broad rewrites.

## Validation

Before claiming success, validate the relevant behavior with the smallest relevant command:

- `php artisan test` for feature/unit coverage
- `php artisan route:list` when route or middleware issues are suspected
- `php artisan serve` for manual browser validation of UI flows
- `npm run build` when changing frontend assets

## Claude-specific guidance

When working on this project with Claude, favor project-local patterns over generic Laravel advice:

- Read the route file first to understand the page or admin feature entry point.
- Check the matching admin controller before making logic changes.
- Reuse the existing admin auth and session conventions instead of introducing default auth code.
- Treat the project as a custom marketing CMS, not a vanilla Laravel starter app.