vidok.com/.paul/codebase/structure.md

Codebase Structure

Analysis Date: 2026-05-05

Directory Layout

vidok.com/
├── index.php               # Frontend entry point
├── ajax.php                # Frontend AJAX handler
├── config.php              # Database credentials (hardcoded)
├── download.php            # Secure file download handler
├── get_file.php            # PDF/document download wrapper
├── api/                    # JSON API endpoints
├── admin/                  # Admin panel application
│   ├── index.php           # Admin entry point
│   ├── ajax.php            # Admin AJAX handler
│   ├── css/                # Admin SCSS source files
│   ├── style-css/          # Compiled admin CSS
│   └── templates/          # Admin UI PHP templates
├── autoload/               # Core PHP classes (MVC layers)
│   ├── class.S.php         # Global static helpers
│   ├── class.Tpl.php       # Template engine
│   ├── class.Cache.php     # Session cache
│   ├── class.Html.php      # HTML generation helpers
│   ├── class.Image.php     # Image processing
│   ├── front/              # Frontend MVC classes
│   │   ├── controls/       # Frontend controllers
│   │   ├── factory/        # Frontend models (DB queries)
│   │   └── view/           # Frontend HTML generators
│   └── admin/              # Admin MVC classes
│       ├── controls/       # Admin controllers
│       ├── factory/        # Admin models (DB queries)
│       └── view/           # Admin HTML generators
├── templates/              # Default frontend PHP templates
│   ├── articles/           # Article display templates
│   ├── pages/              # Page display templates
│   ├── site/               # Layout partials (header, footer, etc.)
│   ├── newsletter/         # Newsletter form templates
│   └── widgets/            # Widget templates
├── templates_user/         # Custom frontend templates (override defaults)
├── layout/                 # Frontend CSS, JS, fonts
│   ├── style-scss/         # SCSS source files
│   │   ├── _variables.scss # Color/font variables
│   │   ├── _mixins.scss    # Responsive breakpoints, mixins
│   │   └── style.scss      # Main SCSS entry point
│   ├── style-css/          # Compiled frontend CSS
│   └── js/                 # Frontend JavaScript
│       ├── main.js         # Main frontend JS
│       └── custom.js       # Custom frontend JS
├── libraries/              # Vendored PHP/JS libraries
│   ├── medoo/              # Medoo ORM
│   ├── phpmailer/          # PHPMailer for email
│   ├── ckeditor/           # Rich text editor
│   ├── grid/               # Admin data grid component
│   ├── bootstrap-4.1.3/    # Bootstrap 4
│   ├── bootstrap-5.0/      # Bootstrap 5
│   ├── font-awesome-6.1.1/ # Icon library
│   ├── swiper/             # Carousel library
│   ├── framework/          # Date pickers, moment.js
│   └── jquery/             # jQuery utilities (lozad, captcha)
├── plugins/                # Hook files for extensibility
│   ├── special-actions.php          # Early hooks
│   ├── special-actions-middle.php   # Contact forms, file uploads
│   └── special-actions-end.php      # Late hooks
├── images/                 # User-uploaded images
├── upload/                 # User-uploaded files
├── cache/                  # Runtime cache + generated WebP images
├── stopki/                 # Footer content fragments
├── .paul/                  # PAUL project management files
├── .vscode/                # VS Code settings (SCSS compile, SFTP)
└── .htaccess               # Apache URL rewriting rules

Directory Purposes

autoload/:

• Purpose: All PHP application classes — the core of the CMS
• Pattern: class.ClassName.php naming
• Namespaced: front\controls\, front\factory\, front\view\, admin\controls\, admin\factory\, admin\view\
• Key files: class.S.php (global helpers), class.Tpl.php (templating), class.Image.php

admin/templates/:

• Purpose: PHP template files for admin panel UI
• Organized by module: articles/, pages/, users/, newsletter/, layouts/, scontainers/, html/
• Key files: articles/article-edit.php, pages/page-edit.php, site/main-layout.php

templates/ and templates_user/:

• Purpose: Frontend page templates
• templates/ — default templates (shipped with CMS)
• templates_user/ — project-specific overrides (take precedence over defaults)
• Tpl::view() checks templates_user/ first, falls back to templates/

layout/:

• Purpose: All frontend CSS, JS, fonts
• SCSS source in layout/style-scss/, compiled output in layout/style-css/
• JS in layout/js/

libraries/:

• Purpose: All vendored third-party libraries (no package manager)
• PHP libraries: Medoo, PHPMailer, Grid
• JS libraries: CKEditor, Bootstrap, Swiper, DatePickers

plugins/:

• Purpose: Extension hooks called from index.php at different lifecycle stages
• special-actions-middle.php is the main plugin — contains all contact form handlers and reCAPTCHA

cache/:

• Purpose: Runtime-generated files (WebP images)
• Auto-created by \Image class during first request
• Not committed to git (runtime data)

Key File Locations

Entry Points:

• index.php — public frontend entry
• ajax.php — frontend AJAX
• admin/index.php — admin panel entry
• admin/ajax.php — admin AJAX
• api/contact_map.php — contacts/locations JSON API

Configuration:

• config.php — database credentials (single config file, no .env)
• admin/ip.conf — optional IP whitelist for admin panel
• .vscode/settings.json — SCSS compile settings

Core Logic:

• autoload/class.S.php — global helpers (images, cache, email, sessions)
• autoload/class.Tpl.php — template engine
• autoload/front/view/class.Site.php — main frontend page renderer
• autoload/admin/view/class.Page.php — main admin page renderer
• libraries/medoo/medoo.php — database ORM

Templates (Frontend):

• templates/articles/ — article display patterns
• templates/site/ — header, footer, contact, Facebook widget
• templates_user/page-contact-v*.php — custom contact page variants

Naming Conventions

PHP Class Files:

• Pattern: class.ClassName.php (e.g., class.Articles.php, class.Users.php)
• Namespace mirrors directory: admin\factory\ = autoload/admin/factory/class.*.php

PHP Templates:

• Pattern: feature-type.php in kebab-case (e.g., article-edit.php, articles-browse-list.php)

SCSS/CSS:

• Helper files: _variables.scss, _mixins.scss (underscore prefix)
• Feature files: kebab-case (e.g., drzwi-wejsciowe-aluminiowe.scss)
• Compiled output in style-css/ mirroring style-scss/

Directories:

• Feature groupings in kebab-case
• Plural for collections: articles/, templates/, controls/

Where to Add New Code

New Content Module (e.g., "Events"):

• Admin factory: autoload/admin/factory/class.Events.php
• Admin controls: autoload/admin/controls/class.Events.php
• Admin view: autoload/admin/view/class.Events.php
• Admin templates: admin/templates/events/
• Frontend factory: autoload/front/factory/class.Events.php
• Frontend templates: templates_user/events/ or templates/events/

New Frontend Page Template:

• Custom: templates_user/page-[name].php
• Default: templates/pages/page-[type].php

New Contact Form Variant:

• Add handler to plugins/special-actions-middle.php

New AJAX Action:

• Frontend: add case in ajax.php
• Admin: add case in admin/ajax.php

New JS/CSS:

• Frontend JS: layout/js/custom.js or new file in layout/js/
• Frontend SCSS: layout/style-scss/ (compiled by Live Sass Compiler)
• Admin SCSS: admin/css/custom.scss

Special Directories

cache/:

• Purpose: Runtime-generated WebP images and temporary cache
• Source: Auto-generated by \Image class and \Cache class
• Committed: No (runtime data, not in git)

admin/temp/:

• Purpose: Temporary file uploads during admin operations
• Source: File upload handlers
• Committed: Should not be committed

templates_user/:

• Purpose: Project-specific template overrides
• Source: Manual creation — customizations live here
• Committed: Yes (project-specific content)

---

Structure analysis: 2026-05-05 Update when directory structure changes