golem15/summercms-initial-research
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7a8cad206098d259600b66bf3a991f6dc8b097f7
summercms-initial-research/.planning/codebase/STRUCTURE.md
Jakub Zych d8a4a4555c IDEA Extended
2026-02-04 01:06:15 +01:00

13 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink