Anatomy & Folder Structure

Blueprint vs Installed App

There are two ways to start: from a blueprint template, or by installing the Kernel into a fresh folder yourself. Both end up with the same shape — the blueprints just come pre-filled with a sensible starting set of files and capabilities.

Either way, the Kernel itself lives in kernel/ at your project root. It's self-contained, so you can read its source, upgrade it, or fork it. Everything else in your root is your project — your app folder, your capabilities and modules, your config, and your storage.

Root Files

A handful of files sit at the very top of your project. They're the front doors.

config/

Simple PHP files that return arrays. The Kernel reads any file in here by name — config('registry') maps to config/registry.php, and so on.

Which config files you have depends on which capabilities you've installed. Each capability contributes its own config file. A fresh app typically starts with things like:

config/
├── forge_router.php   # routes / middleware groups (ForgeRouter)
├── middleware.php     # registered middleware
└── registry.php       # package / source registry

Config here is your app's opinion. The Kernel just loads whatever array the file returns and hands it to you through the config() helper.

app/, modules/ & capabilities/

These are the three folders where your code lives. They differ by what they hold and by namespace, not by how the Kernel treats them. The folders and their namespaces below are the defaults — every one of them can be changed (see Customizing Folder Structure). If you customize, keep this section in mind: your layout follows whatever you configure.

All of the above are configurable: app_root/app_namespace rename app/ and App\; modules_root/modules_namespace rename modules/, capabilities/, and their Modules\/Capability\ namespaces. The Kernel resolves folders and namespaces from this configuration, so routing, discovery, and generation all follow what you set.

Inside app/, folders follow your forge_structure.php defaults — Controllers, Http, Services, Listeners, Models, Events, Database/Migrations, UI/views, and so on.

One of these paths deserves its own note: the injectable folders. This is where classes are automatically discovered and registered by the container so they can be injected into your code. The default names — Services and Listeners in your app, src/Services, src/Listeners and src/Providers in a module — are really just the default folder names for that injectable path. Services was the older name for this concept; the kernel now calls it injectable because that's what the folder actually does, but the folder can still be called Services (the default) if you prefer. It's a naming and semantics thing, not a hard rule.

Discovery doesn't care what the folder is called — it reads the injectable paths from your forge_structure.php and scans whatever folders those point to. So you can rename them, split them, or point the path somewhere else entirely, and the container will find your classes there instead. See Customizing Folder Structure.

Each module or capability holds its own src/ folder with the same internal layout, plus an entry file like ForgeHtmxModule.php in src/ that announces the module.

capabilities/ForgeHtmx/
└── src/
    ├── ForgeHtmxModule.php   # the module's entry file
    ├── Middlewares/
    ├── Traits/
    └── UI/assets/

The Kernel looks for an entry file matching *Module.php (or {Name}.php) inside each module's src/ folder. That's what tells it a folder is a module at all.

storage/

Generated content that should never be committed to version control. The Kernel makes sure these folders exist at every boot:

storage/
├── sessions/      # session data
├── logs/          # application logs
├── database/      # sqlite databases (cache, app, security…)
├── framework/     # cache, compiled hooks, cron, trusted sources
├── app/           # user uploads (images, media)
├── bin/           # runtime binaries
└── queues/        # queue workers & output

Inside storage/framework/ you'll find the Autoloader's class map cache, compiled lifecycle hooks, cron job state, and trusted_sources.json — the list of package sources the package manager trusts.

You generally never touch storage/ by hand. If a folder is missing, the Kernel recreates it the next time it boots.

public/

The only folder your web server should serve directly. This is your app's web root.

public/
├── index.php       # the web entry point
├── storage/        # symlinked public assets
├── assets/         # compiled css / js
└── favicon.ico

public/index.php is the real front door for web requests. It defines the base path, registers the Autoloader, checks for a maintenance page, and then hands off to the Kernel — Kernel::init(). The details of that path are on the Lifecycle page.

The index.php at your project root is a deliberate dead-end that returns 403, so directory browsing or direct hits on the root can't serve anything sensitive.

Customizing Folder Structure & Namespaces

Every default on this page — where app/ lives, what root folders hold modules, and even the namespaces — comes from one place: the Kernel's internal structure file. You can override any of it without touching the Kernel.

You don't have to write that file by hand. Use the wizard:

php forge.php structure:init   # generates forge_structure.php at your project root
php forge.php structure:info   # interactively view your current config

The wizard asks what you want to customize and offers you a few choices:

• Full structure — everything at once.
• App structure only — app root, namespace, and per-type paths.
• Modules structure only — module roots, namespaces, entry files.
• Partial — pick just the entries you care about.
• Roots & namespaces only — e.g. where modules/ and capabilities/ live and what their namespaces are.

If a forge_structure.php already exists the wizard will ask whether to overwrite it or merge your new choices into it. If you'd rather write it by hand, create forge_structure.php at your project root — it's just a PHP file that returns an array. The wizard generates the same file, so the two paths are equivalent.

<?php

return [
    'app_root' => 'app',
    'app_namespace' => 'App',
    'modules_root' => ['modules', 'capabilities'],
    'modules_namespace' => ['Modules', 'Capability'],
    'app' => [
        'controllers' => 'Controllers',
        'injectable' => ['Services', 'Listeners'],
        'models' => 'Models',
        'views' => 'UI/views',
    ],
    'modules' => [
        'controllers' => 'src/Controllers',
        'injectable' => ['src/Services', 'src/Listeners', 'src/Providers'],
        'models' => 'src/Models',
        'views' => 'src/UI/views',
    ],
];

Any key you set is merged over the Kernel's defaults — you only need to list what you're changing. The full list of keys mirrors the defaults shown elsewhere on this page: app_root, app_namespace, modules_root, modules_namespace, module_entry_files, plus per-type paths for app and modules (controllers, views, models, migrations, injectable, and more).

Two more things worth knowing:

• Modules can opt out. A module or capability can pin down its own internal structure with a #[Structure(structure: [...])] attribute on its module class. Those are sovereign — your project-level forge_structure.php doesn't touch them.
• Per-capability details live in that capability's page. If a capability documents custom layout, it's on its own page, not repeated here.

When in doubt, run structure:info — it shows your app structure, your modules, and whether a user-defined file is active, all interactively.

forge-lock.json

Where forge.json says what you want, forge-lock.json records exactly what the package manager installed. For every module it stores the pinned version, the source (registry, git, or URL), and an integrity hash.

That integrity hash is what keeps installs reproducible and tamper-evident — the same module version resolves to the same verified content. Commit this file. It's the record that makes your build stable.

The package manager uses this file to know what's actually on disk, and the lock can be regenerated from your forge.json requirements.