# 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*
