Directory Structure
What lives where inside VelvetCMS Core and why.
VelvetCMS keeps HTTP, CLI, content, and theme concerns in predictable top-level directories. The framework favors explicit organization so you can reason about deploys and module boundaries quickly.
Top level #
| Path | Purpose | Key files |
|---|---|---|
bootstrap/ |
Shared bootstrap that creates the Application container. |
bootstrap/app.php |
config/ |
PHP arrays that drive every service. Cached via config:cache. |
app.php, content.php, theme.php, modules.php, … |
content/ |
Markdown pages (default store). Drivers resolve via content_path(). |
content/pages/welcome.md |
database/ |
SQL migrations + seeds. | database/migrations/*.sql |
public/ |
Front controller + public assets. Serves as web root. | public/index.php |
routes/ |
Route definition closures, cacheable. | routes/web.php |
src/ |
All framework code. Namespaces map 1:1 via Composer PSR‑4. | src/Core, src/Commands, src/Http, … |
storage/ |
Cache, logs, sessions, compiled module manifests. | storage/cache, storage/modules-compiled.json |
themes/ |
Theme folders with .velvet.php templates and assets. |
themes/default/layouts/default.velvet.php |
velvet |
CLI entry script registered as Composer bin. | invokes VelvetCMS\Commands\CommandRegistry |
Inside src/ #
Core/– Container, router, event dispatcher, modules, config repository, version registry.Commands/– Base command plus feature-specific commands; structured in subfolders (Cache, Config, Module, Page, Route).Contracts/– Interfaces for content drivers, cache drivers, migration runner, and modules.Drivers/– Concrete implementations (cache + content drivers).Http/– Request/response objects, middleware pipeline, CSRF + error middleware.Services/– High-level services exposed via the container (PageService, ThemeService, MarkdownService, TemplateEngine, SessionManager, FileLogger).Support/– Helper functions and cache tag manager.Database/– Connection wrapper, fluentQueryBuilder,Collection, migration runner.Exceptions/– Central exception handler, interfaces, HTTP exceptions.Facades/– Thin static facades forApp,DB,Session.
Storage layout #
storage/
├── cache/ # Config cache, route cache, template cache, file driver index
├── logs/velvet.log # FileLogger output
├── sessions/ # Native PHP sessions (if file driver)
├── modules.json # Enabled/disabled module state
├── modules-compiled.json # Output from module:compile (load order + metadata)
└── modules-autoload.php # PSR-4 mappings generated from module composer files
Content + theme conventions #
- Markdown files live in
content/pages/{slug}.mdwith YAML frontmatter.content_path()resolves this base path and is configurable throughconfig/content.php. - Themes reside in
themes/{name}. Each theme needslayouts/,partials/,blocks/, andassets/. Templates end with.velvet.phpand are compiled/cached instorage/cache/templates.
Keep project-specific modules in modules/ or any path listed in config/modules.php. module:compile walks those directories (plus glob patterns like ../VelvetCMS-*) before producing the compiled manifest.