# Project structure

Below is a map of the directories and what each is responsible for. Understanding this structure is half the battle when working on the engine.

```
core/        CMS core (framework, domain-agnostic)
modules/     Built-in CMS modules
plugins/     Plugins (extensions)
templates/   Themes (appearance)
public/      Public static files (served directly by nginx)
storage/     Transient data (cache, logs, uploads, sessions)
config/      Configuration (app.php, database.php, cache.php)
bin/         CLI commands (bin/celena)
index.php    Front entry point
admin.php    Admin entry point
install.php  Install wizard
.env         Environment (DB credentials, keys)
```

## core/ — the core

| Folder/file | Purpose |
|-------------|---------|
| `Autoloader.php` | PSR-4 autoloader |
| `Kernel.php` | App bootstrap, container, services |
| `Container.php` | DI container (reflection-based auto-resolution) |
| `Config.php` | Loads `.env` and `config/*.php` files |
| `Http/` | `Router`, `Request`, `Response`, middleware |
| `Database/` | `Connection`, `QueryBuilder`, `Schema`, `Blueprint`, `MigrationRunner` |
| `Template/` | `Engine`, `Compiler`, `TagRegistry`, template tags |
| `Plugin/` | `Hook`, `PluginManager`, `Installer`, `Marketplace` |
| `Security/` | `Auth`, `Csrf`, `Permission`, `Filter`, `RateLimiter` |
| `I18n/` | `Locale`, `Translator` |
| `Support/` | utilities (`Markdown` etc.) |
| `Mail/`, `Queue/`, `Cache/`, `Ai/` | mail, queue, cache, AI integration |

## modules/ — built-in modules

The CMS's base functionality. Each module is a folder under `modules/` with controllers in the `Celena\Module\<Name>\` namespace.

`AdminBase`, `Dashboard`, `Users`, `Pages`, `News`, `Categories`, `Media`, `Menus`, `Comments`, `CustomFields`, `Settings`, `Plugins`, `Seo`, `Search`, `Translations`, `Account`, `Webhooks`, `Banners`, `Docs`, `Ai`, `Cities`.

## plugins/ — plugins

Extensions you can enable/disable. The structure of one plugin:

```
plugins/<slug>/
├── manifest.json     metadata (required)
├── plugin.php        entry point: routes, hooks, tags (required)
├── src/              PHP classes (PSR-4 Celena\Plugin\<Slug>\)
├── migrations/       DB migrations
├── templates/        plugin .tpl (admin and front)
├── languages/        translations ru.json/en.json/…
├── assets/           CSS/JS → copied to public/assets/plugins/<slug>/
└── docs/             plugin Markdown documentation
```

Details — [Building a plugin](/docs/code/plugin-create).

## templates/ — themes

Each theme is a folder with `theme.json` and a set of `.tpl` files. The active theme is stored in the `theme` option. On celena.io the active theme is `celena-agency`. Details — [Creating a theme](/docs/code/theme).

## public/ — public static files

`nginx` serves these files directly, bypassing PHP:

```
public/assets/
├── admin/      admin CSS/JS
├── runtime/    shared front-end (celena.js, celena.css)
└── plugins/<slug>/   plugin assets (auto-copied from plugins/<slug>/assets/)
```

## storage/ — transient data

```
storage/
├── cache/tpl/    compiled templates (.php)
├── cache/data/   data cache, rate-limit
├── logs/         logs
├── uploads/      uploaded files
└── sessions/     session files
```

> `storage/` lives outside the publicly served path — its contents are not served directly.

## config/ and .env

- `config/app.php` — name, environment, locale, sessions.
- `config/database.php` — connection parameters (read from `.env`).
- `config/cache.php` — cache driver.
- `.env` — secrets for a specific installation (NOT in the repository): DB credentials, API keys. Locally — PostgreSQL, in production — MySQL; the code is cross-database.
