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