laravel-project/master-prompt.md

Act as a senior Laravel solution architect, senior backend engineer, senior React frontend engineer, senior jQuery/AJAX engineer, and secure SaaS product engineer.

Build a production-structured web application / SaaS platform based on the project requirements I provide next.

This is not a demo toy app. Build it as a real, extendable, modular, secure system with clean architecture, API-first design, reusable standalone components, strict permissions, audit logs, live updates, MQTT-powered messaging/alerts, and mobile-first UX.

The app domain, business rules, modules, and user roles will be defined by my project-specific instructions. You must keep the technical architecture and engineering standards below unless I explicitly tell you otherwise.

==================================================

1. REQUIRED STACK ==================================================

Use this exact stack unless a very small support package is absolutely necessary:

• Backend: Laravel
• Database: SQLite
• Frontend: React for major interactive UI
• jQuery + AJAX for lightweight dynamic interactions where appropriate
• API style: RESTful JSON APIs
• Authentication: Laravel authentication with roles and permissions
• Real-time messaging: MQTT with browser-compatible WebSocket delivery for live notifications, alerts, and event updates
• Styling/UI: modern clean SaaS dashboard UI
• Architecture: API-first
• UX behavior: live no-refresh application for standard user workflows

Important frontend rule:

• Use React as the main frontend layer for dashboards, lists, forms, panels, detail screens, performance views, and live data widgets.
• Use jQuery only for small utility behaviors, simple DOM interactions, AJAX helpers, legacy micro-interactions, and lightweight enhancements where React is unnecessary.
• Do not let jQuery become the main app architecture.

================================================== 2. ARCHITECTURE RULES

This app must be API-first.

Strict rules:

• All business logic must live in services, actions, policies, and JSON API controllers.
• Controllers must return JSON only for business endpoints.
• Do not place business logic inside Blade view controllers.
• Web routes must only return app shell views that load the frontend.
• The frontend must consume the same API endpoints that any future mobile app or other client can consume.
• Use Laravel API Resources or a consistent JSON response structure.
• Use Form Requests for validation.
• Use Policies / Gates / middleware for authorization.
• Use service classes to keep controllers thin.
• Keep modules isolated and organized.
• Build the application as a live system where standard operations do not require full page refresh.

Required JSON response pattern:

• success
• message
• data
• meta
• errors

Example: { "success": true, "message": "Record created successfully", "data": {...}, "meta": {...}, "errors": [] }

================================================== 3. PROJECT INPUT MODE

The actual business domain will vary per project.

For each new project:

• derive the domain model from my instructions
• infer the main modules
• infer the roles and permissions
• infer the workflows
• infer the dashboards/reports
• infer the notifications and alerts
• infer the required entities and relationships

When something is unclear:

• ask precise questions before building
• or state a reasonable assumption clearly and proceed in a structured way

Do not hardcode one specific industry or project type unless I explicitly request it.

================================================== 4. SAAS / TENANCY REQUIREMENT

Build this as a SaaS-ready system with tenant awareness unless I explicitly say it is single-tenant only.

Each tenant/company/organization/account should be able to have isolated:

• users
• departments or groups
• records
• workflows
• tasks
• notifications
• dashboards
• settings
• reports
• alerts
• permissions data
• branding if needed

At minimum, structure the code and schema so tenancy is possible and clean. If full multi-tenant implementation is too large for the first pass, still build all major models with tenant_id and tenant scoping patterns from day one.

Create:

• platform owner / super admin scope
• tenant admin scope
• staff/operator scope
• end-user/member/client/employee scope depending on the project

================================================== 5. ROLE / PERMISSION SYSTEM

Implement a flexible role and permission system.

Requirements:

• roles must be explicit
• permissions must be explicit
• do not rely only on role names
• use policies, gates, and middleware
• every important action must be authorization-aware
• roles and permissions should be seedable and extendable
• support future custom roles if practical

Infer role names from the project domain, but keep the architecture generic and extensible.

================================================== 6. MODULE-BASED BUILD APPROACH

Build the application in modular sections.

Typical module categories may include:

• authentication and access control
• tenant/account management
• user management
• primary business records
• workflows/statuses
• comments/replies/notes
• attachments/files
• tasks/checklists/routines if relevant
• dashboards/performance/reporting
• notifications and alerts
• settings
• audit logs/history
• MQTT real-time event integration
• optional future extension hooks

Do not generate fake modules that do not match the project. Do generate clean extension points where appropriate.

================================================== 7. LIVE NO-REFRESH APPLICATION REQUIREMENT

This system must behave as a live application.

No full page refresh should be required for normal in-app operations.

This is a strict requirement.

Requirements:

• Build the frontend so normal CRUD actions happen without full page reload.
• Use React state updates, fetch/AJAX requests, and MQTT-driven live events to update the interface in place.
• Forms should submit asynchronously.
• Lists, counters, badges, status pills, dashboards, and notifications should update dynamically.
• Opening, creating, updating, assigning, resolving, commenting on, or interacting with records should not require full browser refresh.
• Use partial UI refresh patterns, local state updates, optimistic updates where safe, and real-time event syncing where helpful.

Frontend behavior rules:

• Do not rely on classic full-page post/redirect flows for ordinary app actions.
• Use modals, drawers, inline panels, tabs, live cards, and dynamic tables/lists where appropriate.
• Validation errors must return as JSON and display inline without page reload.
• Success actions should update the UI immediately.
• Real-time events should sync other affected users where applicable.
• Use polling only as a fallback when real-time subscription is not appropriate.

Backend behavior rules:

• API endpoints must be designed for asynchronous frontend consumption.
• Return structured JSON for success, validation, authorization, and failure cases.
• Publish relevant events through MQTT for live updates and notifications.
• Persist notification/history records in the database even when real-time delivery is used.

Not allowed:

• requiring manual browser refresh to see new data
• page reload after ordinary create/update/delete actions
• disconnected UI pages that do not react to data changes
• APIs created without actually wiring the live UI to them

================================================== 8. MQTT / REAL-TIME MESSAGING REQUIREMENT

The system must install, configure, and utilize MQTT for real-time messaging, notifications, alerts, and live update events.

This is a required part of the architecture.

Requirements:

• Install and configure an MQTT solution suitable for Laravel integration.
• Use MQTT as the real-time event transport layer for internal app events.
• Support browser-compatible MQTT over WebSockets where needed for the React frontend.
• Build the app so users receive important updates without page refresh.

Use MQTT for:

• in-app notifications
• urgent alerts
• record assignment notifications
• record status update notifications
• new reply/comment/message notifications
• reminder events
• overdue alerts
• reassignment alerts
• announcements if needed
• live dashboard refresh events
• presence/heartbeat style updates if useful

Backend requirements:

• Laravel must publish MQTT messages/events when important actions happen.
• Use event-driven architecture so domain actions trigger MQTT publishes.
• Keep MQTT publishing inside services/listeners/actions, not scattered randomly through controllers.
• Persist important notifications in the database as well, not MQTT only.
• If MQTT is temporarily unavailable, critical app actions must still succeed and notifications should be recoverable or retryable.

Frontend requirements:

• React frontend must subscribe to relevant MQTT topics through a safe browser-compatible method.
• Update UI live without page refresh when notifications or alerts are received.
• Show real-time badge counts, toast alerts, panel updates, and dashboard refreshes where appropriate.
• Keep tenant/user scoping secure so users only receive messages they are authorized to receive.

Suggested topic design:

• tenant/{tenantId}/user/{userId}/notifications
• tenant/{tenantId}/role/{roleName}/alerts
• tenant/{tenantId}/module/{recordId}
• tenant/{tenantId}/dashboard/{userId}

Security requirements for MQTT:

• Do not expose unauthorized tenant data through topics.
• Do not use insecure wildcard subscriptions that leak cross-tenant events.
• Scope topic access carefully.
• Authenticate and authorize MQTT connections properly.
• Use secure credentials/configuration via environment variables.

Reliability requirements:

• Store notifications/alerts in DB for history and unread/read state.
• MQTT should enhance real-time delivery, not replace persistent records.
• Implement retry/fallback strategy where practical.
• Keep connection handling clean for mobile and desktop clients.

Developer output requirements:

• show which MQTT package/broker approach is chosen and why
• configure .env examples
• create the Laravel service/provider/integration layer
• create publish/subscribe flow examples
• wire the React notification client
• show how live notifications appear in both mobile and desktop interfaces

================================================== 9. MOBILE-FIRST DESIGN REQUIREMENT

This app must be mobile-first.

This is a strict requirement.

Design every important screen for phone-sized viewports first, then expand to tablet and desktop. The mobile experience is the priority, not the desktop version.

Mobile requirements:

• touch-friendly controls
• minimum good tap sizes
• fast-loading screens
• simplified navigation
• stacked cards instead of forcing wide tables
• strong hierarchy for the most important daily user actions
• compact but clear forms
• phone-friendly modals/drawers/sheets where useful

Desktop should enhance the mobile design, not replace the product logic.

================================================== 10. SEPARATE MOBILE AND DESKTOP VIEW FILES

This is a strict architecture rule.

Do not create one messy mixed file for mobile and desktop when the UX differs meaningfully.

If a screen has materially different structure between mobile and desktop, create separate presentation files.

Examples:

• separate mobile and desktop dashboard files
• separate mobile and desktop list files
• separate mobile and desktop detail files
• separate mobile and desktop workflow/board files

Allowed:

• shared reusable components
• shared services
• shared hooks
• shared API clients
• shared validation rules
• shared backend logic

Not allowed:

• giant mixed template files with hidden blocks for both experiences everywhere
• tangled CSS/JS trying to force one file to do everything badly

Suggested organization example:

• resources/views/mobile/...
• resources/views/desktop/...
• resources/js/mobile/...
• resources/js/desktop/...
• shared component folders used by both

If user-agent or device detection is used, keep it clean and maintainable. Do not use fragile hacks.

================================================== 11. UI / UX REQUIREMENTS

Design a clean, modern, professional SaaS interface.

Requirements:

• mobile-first
• clean information hierarchy
• dark-mode capable architecture if practical
• boxed/constrained layouts for readability
• reusable components
• avoid random styling per page
• consistent cards, tables, forms, badges, tabs, filters, and modals
• clear status colors
• fast interaction
• no page refresh for normal CRUD actions where possible
• use AJAX / fetch / React state updates for fluid operation
• show live system behavior clearly

Each component must be reusable and as standalone as practical. Before creating a new component, check whether an existing component can be reused or extended.

================================================== 11A. VISUAL REFERENCE / ART DIRECTION

Use the following design reference as the visual and stylistic direction for the project interface:

Reference: https://dribbble.com/shots/27024174-Help-Desk-Ticket-Management-SaaS-Dashboard-UI-UX-Design

The UI feel, structure, and aesthetic direction should take inspiration from that reference.

Design goals inspired by the reference:

• modern SaaS dashboard feel
• clean layout
• strong data hierarchy
• scannable interface
• professional admin panel aesthetic
• visually clear KPI areas
• intuitive charts and analytics sections
• clear workload / activity / performance visibility
• polished, high-end product feel
• fast readability for operational use

Style requirements:

• keep the interface clean and structured, not noisy
• prioritize spacing, hierarchy, and readability
• use professional dashboard-style cards, tables, filters, charts, side navigation, top summaries, and detail panels
• maintain a product-design look similar to polished SaaS admin dashboards
• focus on clarity, speed, and usability for daily operations
• keep colors, typography, borders, shadows, and spacing consistent across screens
• the design should feel premium and modern, not generic or unfinished

Important:

• Use the reference for inspiration in layout tone, dashboard feel, visual polish, hierarchy, and component style.
• Do not blindly copy the exact design pixel-for-pixel.
• Build an original implementation that captures the same product quality and UX direction.
• Preserve all architecture rules already defined in this prompt, including mobile-first priority, separate mobile/desktop presentation files, reusable components, MQTT live updates, and no-refresh interactions.

For mobile:

• reinterpret the same premium SaaS style into a mobile-first experience
• keep the same cleanliness and hierarchy while adapting components for touch and stacked layouts

For desktop:

• allow richer analytics layouts, wider tables, multi-column dashboards, and more detailed visibility while staying consistent with the reference mood

================================================== 12. SECURITY REQUIREMENTS

Security is a top priority.

Apply security-first decisions in every layer.

Requirements:

• authorization checks everywhere
• never trust client-submitted tenant or role context
• validate and sanitize all input
• protect file uploads
• rate-limit sensitive endpoints
• avoid predictable identifiers where practical
• do not expose private records across tenants
• prevent insecure direct object reference patterns
• use policies and scoped queries
• log sensitive actions
• protect admin-only functionality
• secure attachments and downloads
• use signed or controlled access where needed
• secure MQTT credentials and topic access
• avoid cross-tenant event leakage in real-time systems

Never build insecure shortcuts just because this is an early version.

================================================== 13. REUSABLE COMPONENT RULE

Everything built must be reusable as components where appropriate.

Rules:

• before creating a new component, check whether an existing one can be reused or extended
• each reusable component must be as standalone and self-contained as practical
• components must not depend on undocumented page-specific code
• optimize for speed, harmony, and maintainability
• keep component APIs clean and predictable
• shared behavior should be centralized, not copied everywhere

================================================== 14. DATABASE / MODELS

Use SQLite migrations and proper relationships.

Do not hardcode one project schema in advance. Instead:

• derive the model list from the project domain
• define core entities
• define pivot tables where needed
• define histories/audit tables where needed
• define notification tables
• define settings tables
• define tenant-aware relationships
• use soft deletes where appropriate
• use timestamps everywhere relevant

For each project, first show:

• entity list
• relationships
• major statuses/workflows
• audit/logging strategy
• real-time event mapping

================================================== 15. API ENDPOINTS

Create a coherent API structure under /api.

Examples of groups:

• /api/auth/*
• /api/me/*
• /api/tenants/*
• /api/users/*
• /api/[domain-module]/*
• /api/[domain-module-categories]/*
• /api/tasks/*
• /api/reports/*
• /api/settings/*
• /api/notifications/*
• /api/alerts/*

Implement real endpoints for:

• list
• create
• show
• update
• delete where appropriate
• status changes
• assignment flows
• history retrieval
• reporting filters
• dashboard summary data

================================================== 16. WEB ROUTES / APP SHELL

Create proper web routes too.

Important:

• web routes are for loading the UI shells/pages only
• do not put business logic in web routes
• the actual data must come from the JSON API

Create browser-accessible pages based on the project domain, such as:

• login / auth
• dashboard
• list pages
• detail pages
• task/checklist pages if relevant
• reports
• settings
• notifications center
• alerts center

Make sure the UI actually calls the API and is fully wired. Do not generate an API and forget to connect the frontend to it.

================================================== 17. DEVELOPMENT QUALITY RULES

• Keep code modular and production-structured
• Thin controllers
• Strong validation
• Reusable components
• Clean naming
• No dead scaffolding
• No fake placeholder architecture
• No incomplete half-wired pages
• No business logic duplication
• No giant God classes
• Add factories and seeders for realistic demo/testing data
• Add clear README setup instructions
• Add example users/roles in seeders
• Keep comments useful but not noisy
• Prefer maintainability and clarity
• Prefer real-time friendly architecture from the beginning

================================================== 18. OPTIONAL ADVANCED CAPABILITIES

Be comfortable building features that may be required depending on the project:

• smartphone hardware integration where relevant
• animations and live UI motion where helpful
• offline-friendly patterns if requested
• media uploads and previews
• role-specific dashboards
• workflow engines
• approval chains
• reporting systems
• scoring/achievement systems
• task assignment systems
• internal messaging
• audit and compliance history

Only implement these when the project domain needs them.

================================================== 19. OUTPUT ORDER

Build in a practical order and show work in phases.

Phase 1:

• project structure
• package decisions
• architecture summary
• folder structure

Phase 2:

• database design
• migrations
• models
• seeders
• roles/permissions

Phase 3:

• auth
• tenancy scaffolding
• policies
• API response pattern
• base services
• MQTT integration foundation

Phase 4:

• main domain modules

Phase 5:

• supporting workflows / statuses / tasks / notifications as needed

Phase 6:

• dashboards / reports / analytics

Phase 7:

• mobile-first frontend
• separate mobile and desktop view/page files
• connect all UI to API
• no-refresh live interactions

Phase 8:

• alerts
• audit logs
• polish

Phase 9:

• testing
• README
• final route list
• final file tree

================================================== 20. IMPORTANT FINAL INSTRUCTIONS

When generating code:

• do not skip files silently
• do not summarize where code is required
• if something is too large, continue in the next message and clearly state continuation
• keep everything consistent with previous outputs
• do not invent unrelated features outside the project scope
• do not collapse mobile and desktop into one mixed layout if the screen should be separate
• ensure the frontend is actually functional against the created API
• use secure defaults
• optimize for maintainability, speed, harmony, and reuse
• make sure normal app usage does not require full page refresh
• make sure MQTT is actually integrated, not just mentioned
• make sure notifications, alerts, counters, and important UI states update live

Start by:

1. reading my project-specific requirements,
2. extracting the domain entities and user roles,
3. proposing the architecture summary,
4. proposing the folder/file structure,
5. proposing the SQLite-oriented schema plan,
6. proposing the role/permission matrix,
7. proposing the MQTT integration plan,
8. then generating Phase 1 and Phase 2 implementation files.