vidok.com/.paul/codebase/architecture.md

Architecture

Analysis Date: 2026-05-05

Pattern Overview

Overall: Custom MVC CMS (Content Management System) — dual-layer monolith

Key Characteristics:

• Two distinct application layers: public frontend and admin panel
• Namespace-based class autoloading (no Composer PSR-4, custom autoloader)
• Factory (Model) + Controls (Controller) + View separation per layer
• Medoo ORM for all database operations
• Apache .htaccess URL rewriting for routing
• Template engine (Tpl class) for view rendering with PHP template files
• Plugin hook system for extensibility without modifying core

Layers

Frontend Layer (front namespace):

• Purpose: Serve public website to visitors
• Contains: Route handlers, page rendering, form processing
• Controls: autoload/front/controls/ — URL parsing, request dispatch
• Factory: autoload/front/factory/ — database queries, data retrieval
• View: autoload/front/view/ — HTML generation
• Templates: templates/, templates_user/ (user overrides take precedence)
• Entry: index.php

Admin Panel Layer (admin namespace):

• Purpose: CMS content management interface for editors
• Contains: CRUD operations for all content types, user management
• Controls: autoload/admin/controls/ — admin action handlers
• Factory: autoload/admin/factory/ — admin database operations
• View: autoload/admin/view/ — admin UI rendering
• Templates: admin/templates/ organized by module (articles, pages, users, etc.)
• Entry: admin/index.php

Core/Shared Layer (root autoload/):

• Purpose: Utilities and helpers shared by both layers
• Key classes:
  • autoload/class.S.php — static helpers (1328 lines): images, cache, sessions, email, DB utils
  • autoload/class.Tpl.php — template engine (loads/renders PHP template files)
  • autoload/class.Cache.php — session-based caching
  • autoload/class.Html.php — HTML generation helpers
  • autoload/class.Image.php — image processing (WebP conversion)

Database Layer:

• Medoo ORM (libraries/medoo/medoo.php) — all DB access
• MySQL with pp_ prefixed tables (~32 tables)
• Configuration in config.php

Data Flow

Frontend Page Request:

1. HTTP request hits Apache — .htaccess rewrites URL to index.php query params
2. index.php — initializes autoloader, session, Medoo DB instance, loads config.php
3. \front\controls\Site::check_url_params() — parses ?a= (action) and ?id= (resource ID)
4. Language loaded from session (current-lang), global settings from pp_settings
5. Page determined from pp_pages and pp_layouts tables
6. \front\view\Site::show() — assembles layout HTML
7. Layout HTML has placeholders ([MENU:id], [ARTYKULY:id], [KONTENER:id]) replaced at runtime
8. Tpl::view() renders PHP template files into final HTML
9. Optional: page-level cache stored/served, WebP images generated

Admin Panel Request:

1. Request hits admin/index.php — .htaccess routes /admin/module/action/
2. Session check + optional cookie-based auto-login
3. \admin\factory\Users::check_privileges() — access control verification
4. Route parsed: module and action determine which class/method to call
5. Factory methods perform DB operations (Medoo queries)
6. Grid library or Tpl::view() renders response

AJAX Request:

1. ajax.php (frontend) or admin/ajax.php (admin) receives request
2. ?a=action parameter dispatches to appropriate handler
3. Returns JSON response
4. Examples: contact_form, cookie_close, inline-edit-save, pixieset_*

State Management:

• Session-based: language preference, admin auth, inline-edit mode (front-devel)
• Database: all persistent content state
• File cache: WebP images in cache/ directory
• Session cache: page data via \Cache class

Key Abstractions

Factory (Model):

• Purpose: Database operations for a content domain
• Pattern: Static methods on classes (not instantiated)
• Location: autoload/front/factory/class.*.php, autoload/admin/factory/class.*.php
• Examples: \admin\factory\Articles, \front\factory\Newsletter
• Methods: article_details(), articles_list(), article_save(), article_delete()

Controls (Controller):

• Purpose: Handle requests, validate input, call factories, pass to views
• Pattern: Static methods, namespaced by layer
• Location: autoload/front/controls/class.*.php, autoload/admin/controls/class.*.php

View:

• Purpose: Generate HTML for frontend or admin
• Pattern: Static methods that load templates via Tpl::view()
• Location: autoload/front/view/class.*.php, autoload/admin/view/class.*.php

Template System:

• Tpl::view() — loads PHP template file, passes variables, captures output
• Fallback: templates_user/ (custom) overrides templates/ (default)
• Layout placeholders: [MENU:id], [ARTYKULY:id], [KONTENER:id], [BANERY], [NEWSLETTER], [WIDGET_TELEFON], [MAPA]...[/MAPA]

Plugin Hooks:

• plugins/special-actions.php — early hooks
• plugins/special-actions-middle.php — contact forms, file uploads, reCAPTCHA
• plugins/special-actions-end.php — late hooks

Entry Points

Frontend:

• index.php — primary public entry point; bootstraps app, calls \front\view\Site::show()
• ajax.php — AJAX handler for contact forms, cookie consent, gallery actions, inline editing

Admin Panel:

• admin/index.php — admin entry; handles auth, routes to admin controls/views
• admin/ajax.php — admin AJAX handler

API:

• api/contact_map.php — JSON API for contact/location map data
• download.php — secure file download for article attachments
• get_file.php — PDF/document download wrapper

Error Handling

Strategy: Inconsistent — errors largely suppressed rather than handled

Patterns:

• error_reporting(0) in admin/ajax.php, admin/index.php — all errors silenced
• error_reporting(E_ALL ^ E_NOTICE ^ E_STRICT ^ E_WARNING ^ E_DEPRECATED) in frontend entry points
• No try/catch blocks in most factory methods
• No global exception handler
• Failed DB operations silently return null or empty array

Cross-Cutting Concerns

Caching:

• \Cache::fetch() / \Cache::store() — session-based page data cache
• \S::delete_cache() — invalidates cache on content changes
• WebP image generation + file caching in cache/

Multi-language:

• All content tables have _langs counterpart (e.g., pp_articles_langs, pp_pages_langs)
• Language ID loaded per request from session and pp_langs table
• Language strings managed in pp_langs_translations

Inline Editing (Developer Mode):

• When front-devel session is set, pages render with contenteditable="true"
• Saves edits back to pp_layouts.html via ajax.php?a=inline-edit-save

Authentication:

• Admin only — no frontend user auth
• Session-based with IP validation
• Cookie-based "remember me" with auto-login
• Privilege system: pp_users_privileges junction table

---

Architecture analysis: 2026-05-05 Update when major patterns change