๐Ÿ“˜ Project Documentation

๐Ÿงฑ Environment

Laravel (modular, service-based)

๐ŸŽฏ Purpose

ูŽAppointment Treatment Reservation Booking System

๐Ÿ‘ฅ User Roles

  • Admin
  • Provider
  • User
  • Development

๐Ÿ—„๏ธ Database & Permissions

Role-based access control via Spatie package. Providers extend users.

๐Ÿ”Œ API Conventions

Request validation, Resource formatting, Route structure: /api/{role}/{resource}/{action}

๐Ÿงฑ Example Modules Structure

This Laravel project uses nwidart/laravel-modules to support a clean and scalable modular architecture. Each module contains the following folders:

  • Config/ โ€“ Configuration files
  • Console/ โ€“ Custom Artisan commands
  • Database/ โ€“ Migrations, Seeders, Factories
  • Entities/ โ€“ Eloquent models (e.g. User.php)
  • Http/ โ€“ Controllers, Middleware, Requests (grouped by roles)
  • Providers/ โ€“ Service providers to bind services/routes
  • Resources/ โ€“ Blade templates (optional, not used in API-based modules)
  • Routes/ โ€“ API/web route files
  • Services/ โ€“ Business logic with interface and implementation
  • Tests/ โ€“ Unit/feature tests
  • Transformers/ โ€“ Laravel API Resources grouped by role

๐ŸŒฑ Seeder Strategy

Seeders help create consistent dummy data across dev environments and automate testing. Each module may contain:

  • UsersTableSeeder โ€“ Generates admins, providers, users with random or fixed attributes
  • RolesSeeder โ€“ Syncs role/permission structures (via Spatie or Laratrust)
  • ProviderSeeder โ€“ Populates providers with linked services, specializations
  • CalendarSeeders โ€“ Fills years, months, weekdays, and days
  • ReservationSeeder โ€“ Optionally generates sample booking data

๐Ÿค– AI RULES for Modification

This project is intended to be AI-agent friendly (e.g., Cursor, GPT-based agents). Follow these rules to ensure maintainability and smooth collaboration with agents:

  • โŒ Avoid putting business logic in controllers.
  • โœ… Always inject interfaces (Service Pattern).
  • ๐Ÿ“ฆ Validate inputs using Form Request classes.
  • ๐Ÿ“ค Format responses via Laravel Resources (Transformers).
  • ๐Ÿงช Seeders should cover core test data (roles, users, relations).
  • ๐Ÿง  Follow naming conventions and keep modules self-contained.
  • ๐Ÿ“ Store all dynamic files in their module (Routes, Configs, Services...)

๐Ÿงฎ Database Structure & Relationships

ER Diagram

Mermaid ER Diagram and table summaries of all key entities.

๐Ÿงฐ Composer Packages & Usage

This project utilizes a carefully curated set of Composer packages. Highlights include:

  • nwidart/laravel-modules: Enables true modular structure
  • spatie/laravel-permission: Role and permission management
  • spatie/laravel-medialibrary: Handles file uploads and associations
  • cviebrock/eloquent-sluggable: Auto-generate SEO-friendly slugs
  • shetabit/payment: Powerful multi-gateway payment layer
  • laravel/passport & sanctum: Advanced API authentication
  • vinkla/hashids: Obfuscates IDs for user-friendly URLs
  • dedoc/scramble & scribe: Live API docs from code

All packages are well-integrated and follow PSR and Laravel service provider conventions. No unnecessary dependencies are installed.