docs(codebase): add codebase map — stack, architecture, structure, schema, conventions, testing, integrations, concerns

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-27 17:57:19 +02:00
parent 11afc80a7b
commit 5f23ca9482
8 changed files with 903 additions and 0 deletions
--- a/.paul/codebase/structure.md
+++ b/.paul/codebase/structure.md
@@ -0,0 +1,145 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-04-27
+
+## Directory Layout
+
+```
+_rejestracja/
+├── Admin/                  # Admin frontend (separate MVC stack)
+│   ├── controller/         # Admin controllers (CalcController, HomeSiteController, etc.)
+│   └── template/           # Admin Smarty templates
+│       └── partial/
+│           └── Calc/       # Registration admin views (Reg.tpl, RegEdit.tpl, RegPAN.tpl)
+├── controller/             # Public controllers (IndexController.php)
+├── core/                   # Shared core layer (both frontends)
+│   ├── class/              # Framework classes (Router, DefaultDAL, DataObject, Validator, etc.)
+│   ├── config/             # INI config files (db.config.ini, smtp.config.ini)
+│   ├── lib/                # Third-party libraries (Smarty, PHPMailer)
+│   ├── model/              # Active models: Mf{Entity}.class.php + Mf{Entity}DAL.class.php
+│   └── _model/             # Legacy backup of model/ — NOT loaded by autoloader (78 mirror files)
+├── sql/                    # Migration SQL files + PHP runner scripts
+├── Static/                 # Frontend assets (CSS, JS, images)
+│   └── image/Admin/        # Admin UI images (Thumbs.db ignored)
+├── template/               # Public Smarty templates
+│   └── partial/Index/      # Registration form templates (Index.tpl, IndexSent.tpl, etc.)
+├── index.php               # Public frontend entry point
+└── Admin/index.php         # Admin frontend entry point
+```
+
+## Directory Purposes
+
+**`core/model/`** (ACTIVE — edit here):
+- Purpose: All domain models and DAL classes
+- Contains: `Mf{Entity}.class.php` (model), `Mf{Entity}DAL.class.php` (data access)
+- Key files: `MfParticipant.class.php`, `MfParticipantDAL.class.php`, `MfParameters.class.php`, `MfDictionary.class.php`
+- Loaded by: `core/core.php` autoloader via `spl_autoload_register`
+
+**`core/_model/`** (LEGACY — do not edit):
+- Purpose: Stale backup of model directory; 78 files mirroring `core/model/`
+- NOT loaded by autoloader — changes here have no effect
+- Should be deleted but kept for historical reference
+
+**`core/class/`**:
+- Purpose: Framework infrastructure
+- Key files: `Router.class.php`, `DefaultDAL.class.php`, `DataObject.class.php`, `Validator.class.php`, `SessionProxy.class.php`, `Request.class.php`, `MainController.class.php`
+
+**`core/config/`**:
+- Purpose: Runtime configuration
+- Key files: `db.config.ini` (DB credentials), `smtp.config.ini` (SMTP credentials)
+- WARNING: Both committed to repo — contain production secrets
+
+**`core/lib/`**:
+- Purpose: Bundled third-party libraries
+- Contains: Smarty 3.x, PHPMailer, other vendored code
+
+**`controller/`**:
+- Purpose: Public-facing request handlers
+- Key files: `IndexController.php` (registration form — main entry point for all user interactions)
+
+**`Admin/controller/`**:
+- Purpose: Admin panel request handlers
+- Key files: `CalcController.php` (registration list, edit, delete), `HomeSiteController.php` (content editing)
+
+**`template/partial/Index/`**:
+- Purpose: Public registration form templates
+- Key files: `Index.tpl` (main form), `Index_good.tpl` (alternate variant), `IndexSent.tpl` (confirmation), `IndexSent_good.tpl` (alternate confirmation)
+
+**`Admin/template/partial/Calc/`**:
+- Purpose: Admin registration management views
+- Key files: `Reg.tpl` (registration list), `RegEdit.tpl` (edit payment status), `RegPAN.tpl` (alternate location view)
+
+**`sql/`**:
+- Purpose: Database migrations
+- Pattern: `YYYY-MM-DD-description.sql` + `apply-YYYY-MM-DD-description.php` (idempotent runner)
+- Key files: `apply-2026-04-24-registration-form-settings.php`, `apply-2026-04-27-additional-info-field.php`
+
+## Key File Locations
+
+**Entry Points:**
+- `_rejestracja/index.php` — public registration frontend
+- `_rejestracja/Admin/index.php` — admin panel frontend
+
+**Configuration:**
+- `_rejestracja/core/config/db.config.ini` — database connection
+- `_rejestracja/core/config/smtp.config.ini` — SMTP email credentials
+- `.vscode/ftp-kr.sync.cache.json` — FTP deployment sync config
+
+**Core Logic:**
+- `_rejestracja/core/class/DefaultDAL.class.php` — generic CRUD base
+- `_rejestracja/core/model/MfParticipant.class.php` — registration participant model
+- `_rejestracja/controller/IndexController.php` — registration form controller (save, email, display)
+- `_rejestracja/Admin/controller/CalcController.php` — admin registration management
+
+**Testing:**
+- None
+
+## Naming Conventions
+
+**Files:**
+- `Mf{Entity}.class.php` — model classes (MfParticipant, MfParameters, MfDictionary)
+- `Mf{Entity}DAL.class.php` — data access layer classes
+- `{Name}Controller.php` — controller classes
+- `{Name}.tpl` — Smarty templates
+- `YYYY-MM-DD-description.sql` — migration SQL files
+- `apply-YYYY-MM-DD-description.php` — idempotent migration runners
+
+**Directories:**
+- PascalCase for Admin sub-directories (Admin/controller/, Admin/template/)
+- lowercase for core infrastructure directories (core/class/, core/model/)
+
+## Where to Add New Code
+
+**New model field:**
+- Model: `_rejestracja/core/model/Mf{Entity}.class.php` — add to `$fields`, add property + getter/setter
+- Migration: `_rejestracja/sql/YYYY-MM-DD-description.sql` + `apply-*.php` runner
+
+**New form field (public):**
+- Template: `_rejestracja/template/partial/Index/Index.tpl` and `Index_good.tpl`
+- Controller: `_rejestracja/controller/IndexController.php` — read POST, set on model
+- Confirmation: `IndexSent.tpl`, `IndexSent_good.tpl`
+- Admin display: `_rejestracja/Admin/template/partial/Calc/Reg.tpl`
+
+**New admin action:**
+- Controller: `_rejestracja/Admin/controller/CalcController.php` — add `{Name}Action` method
+- Template: `_rejestracja/Admin/template/partial/Calc/{Name}.tpl`
+
+**New dictionary phrase:**
+- SQL insert into `mf_dictionary` table + migration runner
+
+## Special Directories
+
+**`core/_model/`:**
+- Purpose: Legacy backup, 78 files mirroring `core/model/`
+- Source: Manual backup, not updated consistently
+- NOT in autoloader path — editing here has NO effect
+
+**`sql/`:**
+- Purpose: Database migration scripts
+- Runners are web-accessible (risk) — require `?run=YYYYMMDD` param to execute
+- Idempotent pattern: check `INFORMATION_SCHEMA` before `ALTER TABLE`
+
+---
+
+*Structure analysis: 2026-04-27*
+*Update when directory structure changes*