# Codebase Map — orderPRO

> Generated: 2026-03-12
> Branch: main

## What is this project?

**orderPRO** is a custom PHP 8.4 order management system (OMS) that aggregates and manages orders from multiple sales channels (Allegro marketplace, shopPRO e-commerce platform). It handles order import, status synchronization, shipment management, and product data enrichment. The system is entirely self-contained — no Composer runtime dependencies — built on a hand-rolled micro-framework.

---

## Documents

| Document | Contents |
|----------|----------|
| [STACK.md](./STACK.md) | Language, framework, DB, integrations, build tools, dependencies |
| [ARCHITECTURE.md](./ARCHITECTURE.md) | Directory layout, layers, request flow, domain model, all 24 DB tables |
| [CONVENTIONS.md](./CONVENTIONS.md) | Naming rules, design patterns, DB access style, frontend conventions, testing |
| [CONCERNS.md](./CONCERNS.md) | Tech debt, bugs, security gaps, incomplete features — with severity levels |

---

## Quick Reference

### Stack
- **PHP 8.4**, zero Composer runtime deps, hand-rolled framework in `src/Core/`
- **MySQL** via raw PDO prepared statements (no ORM)
- **Frontend**: plain PHP views, SCSS → CSS via Dart Sass, jQuery + custom alert module
- **Tests**: PHPUnit 11 (currently zero active test coverage)

### External Integrations
| Integration | Purpose |
|-------------|---------|
| **Allegro** | OAuth 2.0, order import, status sync, shipment management |
| **shopPRO** | API key auth, order/product import |
| **Apaczka** | HMAC-signed REST, multi-carrier shipping aggregator |
| **InPost ShipX** | Bearer token REST, parcel lockers (settings only — shipments route via Allegro WZA workaround) |
| **GS1** | Barcode/product data (bin scripts) |

### Architecture in One Sentence
`public/index.php` → `Application` → `Router` → middleware pipeline → controller (in `src/Modules/`) → service → repository (raw PDO) → plain PHP view.

### Top Concerns to Address
1. **OAuth refresh duplicated** across 4 Allegro services → extract `AllegroTokenRefreshService`
2. **Utility methods duplicated** 15+ times across repositories → shared trait or utility class
3. **Zero test coverage** — `tests/` directory is empty
4. **Known bug**: `AllegroShipmentService.php:255` — ZPL branch always returns `'A6'` (dead conditional)
5. **InPost shipment provider stub** — settings exist, no `ShipmentProviderInterface` implementation
6. **No `CURLOPT_SSL_VERIFYPEER`** set in any cURL client — implicit trust of TLS certs

---

## Module Overview

| Module | Path | Responsibility |
|--------|------|----------------|
| Auth | `src/Modules/Auth/` | Login, session management |
| Orders | `src/Modules/Orders/` | Order list, detail, filters, status updates |
| Settings | `src/Modules/Settings/` | Integration config, carrier mapping, status groups |
| Shipments | `src/Modules/Shipments/` | Shipment creation, label printing, provider dispatch |
| Cron | `src/Modules/Cron/` | Cron job runner, schedule management |
| Users | `src/Modules/Users/` | User management |

---

## Entry Points

| Entry | Path |
|-------|------|
| Web app | `public/index.php` |
| Route definitions | `routes/web.php` |
| CLI scripts | `bin/` (8 scripts) |
| DB migrations | `database/migrations/` |