Dodano mapę kodu w .paul/codebase/ (7 dokumentów)

Wygenerowano przez równoległą analizę czterech agentów: stack, architektura,
konwencje, integracje, testy, baza danych oraz wykryte problemy i dług techniczny.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.paul/codebase/architecture.md

@@ -0,0 +1,126 @@
+# Architecture — rank24.pl
+
+## Pattern
+Custom PHP MVC — no framework. Layered as **controls → factory → view**, with Savant3 templates.
+
+## Entry Points
+
+| File | Purpose |
+|------|---------|
+| `index.php` | Front controller — bootstraps app, routes all page requests |
+| `ajax.php` | xajax AJAX endpoint |
+| `json.php` | JSON responses for AJAX calls |
+| `api.php` | External API integration endpoint |
+| `cron.php` | Background job runner |
+| `proxy.php` | Proxy management endpoint |
+| `ajax-check.php` | Health check / secondary AJAX |
+| `dsf.php` | DataForSEO callback handler |
+
+## Directory Structure
+
+```
+rank24.pl/
+├── index.php               Front controller & bootstrap
+├── config.php              All configuration (DB, proxy, intervals)
+├── cron.php                Cron job runner
+├── .htaccess               URL rewriting rules
+│
+├── autoload/               PSR-0-style autoloaded classes
+│   ├── class.*.php         Core utility classes
+│   ├── controls/           Page controllers (routing + business logic)
+│   ├── factory/            Data access layer (DB queries via Medoo)
+│   ├── view/               View renderers (build Savant3 template output)
+│   ├── savant3/            Savant3 template engine internals
+│   └── opd*/               Legacy PDO debug wrapper
+│
+├── templates/              PHP view templates
+│   ├── page/               Admin main/unlogged layouts
+│   ├── client/             Client dashboard templates
+│   ├── ranker/             Admin/ranker management templates
+│   ├── reseller/           Reseller dashboard templates
+│   ├── html/               Reusable form component templates
+│   ├── other/              Pagination, alerts, misc templates
+│   └── cron/               Cron management view
+│
+├── functions/              xajax AJAX handler functions
+│   ├── xajax.php           xajax init & config
+│   ├── xajax-ranker.php    Rank-related AJAX
+│   ├── xajax-messages.php  Messaging AJAX
+│   ├── xajax-analysis.php  Analysis AJAX
+│   └── xajax-settings.php  Settings AJAX
+│
+├── libraries/              Third-party libraries
+│   ├── medoo.php           ORM
+│   ├── grid/               Custom DataTables grid
+│   └── framework/          Bootstrap + jQuery + 57 plugins
+│
+├── layout/                 Static assets, compiled CSS
+├── resources/              xajax, phpmailer, mPDF
+└── temp/, temp_t/          File cache directories
+```
+
+## Autoloading
+
+Defined in `index.php`:
+```php
+// namespace\ClassName → autoload/namespace/class.ClassName.php
+// ClassName           → autoload/class.ClassName.php
+spl_autoload_register('__autoload_my_classes');
+```
+
+## Request Flow
+
+```
+HTTP request
+  → .htaccess: rewrites /m/a/params → ?module=m&action=a&params
+  → index.php: load config, init $db (OPD) + $mdb (Medoo), start session, init $cache
+  → \controls\Page::checkUrlParams()   (handles ?rw= special actions)
+  → \controls\Page::getContent()       (resolves module+action → controller class)
+  → \controls\[Module]::method()       (business logic, calls factory)
+  → \factory\[Module]::query()         (Medoo DB queries)
+  → \view\[Module]::render()           (assigns data to Savant3, returns HTML)
+  → \view\Page::show()                 (wraps in role-appropriate layout)
+  → HTML → browser
+```
+
+## User Roles & Routing
+
+| Role | Source table | Layout |
+|------|-------------|--------|
+| `admin` | `pro_users` | `templates/page/main-layout.php` |
+| `client` | `pro_rr_clients` (type=0) | `templates/client/main-layout.php` |
+| `worker` | `pro_rr_clients` (type=2) | `templates/client/main-layout.php` |
+| `reseller` | `pro_rr_clients` (type=1) | `templates/reseller/main-layout.php` |
+
+## Template System
+
+Two systems co-exist:
+
+**Savant3** (primary): `$tpl = new \Savant3; $tpl->varName = $val; return $tpl->fetch('ranker/summary');`
+
+**Tpl** (lightweight): `$tpl = new \Tpl; $tpl->render('other/pager');`
+- Template search order: `templates_a/` → `templates_b/` → `templates/`
+
+## Database Layer
+
+Two connections initialized in `index.php`:
+- `$db` — OPD (legacy PDO debug wrapper), used in older code paths
+- `$mdb` — Medoo ORM, used in all newer code
+
+Factory pattern: controllers call `\factory\Ranker::getClient($id)` which does `global $mdb; return $mdb->get(...)`.
+
+## Cron System
+
+`cron.php` → `\Cron::staticMethod()` — jobs defined as static methods in `autoload/class.Cron.php`:
+- `fill_missing_positions()` — interpolates missing rank records
+- `archive_positions()` / `archive_empty()` — data archiving
+- `check_proxy()` — validates proxy pool
+- `get_phrases_positions_dfs3()` / `post_phrases_positions_dfs3()` — DataForSEO rank fetching
+
+## AJAX System
+
+`functions/xajax.php` registers handler functions → `ajax.php` processes incoming xajax requests → returns DOM update commands to jQuery on client.
+
+## Caching
+
+`\FileCache` stores serialized data in `temp/` and `temp_t/`. Invalidated via `\S::deleteCache()`.