IDEA Extended
This commit is contained in:
Jakub Zych
231
.planning/codebase/ARCHITECTURE.md
Normal file
231
.planning/codebase/ARCHITECTURE.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# Architecture
|
||||
|
||||
**Analysis Date:** 2026-02-04
|
||||
|
||||
## Pattern Overview
|
||||
|
||||
**Overall:** Modular Layer-based MVC with Plugin System
|
||||
|
||||
WinterCMS implements a **three-layer modular architecture** consisting of Core Modules (System, Backend, CMS) that form the framework foundation, with a Plugin system overlaid for extensibility. The framework uses Laravel 9.x as its base, with Winter's Storm library acting as a compatibility buffer.
|
||||
|
||||
**Key Characteristics:**
|
||||
- Laravel-based HTTP kernel with module-level routing
|
||||
- CMS-first approach: frontend pages route through CMS module, backend admin routes through Backend module
|
||||
- Plugin dependency resolution with automatic component/controller/model discovery
|
||||
- Extensibility through plugin interdependencies and event-driven architecture
|
||||
- YAML/JSON configuration for models, forms, lists, and behaviors
|
||||
- Static theme system with file-based page, layout, and partial management
|
||||
|
||||
## Layers
|
||||
|
||||
**Core Modules (modules/ directory):**
|
||||
- **System Module:** Base framework, plugin management, mail system, asset handling, error management
|
||||
- **Backend Module:** Admin interface, form/list widgets, user role management, controller behaviors
|
||||
- **CMS Module:** Frontend page rendering, theme management, component system, layout composition
|
||||
|
||||
**Plugin Layer (plugins/ directory):**
|
||||
- Vendor-namespaced plugins (winter/, golem15/)
|
||||
- Each plugin extends and integrates with core modules
|
||||
- Plugin dependencies declared via `$require` arrays in Plugin.php
|
||||
- Core plugins: Apparatus (DI/scenarios), User (auth), PaymentGateway (commerce)
|
||||
- Domain plugins: Blog, Menu, Translate, AI, Chat, etc.
|
||||
|
||||
**Frontend/Theme Layer (themes/ directory):**
|
||||
- Static theme files organized in theme directories
|
||||
- Pages, layouts, partials stored as .htm files with Twig syntax
|
||||
- Assets (CSS, JS, images) co-located with pages/layouts
|
||||
- URL routing to pages via Theme manager and CMS controller
|
||||
|
||||
## Data Flow
|
||||
|
||||
**Frontend Request (Page View):**
|
||||
|
||||
1. HTTP request to any URL arrives at `index.php`
|
||||
2. Bootstrap loads application (`bootstrap/app.php`)
|
||||
3. HTTP Kernel processes request through middleware
|
||||
4. Laravel Router evaluates all registered routes
|
||||
5. Backend/System routes handled by their controllers
|
||||
6. CMS module catch-all route `{slug?}` routes to `Cms\Classes\CmsController@run()`
|
||||
7. CMS Controller delegates to `Cms\Classes\Controller` (primary frontend controller)
|
||||
8. Primary Controller:
|
||||
- Looks up URL in Theme using `Cms\Classes\Router`
|
||||
- Resolves Page, Layout, and Component objects from theme files
|
||||
- Renders page through Twig template engine
|
||||
- Components injected into page output via ComponentManager
|
||||
9. Response sent back to client
|
||||
|
||||
**Backend Request (Admin Interface):**
|
||||
|
||||
1. HTTP request to `/backend/...` arrives
|
||||
2. Backend Router matches `Backend\Classes\BackendController@run()`
|
||||
3. BackendController parses remaining URL segments to determine target plugin/controller
|
||||
4. Controller loaded from plugin (e.g., `Golem15\Blog\Controllers\Posts`)
|
||||
5. Controller action determined by remaining URL parts
|
||||
6. Behaviors attached (FormController, ListController, etc.) handle CRUD operations
|
||||
7. Views rendered with form/list widgets
|
||||
8. JSON/HTML response returned
|
||||
|
||||
**Component Lifecycle:**
|
||||
|
||||
1. Page YAML/Twig specifies component code (`{% component 'componentName' %}`)
|
||||
2. ComponentManager resolves code to fully-qualified class name via codeMap
|
||||
3. Component class instantiated with properties from page markup
|
||||
4. Component's `onRun()` method called by page renderer
|
||||
5. Component renders its partial template (HTM file) in page context
|
||||
6. AJAX handlers on component (e.g., `onUpdateCart`) handled by Snowboard framework
|
||||
|
||||
**State Management:**
|
||||
|
||||
- Models: Database-backed via Winter\Storm\Database\Model (extends Laravel Eloquent)
|
||||
- Sessions: Laravel session middleware, stored in `storage/framework/sessions/`
|
||||
- Cache: Laravel cache (configurable drivers: file, redis, memcached)
|
||||
- Parameters: System\Models\Parameter table for application-level configuration
|
||||
- Translation: Text keys cached in parameters, loaded by Translate plugin
|
||||
|
||||
## Key Abstractions
|
||||
|
||||
**Plugin Architecture:**
|
||||
|
||||
Purpose: Enables modular, independently-deployable features with dependency resolution
|
||||
- Each plugin is a Laravel ServiceProvider extending `System\Classes\PluginBase`
|
||||
- Plugin.php declares: `pluginDetails()`, `register()`, `boot()`, `registerComponents()`, `registerControllers()`, etc.
|
||||
- Examples: `golem15-wintercms-starter/plugins/golem15/blog/Plugin.php`, `golem15-wintercms-starter/plugins/golem15/user/Plugin.php`
|
||||
- Pattern: Plugins register services, components, controllers, and extend existing models
|
||||
|
||||
**Component System:**
|
||||
|
||||
Purpose: Reusable, composable page elements with their own controllers and views
|
||||
- Components extend `Cms\Classes\ComponentBase`
|
||||
- Register in plugin via `registerComponents()` returning [ClassName => 'code']
|
||||
- ComponentManager loads all registered components into codeMap
|
||||
- Example: `golem15-wintercms-starter/modules/cms/components/SoftComponent.php`
|
||||
- Pattern: Component renders partial, handles AJAX, injects CSS/JS
|
||||
|
||||
**Theme/Page System:**
|
||||
|
||||
Purpose: File-based, non-database-backed content management
|
||||
- Theme directory contains pages/, layouts/, partials/ subdirectories
|
||||
- Page class `Cms\Classes\Page` extends `CmsCompoundObject` - represents page file as object
|
||||
- Page file format: URL metadata → YAML → Twig markup
|
||||
- Page references layout (inherited structure) and components (functional blocks)
|
||||
- Example page structure: `themes/demo/pages/home.htm`
|
||||
- Pattern: Page objects loaded on-demand from disk, cached in memory
|
||||
|
||||
**Backend Form/List System:**
|
||||
|
||||
Purpose: YAML-driven admin CRUD interfaces
|
||||
- Controllers use FormController and ListController behaviors
|
||||
- forms.yaml/fields.yaml define form structure and validation
|
||||
- lists.yaml/columns.yaml define table columns and filtering
|
||||
- FormController handles create/read/update/delete operations
|
||||
- Example files: `plugins/*/models/*/fields.yaml`, `plugins/*/models/*/columns.yaml`
|
||||
- Pattern: Behaviors parse YAML and generate HTML forms/tables dynamically
|
||||
|
||||
**Service Providers & Dependency Injection:**
|
||||
|
||||
Purpose: Central registration of services and extensibility hooks
|
||||
- Plugins register services in `register()` and `boot()` methods
|
||||
- Services bound to Laravel's DI container via `$this->app->singleton()`
|
||||
- Example: Apparatus framework registers DI container for component auto-wiring
|
||||
- Pattern: Late binding allows plugin A to extend plugin B's services
|
||||
|
||||
## Entry Points
|
||||
|
||||
**Frontend (CMS Page Serving):**
|
||||
|
||||
- Location: `golem15-wintercms-starter/modules/cms/classes/CmsController.php` (HTTP entry), `golem15-wintercms-starter/modules/cms/classes/Controller.php` (business logic)
|
||||
- Triggers: Any URL not matching backend or other routes
|
||||
- Responsibilities:
|
||||
- Routes URL to page via Theme manager
|
||||
- Loads Page, Layout, and Components
|
||||
- Renders through Twig with component injection
|
||||
- Returns HTML response
|
||||
|
||||
**Backend (Admin Interface):**
|
||||
|
||||
- Location: `golem15-wintercms-starter/modules/backend/classes/BackendController.php`
|
||||
- Triggers: URLs prefixed with `/backend/`
|
||||
- Responsibilities:
|
||||
- Parses plugin.controller.action URL pattern
|
||||
- Instantiates controller from plugin
|
||||
- Applies middleware and behaviors
|
||||
- Routes to controller action
|
||||
- Renders admin interface
|
||||
|
||||
**System Initialization:**
|
||||
|
||||
- Location: `golem15-wintercms-starter/bootstrap/app.php`, `golem15-wintercms-starter/index.php`
|
||||
- Triggers: Every HTTP request
|
||||
- Responsibilities:
|
||||
- Creates Laravel application instance
|
||||
- Binds kernel, console kernel, exception handler
|
||||
- Loads plugin manager and auto-discovers plugins
|
||||
- Registers module routes
|
||||
|
||||
**CLI Commands:**
|
||||
|
||||
- Location: `golem15-wintercms-starter/artisan` (entry point), `golem15-wintercms-starter/modules/*/console/` (command classes)
|
||||
- Triggers: `php artisan <command>`
|
||||
- Responsibilities:
|
||||
- Plugin scaffold commands
|
||||
- Database migrations
|
||||
- Asset management
|
||||
- Cache management
|
||||
- Payment gateway operations (via golem15/paymentgateway)
|
||||
|
||||
## Error Handling
|
||||
|
||||
**Strategy:** Exception-driven with error page rendering
|
||||
|
||||
**Patterns:**
|
||||
- All exceptions thrown as `SystemException`, `ApplicationException`, or Framework exceptions
|
||||
- HTTP exceptions converted to error pages by Exception Handler (`modules/system/classes/ErrorHandler.php`)
|
||||
- In production: Shows generic error page, logs details
|
||||
- In debug mode: Shows full stack trace and context
|
||||
- Model validation: Throws ApplicationException with validation messages
|
||||
- Frontend: 404 errors trigger Page not found response
|
||||
- Backend: 404 errors redirect to backend dashboard, show toast notifications
|
||||
|
||||
## Cross-Cutting Concerns
|
||||
|
||||
**Logging:**
|
||||
- Uses Laravel's log facade (`Log::info()`, `Log::error()`)
|
||||
- Stored in `storage/logs/`
|
||||
- Configured in `config/app.php` and environment variables
|
||||
- EventLog model (`modules/system/models/EventLog.php`) tracks application events
|
||||
- RequestLog model tracks HTTP requests for debugging
|
||||
|
||||
**Validation:**
|
||||
- Model-level via `$rules` property (Laravel validation rules)
|
||||
- Form widget validation via fields.yaml `validation` property
|
||||
- Backend behaviors apply validation before save
|
||||
- Errors returned as JSON validation responses in AJAX handlers
|
||||
|
||||
**Authentication:**
|
||||
- Winter Backend: Database-backed user with role-based access control
|
||||
- Frontend API: JWT tokens (via golem15/user plugin)
|
||||
- Middleware: `Backend\Middleware\AuthenticateBackend`, `User\Middleware\JwtAuth`
|
||||
- Guards: `web` (session-based), `api` (JWT)
|
||||
|
||||
## Extensibility Mechanisms
|
||||
|
||||
**Model Extension:**
|
||||
- Plugins extend models dynamically using `Model::extend(Closure)`
|
||||
- Example: `User::extend(function($model) { $model->hasMany['payments'] = ...; })`
|
||||
- Used for adding relationships, attributes, query scopes without modifying core
|
||||
|
||||
**Event System:**
|
||||
- Global events via `Event::listen()` and `Event::fire()`
|
||||
- Module-level events: `system.route`, `cms.beforeRoute`, `cms.route`, `backend.beforeRoute`
|
||||
- Model events: `model.saveInternal`, `model.afterCreate`, `model.afterUpdate`, `model.afterDelete`
|
||||
- Custom events fired by plugins for extensibility
|
||||
|
||||
**Behaviors:**
|
||||
- Controllers implement behaviors via `$implement` array
|
||||
- Backend behaviors: FormController, ListController, RelationController, ImportExportController
|
||||
- Each behavior adds methods (e.g., `create`, `update`, `index`) to controller
|
||||
- Example: `modules/backend/behaviors/FormController.php`
|
||||
|
||||
---
|
||||
|
||||
*Architecture analysis: 2026-02-04*
|
||||
Reference in New Issue
Block a user