chore: rename codebase map files to lowercase
This commit is contained in:
126
.paul/codebase/architecture.md
Normal file
126
.paul/codebase/architecture.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# Architecture
|
||||
|
||||
## Request Flow
|
||||
|
||||
```
|
||||
HTTP Request
|
||||
→ public/index.php
|
||||
→ bootstrap/app.php (loads config, registers PDO, services)
|
||||
→ Application::boot() (loads routes/web.php)
|
||||
→ Router::dispatch(Request) (matches URL, runs middleware pipeline)
|
||||
→ [Middleware] (AuthMiddleware, ApiKeyMiddleware)
|
||||
→ Controller::method() (parse input → call repository/service → render)
|
||||
→ Template::render() (PHP native, layout composition)
|
||||
→ Response::send()
|
||||
```
|
||||
|
||||
## Layer Map
|
||||
|
||||
| Layer | Location | Responsibility |
|
||||
|-------|----------|----------------|
|
||||
| Entry | `public/index.php` | Bootstrap only |
|
||||
| Routes | `routes/web.php` (581 lines) | All ~80 routes; manual DI wiring |
|
||||
| Core | `src/Core/` (25 files) | Framework infrastructure |
|
||||
| Controllers | `src/Modules/*/Controller.php` | Request parsing → response |
|
||||
| Services | `src/Modules/*/Service.php` | Business logic |
|
||||
| Repositories | `src/Modules/*/Repository.php` | PDO data access (34+ repos) |
|
||||
| Views | `resources/views/` | PHP templates with `$e()` / `$t()` |
|
||||
| Components | `resources/views/components/` | Reusable UI blocks |
|
||||
|
||||
## Module Inventory (`src/Modules/`)
|
||||
|
||||
| Module | Files | Key Classes | Purpose |
|
||||
|--------|-------|-------------|---------|
|
||||
| **Auth** | 3 | `AuthController`, `AuthMiddleware`, `AuthService` | Login/logout, session |
|
||||
| **Users** | 2 | `UserController`, `UserRepository` | User CRUD |
|
||||
| **Orders** | 3 | `OrdersController` (1187 LOC), `OrdersRepository` (1221 LOC) | Order list, detail, status, payment, correlated subquery for return-risk |
|
||||
| **Shipments** | 17 | `ShipmentController`, provider services + tracking services | Shipment creation, label download, tracking polling |
|
||||
| **Accounting** | 5 | `AccountingController`, `ReceiptService`, `ReceiptRepository` | Receipts, invoices, PDF, Excel export |
|
||||
| **Email** | 3 | `EmailSendingService`, `VariableResolver`, `AttachmentGenerator` | Template-based email with PDF attachments |
|
||||
| **Automation** | 6 | `AutomationService` (834 LOC), `AutomationRepository`, `AutomationExecutionLogRepository` | Event→condition→action rules, email triggers |
|
||||
| **Settings** | 51+ | Integration controllers, OAuth clients, API clients, mappers | Allegro/shopPRO/Apaczka/InPost config, status mappings |
|
||||
| **Cron** | 12 | `CronRepository`, `CronHandlerFactory`, handler classes | Scheduled imports, syncs, token refresh |
|
||||
| **Printing** | 4 | `PrintApiController`, `PrintJobRepository`, `ApiKeyMiddleware` | REST API for Windows print client |
|
||||
| **Statistics** | 2 | `OrdersStatisticsController`, `OrdersStatisticsRepository` | Dashboard aggregates |
|
||||
| **Info** | 1 | `InfoController` | Health check |
|
||||
|
||||
## Key Data Flows
|
||||
|
||||
### Order Lifecycle
|
||||
1. **Import** — Cron handler → API client → `OrderImportService` → `OrdersRepository::insertOrder()` → `AutomationService::executeForNewOrder()`
|
||||
2. **Status update** — `OrdersController::updateStatus()` → `OrdersRepository::updateStatus()` → automation check
|
||||
3. **Status sync** — Cron → `AllegroStatusSyncService` / `ShopproStatusSyncService` → carrier API
|
||||
|
||||
### Shipment Flow
|
||||
1. **Create** — `ShipmentController::create()` → `ShipmentProviderRegistry` → carrier `ShipmentService::createShipment()` → `ShipmentPackageRepository::insert()`
|
||||
2. **Track** — Cron `ShipmentTrackingHandler` → `ShipmentTrackingRegistry` → carrier tracking API → `ShipmentPackageRepository::updateDeliveryStatus()`
|
||||
|
||||
### Receipt / Invoice
|
||||
1. **Generate** — `ReceiptController::store()` → `ReceiptService::generateReceipt()` → `ReceiptRepository::insert()` + Dompdf PDF
|
||||
2. **Email** — `EmailSendingService::send()` → `VariableResolver::resolve()` → `AttachmentGenerator::generatePdf()` → PHPMailer SMTP
|
||||
|
||||
### Automation Rules
|
||||
1. **Setup** — `AutomationController` → `AutomationRepository::insertRule()`
|
||||
2. **Trigger** — `AutomationService::executeForOrder()` → evaluates trigger (`order_status_changed`, `order_status_aged`) → runs action (send email, update status)
|
||||
3. **Log** — `AutomationExecutionLogRepository` tracks every run
|
||||
|
||||
### Cron Jobs
|
||||
|
||||
| Handler | Task |
|
||||
|---------|------|
|
||||
| `AllegroOrdersImportHandler` | Fetch new Allegro orders |
|
||||
| `AllegroStatusSyncHandler` | Push status changes to Allegro |
|
||||
| `AllegroTokenRefreshHandler` | OAuth token refresh (24h expiry) |
|
||||
| `ShopproOrdersImportHandler` | Fetch new shopPRO orders |
|
||||
| `ShopproStatusSyncHandler` | Push status to shopPRO |
|
||||
| `ShopproPaymentStatusSyncHandler` | Sync payment statuses |
|
||||
| `ShipmentTrackingHandler` | Poll carrier tracking APIs |
|
||||
| `OrderStatusAgedHandler` | Trigger automation for stuck statuses |
|
||||
| `AutomationHistoryCleanupHandler` | Purge old automation logs |
|
||||
|
||||
## Dependency Injection
|
||||
|
||||
Manual constructor injection in `routes/web.php` — no DI container library. Example:
|
||||
|
||||
```php
|
||||
$ordersController = new OrdersController(
|
||||
$template, $translator, $auth,
|
||||
$app->orders(), $shipmentPackageRepository,
|
||||
$receiptRepository, $receiptConfigRepository, ...
|
||||
);
|
||||
```
|
||||
|
||||
All production classes are `final` — prevents accidental inheritance.
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
bootstrap/ app.php (service wiring, config loading)
|
||||
bin/ migrate.php, cron.php (CLI entry points)
|
||||
config/ app.php, database.php
|
||||
database/
|
||||
migrations/ 84 SQL files (YYYYMMDD_NNNNNN_description.sql)
|
||||
drafts/ WIP migrations
|
||||
public/
|
||||
index.php HTTP entry point
|
||||
.htaccess Apache rewrite rules
|
||||
assets/css/ Compiled CSS (app.css, login.css, modules/)
|
||||
assets/js/ jquery-alerts.js, global-search.js, automation-form.js
|
||||
resources/
|
||||
views/ PHP templates by module + components/ layouts/
|
||||
scss/ SCSS sources (app.scss, login.scss, modules/_*.scss)
|
||||
modules/ jquery-alerts JS+SCSS source
|
||||
lang/pl/ Polish translations
|
||||
routes/
|
||||
web.php All routes (581 lines)
|
||||
src/
|
||||
Core/ Framework (25 files)
|
||||
Modules/ 13 feature modules (~200+ PHP files)
|
||||
storage/
|
||||
logs/ app.log
|
||||
sessions/ PHP session files
|
||||
cache/ PHPUnit cache, etc.
|
||||
tests/
|
||||
Unit/ PHPUnit tests (7+ service test files)
|
||||
bootstrap.php PSR-4 autoloader for tests
|
||||
```
|
||||
Reference in New Issue
Block a user