# Laravel Project Architecture & Folder Structure Rules
## Role
Act as a senior Laravel developer. Before writing or modifying code, inspect the existing Laravel project structure and follow the architecture rules below. Maintain clean, modular, reusable, and easy-to-understand code throughout the project.
## 1. Module-Based Architecture
Each business module must maintain its own organized structure. Do not mix unrelated modules in the same folders.
The clinic management system will contain modules such as:
- Patient Registration
- OPD Consultation
- Prescription
- Billing
- Patient History
- Dashboard & Reports
- User Access & Roles
- Backup & Audit Trail
- Pharmacy Stock Management
For each module, organize its controllers, models, views, validation, and related business logic under a clearly identifiable parent module folder wherever practical.
Example structure:
```text
app/
├── Modules/
│ ├── Patients/
│ │ ├── Controllers/
│ │ │ └── PatientController.php
│ │ ├── Models/
│ │ │ └── Patient.php
│ │ ├── Requests/
│ │ │ └── StorePatientRequest.php
│ │ └── Services/
│ │ └── PatientService.php
│ ├── Billing/
│ │ ├── Controllers/
│ │ ├── Models/
│ │ ├── Requests/
│ │ └── Services/
│ └── Pharmacy/
│ ├── Controllers/
│ ├── Models/
│ ├── Requests/
│ └── Services/
```
Important:
- Keep each module independent and easy to maintain.
- Place each controller and model in its appropriate module folder.
- Keep related business logic inside its module.
- Use shared services only when genuinely needed by multiple modules.
- Follow Laravel naming conventions and use namespaces that match the folder structure.
- Configure model discovery, autoloading, routing, and other Laravel integrations correctly if custom module folders are used.
- Do not create duplicate models or controllers for the same entity.
- Keep migrations in Laravel's standard `database/migrations` directory unless a documented project-specific migration loader is configured.
## 2. Parent and Child View Folders
Views must be separated by module and feature. Do not put all views directly inside one folder.
Example:
```text
resources/
└── views/
├── layouts/
│ ├── app.blade.php
│ └── guest.blade.php
├── components/
│ ├── layouts/
│ │ ├── header.blade.php
│ │ ├── sidebar.blade.php
│ │ ├── footer.blade.php
│ │ └── navigation.blade.php
│ └── ui/
│ ├── button.blade.php
│ ├── modal.blade.php
│ ├── alert.blade.php
│ └── form-field.blade.php
├── modules/
│ ├── patients/
│ │ ├── index.blade.php
│ │ ├── create.blade.php
│ │ ├── edit.blade.php
│ │ ├── show.blade.php
│ │ └── partials/
│ │ ├── form.blade.php
│ │ └── details.blade.php
│ ├── billing/
│ │ ├── index.blade.php
│ │ ├── create.blade.php
│ │ ├── show.blade.php
│ │ └── partials/
│ └── pharmacy/
│ ├── index.blade.php
│ ├── stock-entry.blade.php
│ ├── stock-list.blade.php
│ └── partials/
└── dashboard/
└── index.blade.php
```
Rules:
- Each module must have its own parent view folder.
- Separate child pages by function, such as listing, creation, editing, details, and reports.
- Reuse partial views and components instead of duplicating markup.
- Use consistent Blade view naming conventions.
- Keep business logic out of Blade templates.
## 3. Reusable Header, Footer, and Layout
The header, footer, sidebar, and navigation must be reusable components. Do not duplicate these sections across module pages.
Create a common application layout, for example:
`resources/views/layouts/app.blade.php`
The layout should include the shared header, sidebar, footer, navigation, common styles, and scripts as appropriate.
Example:
```blade
@yield('title', config('app.name'))
@vite(['resources/css/app.css', 'resources/js/app.js'])
@livewireStyles
@yield('content')
@livewireScripts
```
Use the layout from individual module views:
```blade
@extends('layouts.app')
@section('title', 'Patient Registration')
@section('content')
{{-- Patient registration page content --}}
@endsection
```
Rules:
- Render the shared layout once per page through the layout system.
- Include reusable components in the common layout rather than repeating them in each page.
- Keep the header, footer, sidebar, and navigation in separate component files.
- Avoid duplicate asset imports and duplicate script execution.
- Ensure the layout works with Livewire navigation and interactions.
- If authentication pages need a different layout, create a separate reusable guest layout.
## 4. Separate API and HTTP Communication Logic
Do not mix API communication logic with Blade templates or UI components.
Organize API-related code separately from controllers and views.
Example:
```text
app/
└── Modules/
└── Patients/
├── Controllers/
├── Models/
├── Services/
└── Requests/
resources/
└── js/
├── api/
│ ├── http.js
│ ├── patients.js
│ ├── billing.js
│ └── pharmacy.js
└── modules/
├── patients/
├── billing/
└── pharmacy/
```
Rules:
- Keep frontend API clients in `resources/js/api/` when JavaScript API calls are needed.
- Use a shared HTTP client for common configuration, authentication headers, error handling, and response handling where appropriate.
- Keep each API resource or module in its own file.
- Do not write raw `fetch()` or Axios calls repeatedly throughout UI code.
- Keep server-side business logic in Laravel services and controllers, not in JavaScript API clients.
- If the application uses Livewire for ordinary server-driven interactions, do not create unnecessary API endpoints or JavaScript API clients.
- Create API routes and JSON responses only when required, such as integrations, external clients, or independent frontend consumers.
- Keep `routes/web.php` for web routes and `routes/api.php` for API routes when the API routing feature is configured.
- Do not expose sensitive information in frontend code.
## 5. Controllers, Models, Services, and Validation
Follow separation of concerns.
- **Controllers:** Handle HTTP requests, authorize actions, call the appropriate services, and return views or responses.
- **Models:** Define database relationships, casts, and persistence-related behavior.
- **Form Requests:** Handle request validation and authorization rules.
- **Services:** Handle reusable or multi-step business operations.
- **Policies:** Handle resource-level authorization.
- **Blade components:** Handle reusable UI presentation.
- **Livewire components:** Handle server-driven interactive UI when required.
Avoid huge controllers, duplicate business logic, and models that contain unrelated responsibilities.
Do not introduce repository interfaces, extra abstraction layers, or additional packages unless they solve a real project requirement.
## 6. Laravel + Livewire Technology Rules
The project uses:
- Laravel for backend logic.
- Livewire for server-driven interactive interfaces.
- Blade for page layouts and templates.
- Tailwind CSS for styling.
- MySQL 8.0+ or compatible MariaDB with InnoDB, `utf8mb4`, foreign keys, and appropriate indexes.
Rules:
- Do not introduce React or Vue unless explicitly approved.
- Check the installed Laravel, Livewire, and PHP versions before using version-specific syntax.
- Use compatible APIs and conventions for the installed versions.
- Keep the architecture modular without unnecessarily fighting Laravel conventions.
- Store credentials and environment-specific configuration in `.env`, never hardcode secrets.
- Use database transactions for multi-step operations such as billing and stock updates.
## 7. Routes and Naming Conventions
Organize routes by module using route files or clearly separated route groups when appropriate.
Use consistent route names, URL patterns, namespaces, and middleware.
Example route names:
```text
patients.index
patients.create
patients.store
patients.show
patients.edit
patients.update
billing.index
billing.create
billing.store
pharmacy.stock.index
pharmacy.stock.store
```
Use route names in Blade templates rather than hardcoding URLs wherever possible.
Avoid duplicate route names, unclear naming, and oversized route files.
## 8. Maintainability and Safety
- Use dependency injection where appropriate.
- Validate all user input on the server.
- Apply authentication and authorization to protected operations.
- Use CSRF protection for web forms.
- Escape output and prevent unsafe SQL construction.
- Use database transactions for related financial and inventory changes.
- Do not delete or overwrite existing working code without inspecting its purpose.
- Avoid creating multiple files with overlapping responsibilities.
- Add tests for critical business logic and workflows.
- Document any non-standard architectural decisions.
## 9. Required Workflow Before Coding
Before implementing a module:
1. Inspect the existing Laravel project and installed dependencies.
2. Review the existing folder structure, routes, models, and views.
3. Identify reusable components and existing code that can be extended.
4. Propose the files and folders that will be created or modified.
5. Follow the existing architecture unless it conflicts with these rules.
6. Implement the module with clear separation of concerns.
7. Run the relevant tests and verify routes, migrations, and view rendering.
8. Report the files changed, implementation summary, tests run, and any outstanding issues.
Do not generate the entire application in one uncontrolled step. Implement and verify one module at a time.
## 10. Final Architecture Rule
Maintain a clean, modular, predictable Laravel project. A developer unfamiliar with the codebase should be able to locate a module's controller, model, validation, service, routes, and views without searching the entire project.
Before creating a new architectural pattern or adding a dependency, explain why it is necessary and wait for approval when it changes the agreed technology stack or project architecture.
---
Login credentials:
Admin: admin@hims.local / admin123
Doctor: doctor@hims.local / doctor123