Project Structure

One of the easiest ways to become comfortable with the Quantum PHP Framework is to understand how a real project is organized.

This page is based on the current quantum/project application skeleton, not a generic framework guess. The goal is to help readers build a practical understanding of the folders they will actually see in a new project.

A high-level view

A typical Quantum PHP Framework project is organized around a few core areas:

  • modules/ for feature-oriented application modules
  • shared/ for cross-module configuration, services, commands, and shared resources
  • public/ for the web entry point and public assets
  • cache/ for runtime cache data
  • logs/ for application log output
  • migrations/ for database migrations
  • tests/ for automated tests
  • qt for command-line framework usage

This structure helps keep feature modules, shared application logic, the public web layer, and supporting resources clearly separated.

A practical folder map

The easiest way to understand the skeleton is to look at it as a small set of important root areas instead of a long flat directory list.

project-root/
|-- modules/               Feature-oriented modules such as Web, Api, or your own app modules
|   |-- Api/
|   |-- Web/
|   `-- ...
|
|-- shared/                Cross-module code and shared resources
|   |-- Commands/
|   |-- config/
|   |-- DTOs/
|   |-- emails/
|   |-- Enums/
|   |-- Models/
|   |-- resources/
|   |-- Services/
|   |-- store/
|   |-- Transformers/
|   `-- views/
|
|-- public/                Web root
|   |-- assets/
|   |-- uploads/
|   `-- index.php
|
|-- cache/                 Runtime cache data
|-- logs/                  Application logs
|-- migrations/            Database migrations
|-- tests/                 Unit and feature tests
|-- helpers/               Optional project helpers
|-- hooks/                 Optional hook/event extensions
|-- libraries/             Optional custom library-style code
|-- qt                     CLI entrypoint
|-- composer.json
`-- .env / .env.example

If you only remember one thing, remember this:

  • modules/ is where feature/application structure lives
  • shared/ is where cross-module project code lives
  • public/ is what the web server exposes

Main folders in the project skeleton

public/

This is the public web root of the application.

Notable contents include:

public/index.php

This file is the main web entry point. It serves as a thin handoff to the framework's core bootstrap logic.

require dirname(__DIR__) . '/vendor/autoload.php';

use Quantum\App\Factories\AppFactory;
use Quantum\App\Enums\AppType;

if (!defined('DS')) {
    define('DS', DIRECTORY_SEPARATOR);
}

AppFactory::create(AppType::WEB, dirname(__DIR__))->start();

It is important to note that this file is not where request lifecycle logic lives; that is handled within AppFactory and the WebAppAdapter.

  • public/assets/ for publicly served assets
  • public/uploads/ for uploaded files
  • public/.htaccess for Apache-style web server configuration

If you are deploying a standard web application, this is the folder that will usually be exposed by the web server.

shared/

This is one of the most important directories in the project. It contains shared application logic and framework-facing configuration.

In the current project skeleton, it includes areas such as:

  • shared/config/ for application configuration
  • shared/Commands/ for CLI command classes
  • shared/Models/ for application models
  • shared/Services/ for service-layer logic
  • shared/DTOs/ for data transfer objects
  • shared/Enums/ for enum definitions
  • shared/Transformers/ for transformation logic
  • shared/views/ for shared views
  • shared/resources/ for shared resources such as language files
  • shared/emails/ for email-related assets
  • shared/store/ for storage-related project data

If you are trying to understand the core behavior of a project, this is one of the first places to study.

modules/

This is one of the most important parts of a real Quantum project and should be treated as first-class project structure, not as an advanced afterthought.

Modules are feature-oriented application units. In practice, that means a module can own:

  • controllers
  • middlewares
  • views
  • routes
  • services
  • resources
  • API or web surface for a bounded application area

In the current starter project, this includes modules such as:

  • Web
  • Api

Those names matter because they represent the modules that are actually installed in a fresh starter project today.

That is different from the module generator templates documented elsewhere. Templates such as DemoWeb, DemoApi, or Toolkit are available for scaffolding, but they are not the default root module names in the current starter skeleton.

This matters because a Quantum application is not organized only around one giant shared/ area. It is organized around:

  • feature modules in modules/
  • shared cross-module support code in shared/

That split is one of the most useful mental models to learn early.

migrations/

This folder contains database migration files.

In the current skeleton, it already includes example migration files such as:

  • create_table_users_...php
  • create_table_posts_...php
  • create_table_comments_...php

This gives a good early hint that the starter project is designed to demonstrate real application structure, not just a nearly empty shell.

cache/

This folder stores runtime cache data created by the project.

In the current starter project, it exists from the beginning so cache-backed framework features already have a conventional location to write into during local development.

logs/

This folder stores application log output.

Having it present in the starter skeleton makes it easier to see that local logging is part of the normal project shape, not an afterthought added later.

tests/

This folder contains automated tests.

The current skeleton includes:

  • tests/Feature/ for feature-level tests
  • tests/Unit/ for unit tests
  • tests/Helpers/ for test helpers
  • tests/bootstrap.php for test bootstrap logic
  • tests/_root/ for test support fixtures and environment scaffolding

This is useful because it shows that testing is part of the project structure from the start.

helpers/

This folder contains shared helper functions.

In the current skeleton, it includes:

  • helpers/functions.php

This is typically where reusable procedural helpers can live when they do not naturally belong in a service or class.

hooks/

The skeleton includes a hooks/ directory, currently kept alive with a .gitkeep file.

This suggests the framework/project layout reserves a place for hook-based extensions or related project behavior, even if the demo project does not actively use it yet.

libraries/

The project also includes a libraries/ directory, currently empty except for .gitkeep.

This gives you a dedicated place for custom library-style code that does not fit cleanly into other project areas.

Important root files

A few root-level files are worth recognizing early:

  • composer.json for project dependencies and package metadata
  • .env and .env.example for environment setup
  • .env.example for environment setup guidance
  • qt for command-line framework operations
  • phpunit.xml for testing configuration
  • LICENSE, .gitignore, and CI-related files for project maintenance

A useful way to think about it

If you are new to the framework, this simplified model is enough to get started:

  • modules/ = where feature/application surfaces live
  • shared/ = where cross-module code and config live
  • public/ = what the web server sees
  • cache/ = runtime cache files
  • logs/ = application logs
  • migrations/ = database schema changes
  • tests/ = automated test coverage
  • qt = command-line entry for framework tooling

Once this mental map is clear, it becomes much easier to understand the next layers of the framework.

What is not covered here yet

This page explains the project layout at a structural level, but it does not yet explain:

  • how routing is configured
  • how controllers are organized in practice
  • how views are rendered
  • how modules are structured internally when used in a larger application

Those topics should be covered in their own dedicated pages.

After this page, the best next topics are: