The Skeleton of Laravel Project Structure
Navigating a fresh Laravel installation can feel a bit like walking into a massive, multi-room workshop. Everything has a specific place, and knowing where things live will save you hours of searching.
Here is a breakdown of the Laravel project skeleton, focusing on the directories you will interact with the most.
app/Directory (The Brains)This is the heart of your application. It contains the core PHP code for your project.
Http/Controllers/: Where you handle incoming HTTP requests and pass data to views.
Models/: Contains your Eloquent model classes (each table in your database usually has a corresponding Model to interact with it).
Providers/: Service Providers. These "bootstrap" your application by binding things into Laravel's service container.
routes/Directory (The Traffic Controller)This directory contains all the route definitions for your application.
web.php: Where you define routes for your web interface. These routes are assigned the web middleware group, which provides features like session state and CSRF protection.
api.php: Where you define routes for your API. These routes are stateless and usually use token authentication.
console.php: Where you define your closure-based console commands.
resources/Directory (The Face)This directory contains your front-end assets and raw, un-compiled files.
views/: Contains your HTML templates, typically using Laravel's Blade templating engine (e.g., welcome.blade.php).
css/ & js/: Your raw frontend assets before they are compiled by Vite or Laravel Mix.
database/Directory (The Backbone)Everything related to your database setup lives here.
migrations/: Database version control. These files define your database schema so it can be easily recreated on any machine.
factories/: Used to generate large amounts of fake data for testing or seeding.
seeders/: Used to populate your database with initial data (like an admin user or a list of countries).
config/ Directory (The Control Panel)As the name implies, this contains all of your application's configuration files (e.g., app.php, database.php, mail.php). Most of these files pull their actual values from your hidden .env file at the root of the project.
.env: The Environment Configuration file. This is where you store sensitive data like database credentials, API keys, and app environment settings (local vs production). Never commit this file to Git.
composer.json: Manages your PHP dependencies (libraries and packages required by Laravel).
artisan: The command-line interface for Laravel. You use it by running php artisan [command] in your terminal to generate code, run migrations, or clear caches.
To understand how a full-stack Laravel application functions, it helps to look at it as a unified ecosystem where the backend logic and the frontend user interface are tightly coupled.
Laravel shines as a full-stack framework because it manages everything from database queries to HTML rendering under one roof.
When a user interacts with a full-stack Laravel application, the request moves through a predictable, circular cycle:
[ Browser ] ──( HTTP Request )──> [ routes/web.php ]
▲ │
│(HTML / CSS / JS) (Dispatches)
│ ▼
[ Blade View ]<──( Passes Data ) ── [ Controller ]
│
(Queries / Saves)
▼
[ DB / Model ]
The Request: A user clicks a link or submits a form, sending an HTTP request to your server.
The Route: The request hits routes/web.php, which determines which Controller should handle it.
The Controller: The controller processes business logic. It talks to your Eloquent Models to fetch or save data in the database.
The View: The controller takes that data and passes it to a Blade template (resources/views/).
The Response: The server compiles the Blade template into standard HTML and sends it back to the user's browser.
A robust full-stack Laravel application relies on a few core pillars to handle data, logic, and presentation efficiently.
Laravel strictly adheres to the MVC architectural pattern to separate concerns:
Model ($M$): Represents your data structure and business rules. If you have a users table, you have a User.php model to interact with it.
View ($V$): The presentation layer (HTML/CSS). In Laravel, this is powered by the Blade engine.
Controller ($C$): The glue. It accepts user input from the View, commands the Model to manipulate data, and updates the View.
Modern full-stack Laravel applications use Vite to asset-bundle frontend code. When you write modern JavaScript or use utility-first CSS frameworks like Tailwind CSS, Vite watches your files in real-time, compiles them, and injects them instantly into your Blade views.
Because it is full-stack, Laravel handles user sessions natively. It uses secure, encrypted cookies to keep users logged in, flash temporary "success" messages across pages, and protect against Cross-Site Request Forgery (CSRF) via native @csrf Blade tokens.
While standard Blade templates work perfectly for traditional apps, the Laravel ecosystem offers advanced architectural flavors depending on how "reactive" you want your frontend to feel:
How it works: Laravel renders HTML on the server. You use Tailwind for styling and Alpine.js for minor JavaScript sprinkles (like dropdowns or mobile menus).
Best for: Content-heavy sites, blogs, e-commerce, and SEO-focused applications.
How it works: Livewire allows you to build dynamic, real-time user interfaces using only PHP. When a user clicks a button, Livewire makes a seamless AJAX request behind the scenes and updates the page without a full browser reload.
Best for: Dashboards, complex forms, and dynamic web applications where you want to avoid writing complex API layers and JavaScript.
How it works: Inertia bridges the gap between Laravel and modern JavaScript frameworks. You use Vue or React to build your entire frontend, but you use standard Laravel routing and controllers instead of building a separate client-side router or REST API.
Best for: Rich, highly interactive single-page applications where you prefer Vue or React but love Laravel's backend simplicity.
When you choose to use Laravel strictly as a Headless Backend API, the architecture shifts drastically away from rendering web pages. Instead, Laravel serves as a high-performance, stateless data machine. Your frontend (whether it is a React/Next.js SPA, a Vue app, or a mobile app) lives entirely independently, communicating with Laravel exclusively through HTTP requests.
In a headless architecture, Laravel doesn't care what the frontend looks like or what technology it uses. It only cares about inputs and outputs—typically formatted as JSON.
[ Frontend App ] ──( HTTP Request: GET /api/users )──> [ routes/api.php ]
▲ │
│ (Routes to)
│(JSON Response) ▼
[ API Resource ] <──( Transforms )── [ Model ] <── [ Controller ]
The Request: The frontend application makes an asynchronous network call (using fetch, Axios, etc.) to an API endpoint, passing along authentication tokens and data payload if necessary.
The Routing & Middleware: The request enters through routes/api.php. It passes through the api middleware group, which handles rate limiting, CORS (Cross-Origin Resource Sharing), and token authentication (via Laravel Sanctum).
The Controller: The controller handles the request, interacting with Eloquent Models to fetch, store, or modify data in the database.
The Transformation (API Resources): Instead of passing raw database data or models directly back to the user, Laravel uses API Resources to format and clean the data into a structured JSON response.
The Response: Laravel sends a raw JSON payload back to the frontend along with an appropriate HTTP status code (e.g., 200 OK, 201 Created, 401 Unauthorized).
When you transition Laravel into a Headless Backend API architecture, you strip away the frontend rendering responsibilities (the "head") and treat Laravel purely as a data-engine and business-logic service.
The frontend becomes a completely independent application—built with frameworks like Next.js, Nuxt, React, iOS, or Android—that communicates with Laravel exclusively over HTTP.
In a headless architecture, Laravel never sends back HTML. Instead, it receives requests containing JSON or form data, processes it, and returns structured data (usually JSON) along with standardized HTTP status codes.
[ Independent Frontend ] ──( HTTP Request with JSON / Token )──> [ routes/api.php ]
▲ │
│ (Middleware)
│(JSON Response: e.g., 200 OK) ▼
[ API Resource ] <──( Formats Data )── [ Controller ] <─── [ Auth & Guard ]
│
(Model / DB)
The Request: The frontend application makes an asynchronous network call (fetch or axios) to a Laravel URL (e.g., https://api.myapp.com/v1/posts).
The API Route & Middleware: The request enters through routes/api.php. It bypasses web features like sessions and cookies, running instead through the api middleware group (which handles rate limiting and token authentication).
Authentication/Guard: If the route is protected, middleware verifies the incoming API key or Bearer Token (via Laravel Sanctum or Passport).
The Controller & Model: The Controller executes business logic, interacts with Eloquent Models, and retrieves database records.
The API Resource: Instead of a View, data is passed through an API Resource layer that formats the PHP objects into clean, predictable JSON arrays.
The Response: Laravel issues an HTTP response with a JSON payload and an appropriate status code (e.g., 200 OK, 201 Created, or 422 Unprocessable Entity).
To build a secure and performant headless backend, Laravel introduces or reconfigures several key architectural layers:
routes/api.php)Routes defined here are completely stateless. Because there are no sessions to remember who a user is between requests, every single incoming request must prove its identity by attaching a secure cryptographic token to the HTTP header.
Laravel provides two robust, native options for managing API security:
Laravel Sanctum: A lightweight, easy-to-use authentication system. Perfect for Single Page Applications (SPAs), mobile apps, and simple token-based API keys.
Laravel Passport: A full, heavy-duty OAuth2 server implementation. Use this if your backend needs to allow third-party applications to integrate and authenticate with your platform (like how apps allow you to "Log in with GitHub").
You should never return a raw database model directly from your controller, as it can accidentally leak sensitive internal columns (like password or remember_token).
Laravel uses API Resources to act as a transformation layer between your Eloquent models and the JSON responses returned to the user. It allows you to precisely shape the JSON structure, rename keys, and conditionally load database relationships.
Because your frontend and backend live on different domains or ports (e.g., myapp.com talking to api.myapp.com), modern browsers will block requests by default for security. Laravel includes built-in CORS configuration (config/cors.php) allowing you to specify exactly which frontend domains are permitted to talk to your backend.
In a full-stack app, a validation failure redirects the user back to the form with errors. In a headless app, Laravel automatically intercepts validation failures or exceptions and transforms them into standard JSON error objects accompanied by specific HTTP client error codes ($4xx$ or $5xx$).
When deploying a headless Laravel architecture, developers usually choose between two structural patterns:
| Feature | Monolith / Shared Host | Decoupled / Microservice |
| Setup | Frontend and Laravel API live in the same Git repository. | Frontend and Laravel live in completely separate repositories. |
| Deployment | Deployed together to a single server. | Frontend is deployed to an edge network (Vercel, Netlify), Laravel to a cloud server (AWS, DigitalOcean). |
| Auth Style | Sanctum cookie-based SPA authentication (highly secure, prevents XSS). | Sanctum token-based Bearer tokens (ideal for cross-domain or mobile applications). |