# Codebase Structure **Analysis Date:** 2026-02-04 ## Directory Layout ``` golem15-wintercms-starter/ # WinterCMS reference implementation ├── bootstrap/ # Application bootstrap │ ├── app.php # Creates Laravel Application instance │ ├── autoload.php # Composer autoloader │ └── cache/ # Cached bootstrap files ├── modules/ # Core framework modules (not plugins) │ ├── system/ # Core system functionality │ ├── backend/ # Admin interface module │ └── cms/ # Frontend CMS module ├── plugins/ # Plugin directory (git submodules) │ ├── winter/ # Official Winter plugins │ │ ├── pages/ # Pages plugin │ │ ├── blocks/ # Content blocks plugin │ │ ├── debugbar/ # Debug toolbar │ │ └── ... │ └── golem15/ # Golem15 custom plugins (19 total) │ ├── apparatus/ # Foundation framework/DI │ ├── user/ # Enhanced user auth + JWT │ ├── paymentgateway/ # Payment processing │ ├── blog/ # Blog system │ ├── translate/ # Multilingual support │ ├── ai/ # AI integration │ ├── chat/ # Real-time chat │ └── ... ├── themes/ # Static themes │ └── demo/ # Demo theme │ ├── pages/ # CMS pages (.htm files) │ ├── layouts/ # Page layouts │ ├── partials/ # Reusable partials │ └── assets/ # CSS, JS, images ├── storage/ # Application storage │ ├── logs/ # Log files │ ├── framework/ # Framework cache/sessions/views │ │ ├── sessions/ # User sessions │ │ ├── views/ # Compiled Twig views │ │ └── cache/ # Application cache │ ├── temp/ # Temporary files │ ├── cms/ # CMS-specific cache │ └── app/ # Application uploads │ ├── media/ # Media files │ ├── uploads/ # User uploads │ └── resized/ # Resized images ├── config/ # Application configuration │ ├── app.php # Application config │ ├── cms.php # CMS config │ ├── database.php # Database config │ ├── dev/ # Development overrides │ └── testing/ # Testing overrides ├── index.php # Application entry point ├── artisan # Artisan CLI script └── composer.json # Project dependencies ``` ## Directory Purposes **bootstrap/:** - Purpose: Application initialization and container setup - Contains: App instance creation, autoloader configuration - Key files: `bootstrap/app.php` (creates Winter\Storm\Foundation\Application), `bootstrap/autoload.php` (loads Composer) **modules/system/:** - Purpose: Core framework functionality shared by all modules - Contains: PluginBase, PluginManager, MailManager, ErrorHandler, UpdateManager, VersionManager, ImageResizer - Structure: `classes/`, `models/`, `controllers/`, `database/`, `console/`, `lang/`, `tests/` - Key classes: `System\Classes\PluginBase`, `System\Classes\PluginManager` **modules/backend/:** - Purpose: Admin interface and CRUD backend - Contains: Admin controllers, form/list widgets, user role management, behaviors - Structure: `classes/`, `behaviors/`, `models/`, `controllers/`, `widgets/`, `formwidgets/`, `views/` - Key classes: `Backend\Classes\BackendController`, `Backend\Classes\Controller`, `Backend\Behaviors\FormController` **modules/cms/:** - Purpose: Frontend CMS - page rendering, theming, components - Contains: Page/Layout/Component managers, theme management, frontend controllers - Structure: `classes/`, `components/`, `models/`, `controllers/`, `formwidgets/`, `views/` - Key classes: `Cms\Classes\Controller`, `Cms\Classes\Page`, `Cms\Classes\Layout`, `Cms\Classes\ComponentManager` **plugins/winter/ & plugins/golem15/:** - Purpose: Modular plugin features registered as Laravel ServiceProviders - Each plugin contains: `Plugin.php` (entry point), `controllers/`, `models/`, `components/`, `updates/` (migrations), `lang/` - Plugin.php declares: name, description, author, dependencies ($require), registered components/controllers **themes/demo/:** - Purpose: Static theme files - pages, layouts, and assets - pages/: CMS pages (URL → page mapping) - layouts/: Page layout templates with `{% component %}` tags - partials/: Reusable Twig templates - assets/: CSS, JavaScript, images **storage/:** - Purpose: Runtime data, caches, and uploads - logs/: Application logs (Laravel.log, system errors) - framework/sessions/: User session data - framework/views/: Compiled Twig templates - cms/cache/: CMS-specific caches - app/uploads/: User-uploaded files - app/media/: Media library files **config/:** - Purpose: Application configuration files - app.php: Laravel application settings (logging, cache, etc.) - cms.php: CMS-specific settings (backend URI, theme path, etc.) - database.php: Database connection configuration - dev/: Development environment overrides ## Key File Locations **Entry Points:** - `golem15-wintercms-starter/index.php`: HTTP entry point - loads bootstrap and runs kernel - `golem15-wintercms-starter/artisan`: CLI entry point - loads kernel and console handler - `golem15-wintercms-starter/bootstrap/app.php`: Creates application container - `golem15-wintercms-starter/bootstrap/autoload.php`: Loads Composer autoloader **Core Framework Classes:** - `golem15-wintercms-starter/modules/system/classes/PluginBase.php`: Base class for all plugins - `golem15-wintercms-starter/modules/system/classes/PluginManager.php`: Discovers and loads plugins - `golem15-wintercms-starter/modules/cms/classes/CmsController.php`: Frontend HTTP controller - `golem15-wintercms-starter/modules/cms/classes/Controller.php`: Frontend business logic controller - `golem15-wintercms-starter/modules/backend/classes/BackendController.php`: Backend HTTP controller - `golem15-wintercms-starter/modules/backend/classes/Controller.php`: Backend business logic **Theme System:** - `golem15-wintercms-starter/modules/cms/classes/Theme.php`: Theme loader and manager - `golem15-wintercms-starter/modules/cms/classes/Page.php`: CMS page object - `golem15-wintercms-starter/modules/cms/classes/Layout.php`: Layout template object - `golem15-wintercms-starter/modules/cms/classes/ComponentManager.php`: Component registry **Backend Behaviors:** - `golem15-wintercms-starter/modules/backend/behaviors/FormController.php`: Form CRUD behavior - `golem15-wintercms-starter/modules/backend/behaviors/ListController.php`: List/table behavior - `golem15-wintercms-starter/modules/backend/behaviors/RelationController.php`: Relation management - `golem15-wintercms-starter/modules/backend/behaviors/ImportExportController.php`: Import/export **Routing:** - `golem15-wintercms-starter/modules/cms/routes.php`: Frontend CMS routes - `golem15-wintercms-starter/modules/backend/routes.php`: Backend admin routes - `golem15-wintercms-starter/modules/system/routes.php`: System routes **Models:** - `golem15-wintercms-starter/modules/system/models/Parameter.php`: Application parameters/settings - `golem15-wintercms-starter/modules/system/models/MailTemplate.php`: Email templates - `golem15-wintercms-starter/modules/system/models/EventLog.php`: Event logging ## Naming Conventions **Files:** - Controllers: CamelCase, singular (e.g., `Posts.php`, `Categories.php` in `plugins/*/controllers/`) - Models: CamelCase, singular (e.g., `Post.php`, `Category.php` in `plugins/*/models/`) - Components: CamelCase (e.g., `SearchBox.php`, `ProductCard.php` in `plugins/*/components/`) - Views/Templates: snake_case with underscores for layout/partial files (e.g., `_toolbar.php`, `_list.php`) - Behaviors: CamelCase with "Controller" suffix (e.g., `FormController.php`, `ListController.php`) - Plugins: lowercase with namespace (e.g., `winter`, `golem15`) **Directories:** - Module names: lowercase (system, cms, backend) - Plugin vendor: lowercase (winter, golem15) - Plugin names: lowercase (blog, user, apparatus) - Class directories: lowercase plural (classes/, models/, controllers/, components/, views/, widgets/) **Classes and Namespaces:** - All classes namespaced by module/plugin (e.g., `System\Classes\PluginBase`, `Cms\Classes\Page`, `Golem15\User\Models\User`) - Plugins follow vendor\plugin pattern (e.g., `Golem15\Blog\Controllers\Posts`) - Model classes singular (User, Post, Category) - Manager classes suffix "Manager" (ComponentManager, ThemeManager) - Controllers suffix "Controller" (BackendController, PostsController) ## Where to Add New Code **New Plugin Feature (new controller, model, component):** - Primary code: `plugins/golem15/{pluginname}/{models,controllers,components}/` - Database schema: `plugins/golem15/{pluginname}/updates/` (migration files) - Forms/lists config: `plugins/golem15/{pluginname}/models/{ModelName}/fields.yaml`, `columns.yaml` - Views/templates: `plugins/golem15/{pluginname}/controllers/{ControllerName}/` (for backend views) - Plugin entry: `plugins/golem15/{pluginname}/Plugin.php` (declare plugin, register components/controllers) **New Frontend Component:** - Implementation: `plugins/golem15/{pluginname}/components/{ComponentName}.php` (extends ComponentBase) - Partial template: `plugins/golem15/{pluginname}/components/{componentname}/default.htm` - Register in Plugin.php: `registerComponents()` returns [ClassName => 'code'] - Use on page: `{% component 'componentCode' %}` in page/layout Twig **New Backend CRUD Page:** - Controller: `plugins/golem15/{pluginname}/controllers/{ModelName}.php` (extends Backend\Classes\Controller) - Model: `plugins/golem15/{pluginname}/models/{ModelName}.php` (extends Winter\Storm\Database\Model) - Forms: `plugins/golem15/{pluginname}/models/{modelname}/fields.yaml` - Lists: `plugins/golem15/{pluginname}/models/{modelname}/columns.yaml` - Views: `plugins/golem15/{pluginname}/controllers/{modelname}/{create,update,preview}.php` - Register in Plugin.php: `registerControllers()` returns [ClassName => 'controller'] **Utilities/Helpers:** - Shared service classes: `plugins/golem15/{pluginname}/classes/` - Traits (shared behavior): `modules/{module}/traits/` or `plugins/{vendor}/{plugin}/traits/` - Helper functions: `plugins/golem15/{pluginname}/helpers.php` (loaded in Plugin.php) **Configuration:** - Plugin config: `plugins/golem15/{pluginname}/config/{name}.php` (published to app config/) - Backend form widget: `plugins/golem15/{pluginname}/formwidgets/` - Report widget: `plugins/golem15/{pluginname}/reportwidgets/` ## Special Directories **storage/logs/:** - Purpose: Application logging - Generated: Yes (created at runtime) - Committed: No (ignored in .gitignore) - Contains: `laravel.log`, debug logs, error traces **storage/framework/:** - Purpose: Framework caches, sessions, compiled views - Generated: Yes (created at runtime) - Committed: No (ignored in .gitignore) - Subdirectories: `sessions/`, `views/`, `cache/` **storage/temp/ & storage/cms/cache/:** - Purpose: Temporary files, CMS compilation caches - Generated: Yes (created at runtime) - Committed: No (ignored) - Contents: Compiled page cache, asset combiner output **plugins/ (submodules):** - Purpose: Git submodules for independent version control - Generated: No (checked in as submodule references) - Committed: References only (actual plugin code in separate repos) - Update: `git submodule update --remote --merge` or `./scripts/update-submodules.sh` **bootstrap/cache/:** - Purpose: Cached container, routes, config - Generated: Yes (`php artisan config:cache`, `php artisan route:cache`) - Committed: No (ignored) - Clear: `php artisan cache:clear` **config/dev/ & config/testing/:** - Purpose: Environment-specific config overrides - Generated: No (committed) - Committed: Yes (development/testing defaults) - Used: In dev and testing environments via `.env` --- *Structure analysis: 2026-02-04*