IDEA Extended
This commit is contained in:
Jakub Zych
248
.planning/codebase/STRUCTURE.md
Normal file
248
.planning/codebase/STRUCTURE.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# 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
Block a user