Skip to main content

​
Overview

Macuin follows the standard Laravel 11 directory structure, organized for building a SaaS e-commerce platform for automotive parts. The application uses a Docker-based development environment with PostgreSQL, Nginx, and Node.js.

​
Root Directory Structure

macuin/
├── app/                 # Application core code
├── bootstrap/           # Framework bootstrap files
├── config/              # Configuration files
├── database/            # Migrations, seeders, factories
├── docker/              # Docker configuration files
├── public/              # Public assets and entry point
├── resources/           # Views, CSS, JS
├── routes/              # Route definitions
├── storage/             # Logs, cache, uploaded files
├── tests/               # Test files
├── artisan              # CLI tool
├── composer.json        # PHP dependencies
├── docker-compose.yml   # Docker services configuration
└── package.json         # Node dependencies

​
Key Directories

​
app/

The app/ directory contains the core application code: 
app/
├── Http/
│   └── Controllers/     # HTTP controllers
├── Models/              # Eloquent models
├── Providers/           # Service providers
└── View/
    └── Components/      # Blade components
The app/ directory follows Laravel conventions for organizing business logic, controllers, and models.

​
Models

Eloquent models define the structure and relationships of your database tables:
app/Models/User.php
class User extends Authenticatable
{
    use HasFactory, Notifiable;

    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    protected $hidden = [
        'password',
        'remember_token',
    ];

    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }
}

​
View Components

Blade components for reusable UI elements:
  • Alert.php - Alert messages
  • Footer.php - Page footer
  • Navbar.php - Navigation bar
  • ProductCard.php - Product display card

​
resources/

Front-end assets and Blade templates: 
resources/
├── css/                 # Stylesheets
├── js/                  # JavaScript files
└── views/               # Blade templates
    ├── auth/            # Authentication views
    ├── carrito/         # Shopping cart views
    ├── catalogos/       # Catalog views
    ├── components/      # Blade components
    ├── home/            # Homepage views
    ├── layouts/         # Layout templates
    └── pedidos/         # Order views

auth/

Login and registration pages

carrito/

Shopping cart interface

catalogos/

Product catalog views

pedidos/

Order management pages

​
routes/

Route definitions for the application:
  • web.php - Web application routes
See the Routes page for detailed route documentation.

​
database/

Database-related files: 
database/
├── factories/           # Model factories for testing
├── migrations/          # Database migrations
└── seeders/             # Database seeders
See the Database page for schema details.

​
config/

Configuration files for various Laravel services:
  • app.php - Application configuration
  • auth.php - Authentication settings
  • database.php - Database connections
  • cache.php - Cache configuration
  • mail.php - Email settings
  • queue.php - Queue configuration
  • services.php - Third-party services

​
public/

Public assets accessible via web server: 
public/
├── index.php            # Application entry point
├── .htaccess            # Apache configuration
├── favicon.ico          # Site icon
└── robots.txt           # Search engine directives
The public/ directory is the web server document root. All requests are routed through index.php.

​
storage/

Application-generated files: 
storage/
├── app/                 # User-uploaded files
├── framework/           # Framework-generated files
│   ├── cache/           # Application cache
│   ├── sessions/        # Session files
│   └── views/           # Compiled Blade templates
└── logs/                # Application logs

​
docker/

Docker configuration files: 
docker/
├── nginx/               # Nginx web server config
└── php/                 # PHP-FPM Dockerfile

​
Laravel Conventions

​
Naming Conventions

Models

Singular, PascalCase: User, Product

Controllers

PascalCase with suffix: UserController

Migrations

Snake case: create_users_table

Routes

Kebab case: /order-details

​
File Organization

  • Controllers: Handle HTTP requests and return responses
  • Models: Represent database tables and relationships
  • Views: Blade templates for rendering HTML
  • Migrations: Version control for database schema
  • Routes: Define URL patterns and map to controllers

​
Docker Architecture

The application runs in Docker containers defined in docker-compose.yml: 
services:
  postgres:      # PostgreSQL 16 database
  app:           # PHP-FPM application
  nginx:         # Nginx web server (port 8000)
  node:          # Node.js for Vite dev server (port 5173)

​
Development Workflow

  1. Code changes are made in the project root
  2. Views are compiled by Laravel’s Blade engine
  3. Assets are bundled by Vite (Node container)
  4. Requests are handled by Nginx → PHP-FPM → Laravel
  5. Database operations use PostgreSQL container
All containers share the project directory via volume mounts, enabling live code updates without rebuilding.

Build docs developers (and LLMs) love

Get started for freeTalk to us