Skip to content

Directory Structure

David Ciulla edited this page Nov 7, 2026 · 1 revision

Directory Structure

Introduction

Laravex follows the Laravel 13 application skeleton layout. If you have worked with Laravel before, the directory tree will feel immediately familiar. The project deliberately avoids Phoenix conventions — there is no lib/my_app_web/ directory, no contexts-as-primary-UX, and no router.ex as the main app shape.

my-app/
├── app/                    # Application code
│   ├── Http/
│   │   └── Controllers/    # Controller modules
│   ├── Models/             # Eloquex models
│   ├── Policies/           # Authorization policies
│   └── Providers/          # Service providers
├── bootstrap/              # Application builder and provider list
│   ├── app.ex              # Bootstrap.App — mirrors bootstrap/app.php
│   ├── providers.ex        # Bootstrap.Providers — provider registration list
│   └── cache/              # Compiled route/config caches (git-ignored)
├── config/                 # Laravex config files (*.exs maps)
│   ├── app.exs
│   ├── auth.exs
│   ├── cache.exs
│   ├── database.exs
│   ├── session.exs
│   └── ...
├── database/               # Migrations, factories, seeders
│   ├── factories/
│   ├── migrations/
│   └── seeders/
├── lib/
│   └── laravex/            # Framework runtime (Illuminate analogue)
├── public/                 # HTTP entry point and static assets
│   └── index.ex
├── resources/              # Views, CSS, JS source
│   ├── views/
│   ├── css/
│   └── js/
├── routes/                 # Route registration modules
│   ├── web.ex              # Routes.Web  (always present)
│   └── console.ex          # Routes.Console (always present)
├── storage/                # Logs, sessions, cache, uploads
│   ├── app/
│   ├── framework/
│   │   ├── cache/
│   │   ├── sessions/
│   │   └── views/
│   └── logs/
├── tests/                  # Feature and unit tests
│   ├── Feature/
│   └── Unit/
├── artisan                 # CLI entry point → `mix artisan`
├── mix.exs                 # Mix project file
└── .env                    # Environment variables (not committed)

The Root Directory

app/

The app/ directory contains the core application code. Almost everything you write lives here — models, controllers, providers, and policies. It mirrors app/ in a standard Laravel project.

bootstrap/

Contains two files that wire the application together:

  • bootstrap/app.ex — Defines Bootstrap.App.build/1, which calls Laravex.Foundation.Application.configure/1, chains routing, middleware, and exception configuration, and returns a configured %Application{} struct.
  • bootstrap/providers.ex — Defines Bootstrap.Providers.list/0, which returns the list of service provider modules to boot. Add your own providers here.

The bootstrap/cache/ subdirectory holds compiled artefacts generated by ./artisan config:cache and ./artisan route:cache. It is git-ignored.

config/

Holds Laravex application configuration as plain Elixir map files (*.exs). Do not place Mix environment files here — config.exs, dev.exs, test.exs, prod.exs, and runtime.exs are Mix's responsibility and are ignored by Laravex.Config.Repository.

See Configuration for details.

database/

Contains three subdirectories mirroring Laravel's database/:

  • database/migrations/ — Migration modules that define up/0 (and optionally down/0). Run with ./artisan migrate.
  • database/factories/ — Factory modules used in tests and seeding. Each factory uses Laravex.Support.Faker for fake data generation.
  • database/seeders/ — Seeder modules. Database.Seeders.DatabaseSeeder is the entry point, run with ./artisan db:seed.

lib/laravex/

The framework runtime — the Laravex equivalent of Laravel's illuminate/ packages. Application code should never need to live here. Extend it only when contributing to the framework itself.

Key namespaces inside lib/laravex/:

Namespace Purpose
Laravex.Foundation Application bootstrap, health, maintenance, server
Laravex.Routing Router, route cache, URL generation
Laravex.Http Kernel, request, response, middleware, paginator
Laravex.Database Query builder, connection, migrations, model base
Laravex.Eloquex Eloquex model, relations, factory, scopes
Laravex.Config Config repository
Laravex.Env .env loader and reader
Laravex.Container Service container (bind/singleton/make)
Laravex.Events Event dispatcher and cache
Laravex.Queue Queue worker
Laravex.Broadcasting Broadcasting channel and broadcaster
Laravex.Cache Cache manager (array/file/database stores)
Laravex.Auth Guard, policy, password reset
Laravex.Hashing PBKDF2 hashing
Laravex.Encryption AES-GCM encryption
Laravex.Mail Mailer
Laravex.Filesystem Storage (local disk)
Laravex.Support Arr, Str, Collection, Faker, Helpers, JSON
Laravex.Log Logger
Laravex.Validation Request validation
Laravex.View Blade-style template renderer
Laravex.Notifications Notification channels
Laravex.Bus Command bus (chain/batch)
Laravex.Generators make:* Artisan generators

No lib/my_app_web/ — Laravex does not use Phoenix's web layer. Routes, controllers, and views all live in routes/, app/Http/Controllers/, and resources/views/ respectively.

public/

The public-facing entry point for HTTP requests and static assets (CSS, JS, images). The HTTP server serves files from public/ before routing to the application.

resources/

Uncompiled front-end assets and views:

  • resources/views/ — Blade-style .html.eex / .blade.ex templates rendered by Laravex.View.
  • resources/css/ — Stylesheet source files.
  • resources/js/ — JavaScript source files.

Asset bundling is configured via vite.config.js at the project root.

routes/

Route registration is split into focused modules:

File Module Purpose
routes/web.ex Routes.Web Browser routes with session/CSRF middleware
routes/console.ex Routes.Console Artisan closure commands
routes/api.ex Routes.Api API routes (added by ./artisan install:api)
routes/auth.ex Routes.Auth Auth scaffolding routes (added by ./artisan install:starter-kit)

storage/

Runtime-generated files. The framework writes to storage/framework/ for sessions, cache, and compiled views. Logs go to storage/logs/. User-uploaded files go to storage/app/.

The storage/framework/down file controls Configuration#maintenance-mode.

tests/

Mirrors Laravel's tests/ layout:

  • tests/Feature/ — Integration tests that exercise the full HTTP stack.
  • tests/Unit/ — Unit tests for individual modules.

The base tests/test_case.ex provides helpers equivalent to Laravel's TestCase. Run all tests with:

mix test

artisan

The CLI entry point. Running ./artisan <command> delegates to Mix tasks under lib/mix/tasks/artisan.ex. See Artisan-Console for the full command reference.

Clone this wiki locally