diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..5ed8f3f --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,299 @@ +# SuperSeller3000 — Architecture Reference + +> Quick-reference for Claude Code. Covers layer structure, domain model, all async flows, eBay integration, auth, and key gotchas. Read this before grepping blindly. + +--- + +## 1. Layer Structure + +``` +src/ +├── Domain/ Pure entities, value objects, repository interfaces — no Symfony, no Doctrine annotations beyond mapping +├── Application/ Use-case services and port interfaces (ChannelAdapterInterface, ErpAdapterInterface, …) +├── Infrastructure/ Symfony/Doctrine/HTTP implementations, Messenger handlers, controllers, console commands +└── Kernel.php +``` + +**Dependency rule:** Domain ← Application ← Infrastructure. Nothing in Domain or Application imports from Infrastructure. + +Repository interfaces live in `Domain/*/Repository/`. Doctrine implementations live in `Infrastructure/Persistence/Repository/`. + +--- + +## 2. Domain Model (key entities and relationships) + +``` +ArticleType ──< ArticleTypeAttribute >── AttributeDefinition + │ + └──< ArticleTypeEbayMapping (eBay aspect → Article field or AttributeDefinition) + │ +ArticleTypePlatformConfig(ArticleType, Platform) (categoryId + 4 policy fields per adapter type) + +Article ──> ArticleType + ──< AttributeValue >── AttributeDefinition + ──< ArticlePhoto + fields: sku, inventoryNumber, status(enum), stock, condition(enum), serialNumber, + manufacturer, modelNumber, modelName, listingPrice, specsText, + ebayListingId, ebayTitle, ebayDescription + +Order ──> Article, Customer, Platform + ──> Invoice + +AIPipelineJob tracks every async AI run; stores input/output per step in JSON columns +Platform type string (e.g. 'ebay'), display name +ApiKey bcrypt-hashed secret, linked to User via ManyToOne +``` + +**ArticleType virtual form properties** (`pendingRequired`/`pendingOptional`): EasyAdmin sets these; call `applyAttributeAssignments()` before flush — see `ArticleTypeCrudController`. + +**ArticleTypeEbayMapping.sourceType**: `'article_field'` → read `Article::get{ArticleFieldKey}()`; `'attribute'` → read `AttributeValue` for the linked `AttributeDefinition`. + +--- + +## 3. AI Pipeline — Pipeline A (Photo upload) + +Entry point: `POST /api/pipeline/photo` → dispatches `PhotoUploadMessage` + +``` +PhotoUploadMessage + → PhotoUploadHandler + ├─ OllamaVisionAgent (Mistral pixtral-12b-2409) → {manufacturer, modelName, modelNumber, serial} + ├─ if modelName+modelNumber empty → markNeedsReview, stop + ├─ articleRepo.findCompletedByModelNumber(modelNumber)? + │ YES (cache hit) ──→ records step 'model_match' → DraftArticleMessage + │ DraftArticleHandler copies ebayTitle/Description/specsText + │ from matched article, skips EbayTextMessage, markCompleted + │ + └─ NO (cache miss) ──→ SpecsResearchMessage + → SpecsResearchHandler (Mistral large + Tavily web search) + → JsonCodingMessage + → JsonCodingHandler (Mistral large) → {attributes: {defId: value, …}} + → ValidationMessage + → ValidationHandler + ├─ all required fields present? → DraftArticleMessage + └─ missing + attempts < 3 → JsonCodingMessage (retry with missingFields hint) + └─ attempts ≥ 3 → markNeedsReview + +DraftArticleMessage + → DraftArticleHandler + ├─ creates or updates Article (re-run: job.articleId already set) + ├─ sets manufacturer/modelNumber/modelName from vision step + ├─ if model_match in job output → copies texts, markCompleted (no EbayText step) + └─ otherwise → EbayTextMessage + +EbayTextMessage + → EbayTextHandler (Mistral large) → sets article.ebayTitle + ebayDescription, markCompleted +``` + +--- + +## 4. AI Pipeline — Pipeline B (PXE / manual specs dump) + +Entry point: `POST /api/pipeline/pxe` → dispatches `PxeInventoryMessage` + +``` +PxeInventoryMessage + → PxeInventoryHandler → JsonCodingMessage (specsText = pxeDump) + → (same JSON→Validation→Draft→EbayText chain as Pipeline A cache-miss path) +``` + +--- + +## 5. Order Flow + +Entry point: eBay webhook `POST /webhook/ebay` → `EbayWebhookController` verifies signature → dispatches `OrderReceivedMessage` + +``` +OrderReceivedMessage (transport: orders, max_retries: 5) + → OrderReceivedHandler + 1. idempotency: findByPlatformOrderId → skip if exists + 2. fulfillmentClient.getOrder(platformOrderId) → {ebayListingId, buyer*, shipping*, salePrice, saleDate} + 3. articleRepo.findByEbayListingId → UnrecoverableMessageHandlingException if not found + 4. platformRepo.findByType('ebay') → UnrecoverableMessageHandlingException if not configured + 5. articleRepo.decrementStockAtomic → critical log + Unrecoverable if stock was already 0 + 6. customerResolver.resolve(platform, buyerUsername, …) → find or create Customer + 7. new Order(article, customer, platform, platformOrderId, salePrice, saleDate) + 8. erp.createSalesInvoice(order) → Frappe invoice ID + 9. erp.fetchInvoicePdf(frappeInvoiceId) → binary PDF + 10. storage.store(tmpFile, 'invoice-{id}.pdf') → StoredFile + 11. new Invoice(order, frappeInvoiceId, storagePath, filename) + 12. mailer.sendInvoice(invoice) → SMTP with PDF attachment + 13. dispatch UpdateStockOnChannelsMessage(articleId, newStock) + 14. order.setStatus(Completed) + +UpdateStockOnChannelsMessage (transport: channel_sync) + → UpdateStockOnChannelsHandler + if newStock == 0 → dispatch DeactivateListingMessage per platform + else → adapterRegistry.get(platform.type).updateStock(article, newStock) + +DeactivateListingMessage + → DeactivateListingHandler → adapter.deactivateListing(article) +``` + +--- + +## 6. Channel Adapter Pattern + +**Interface:** `Application/Channel/ChannelAdapterInterface` + +```php +getType(): string +publishListing(Article): string // returns listingId +updateStock(Article, int): void +deactivateListing(Article): void +pushTracking(Order): void +``` + +**Registry:** `Application/Channel/ChannelAdapterRegistry` — receives `iterable $adapters` via tagged_iterator tag `app.channel_adapter`. Look up with `has(type)` / `get(type)`. + +**eBay adapter:** `Infrastructure/Channel/Ebay/EbayAdapter` +- Reads `ArticleTypePlatformConfig` via `findByArticleTypeAndPlatformType($articleType, 'ebay')` — throws `\RuntimeException` if missing +- `buildAspects()` iterates `ArticleType::getEbayMappings()` and resolves each to a value via article field getter or `AttributeValue` +- `publishListing` calls: `upsertInventoryItem` → `createOffer` → `publishOffer`; conditionally adds `listingPolicies` (only if non-empty) and `merchantLocationKey` (only if not null) + +**eBay API clients:** +- `EbayOAuthClient` — Client-Credentials token with PSR-6 cache +- `EbayInventoryApiClient` — Inventory API (upsert item, create/publish/withdraw offer, bulk stock update, get locations) +- `EbayAccountApiClient` — Account API (fulfillment/payment/return policies) +- `EbayFulfillmentApiClient` — Fulfillment API (getOrder, addTracking) +- `EbayTaxonomyService` — Taxonomy API (category suggestions, aspect metadata) + +**EbayPolicyProvider:** aggregates all 4 choice lists (fulfillment, payment, return, location) with 5-minute PSR-6 cache; returns `[]` on any exception (triggers fallback TextField in admin form). + +--- + +## 7. Messenger Transports + +All transports use Redis Streams (DSN from `MESSENGER_TRANSPORT_DSN`). + +| Transport | Stream | Retries | Delay | Used for | +|---------------|----------------|---------|----------------|---------------------------------------------------| +| `ai_pipeline` | `ai_pipeline` | 3 | 2 s × 2 | All AI pipeline messages | +| `orders` | `orders` | 5 | 1 s × 2 | OrderReceivedMessage | +| `channel_sync`| `channel_sync` | 5 | 2 s × 2 ≤ 60 s | Publish/UpdateStock/Deactivate/TrackingPush | +| `failed` | `failed` | — | — | Dead-letter after max retries exhausted | + +**`PipelineJobFailureListener`** (`Infrastructure/Messenger/PipelineJobFailureListener.php`): listens for `WorkerMessageFailedEvent`, extracts `jobId` from message if available, calls `job.markFailed(...)`. + +**Workers** (run separately per transport in prod): +``` +bin/console messenger:consume ai_pipeline --time-limit=3600 +bin/console messenger:consume orders --time-limit=3600 +bin/console messenger:consume channel_sync --time-limit=3600 +``` + +--- + +## 8. Authentication + +**Browser sessions:** Symfony form login + TOTP 2FA (`scheb/2fa-bundle`). Setup flow: `TotpSetupController`. Password change: `ChangePasswordController`. + +**API requests:** Custom `ApiKey` authenticator. Clients send `X-Api-Key: ` header. The authenticator loads `ApiKey` by user email extracted from the JWT-style key prefix, verifies bcrypt hash. + +**PermissionVoter:** `Infrastructure/Http/Security/` — checks `ApiKey.permissions` array against voted attribute strings. + +**Console commands for key management:** +``` +bin/console app:create-user +bin/console app:create-api-key [--permissions=read,write] +``` + +--- + +## 9. EasyAdmin Structure + +**Dashboard:** `Infrastructure/Http/Controller/Admin/DashboardController` — uses `#[AdminDashboard]` attribute, builds menu with `MenuItem::subMenu()` per adapter section. + +**Navigation sections:** +- Artikel (ArticleType, Article, AttributeDefinition, Photo ingest, Pipeline jobs) +- Bestellungen (Order, Customer, Invoice) +- eBay (EbayArticleTypePlatformConfigCrudController) +- System (User, ApiKey, PromptTemplate, Translation, Logs) + +**EbayArticleTypePlatformConfigCrudController:** filters index to `platform.type = 'ebay'` via custom `createIndexQueryBuilder`. Renders ChoiceField (live policy list) or TextField fallback depending on `EbayPolicyProvider` availability. + +**ArticleTypeCrudController:** overrides `persistEntity`/`updateEntity` to call `applyAttributeAssignments()` before flush. + +**EbayAspectImportController:** action button in ArticleType CRUD that fetches eBay Taxonomy aspects for the type's `ebayCategoryId` and upserts `ArticleTypeEbayMapping` rows. + +--- + +## 10. Database / Doctrine + +- PostgreSQL 17, three schemas: `app` (main data), `logs` (log_entries), `logs_archive` (rotated, excluded from migrations) +- `schema_filter` in `doctrine.yaml` excludes `logs_archive.*` and `app.inventory_seq` +- All entity tables are in schema `app` (set via `#[ORM\Table(schema: 'app')]`) +- UUIDs generated with `Uuid::v7()` in constructors (time-ordered) +- `decrementStockAtomic` uses a raw SQL UPDATE with `WHERE stock > 0` for race-free stock locking + +**Migrations:** `bin/console doctrine:migrations:migrate --no-interaction`. Never use `doctrine:schema:update` in prod. + +--- + +## 11. AI / LLM Backend + +All AI traffic goes through Mistral Cloud API. The interface is named `OllamaClientInterface` for historical reasons — the DI alias points to `MistralClient`. + +| Role | Model | Agent class | +|--------------|---------------------------|-----------------------| +| Vision | `pixtral-12b-2409` | `OllamaVisionAgent` | +| Specs / text | `mistral-large-latest` | `SpecsResearchAgent`, `JsonCodingAgent`, `EbayTextAgent` | + +Web search: `WebSearchInterface` → `TavilyWebSearch` (Tavily API). Used inside `SpecsResearchAgent` to augment specs lookup. + +Prompt templates are stored in the database (`app.prompt_templates`) and loaded by `PromptTemplateService`. Edit them live via the admin UI. + +--- + +## 12. Key Gotchas + +**Routing prefix:** API controllers must declare `/api` prefix in the class-level `#[Route('/api/...')]`, NOT via yaml prefix config — Symfony's yaml prefix mechanism conflicts with attribute routing in this setup. + +**`OllamaClientInterface` / `OllamaClient`:** These classes still exist but the DI alias points to `MistralClient`. Do not instantiate `OllamaClient` directly. + +**`EbayAdapter` requires `ArticleTypePlatformConfig`:** If no config row exists for an ArticleType+eBay combination, `publishListing` throws `\RuntimeException`. Create the config via Admin → eBay → Kategorie-Konfigurationen first. + +**`ArticleType::applyAttributeAssignments()`:** Must be called before Doctrine flush whenever the EasyAdmin form sets `pendingRequired`/`pendingOptional`. Forgetting this leaves the DB unchanged silently. + +**Docker user 1000:1000 / HOME=/tmp:** All PHP containers run as UID 1000:1000 with `HOME=/tmp`. Composer cache, Symfony cache, and file writes must target paths writable by that user. + +**`schema_filter` excludes `logs_archive.*`:** Running `doctrine:migrations:diff` will NOT see the archive schema. Never manually create Doctrine entities targeting `logs_archive`. + +**`ArticleTypeEbayMapping` aspect name uniqueness:** Enforced by `uq_ebay_mapping` DB constraint AND `upsertEbayMapping()` helper. Always go through the helper to avoid constraint violations. + +**EbayPolicyProvider cache TTL:** 300 seconds. During dev, policy dropdowns may show stale data. Clear the Symfony cache (`bin/console cache:clear`) or wait 5 minutes. + +--- + +## 13. Where to Find Things + +| What you need | Where | +|----------------------------------------|---------------------------------------------------------------------------------| +| Article domain entity | `src/Domain/Article/Article.php` | +| eBay aspect→Article field mapping | `src/Domain/Article/ArticleTypeEbayMapping.php` | +| Platform config (categoryId + policies)| `src/Domain/Channel/ArticleTypePlatformConfig.php` | +| eBay listing logic | `src/Infrastructure/Channel/Ebay/EbayAdapter.php` | +| eBay OAuth token | `src/Infrastructure/Channel/Ebay/EbayOAuthClient.php` | +| eBay policy dropdowns | `src/Infrastructure/Channel/Ebay/EbayPolicyProvider.php` | +| eBay taxonomy / aspect import | `src/Infrastructure/Channel/Ebay/EbayTaxonomyService.php` | +| All Messenger messages | `src/Infrastructure/Messenger/Message/` | +| All Messenger handlers | `src/Infrastructure/Messenger/Handler/` | +| Messenger routing | `config/packages/messenger.yaml` | +| AI agents | `src/Infrastructure/AI/Agent/` | +| Mistral HTTP client | `src/Infrastructure/AI/MistralClient.php` | +| Prompt templates (runtime) | `src/Infrastructure/AI/PromptTemplateService.php` + DB table `app.prompt_templates` | +| Order processing | `src/Infrastructure/Messenger/Handler/OrderReceivedHandler.php` | +| Stock sync / deactivate | `src/Infrastructure/Messenger/Handler/UpdateStockOnChannelsHandler.php` | +| Frappe ERP adapter | `src/Infrastructure/Channel/Frappe/FrappeErpAdapter.php` | +| Admin dashboard / nav | `src/Infrastructure/Http/Controller/Admin/DashboardController.php` | +| eBay admin config CRUD | `src/Infrastructure/Http/Controller/Admin/EbayArticleTypePlatformConfigCrudController.php` | +| API controllers | `src/Infrastructure/Http/Controller/Api/` | +| Webhook entry point | `src/Infrastructure/Http/Controller/Webhook/EbayWebhookController.php` | +| Auth / ApiKey | `src/Domain/Auth/ApiKey.php`, `src/Domain/Auth/User.php` | +| Doctrine migrations | `migrations/` | +| Service wiring | `config/services.yaml` | +| Transport config | `config/packages/messenger.yaml` | +| Admin translations (de/en) | `translations/admin.de.yaml`, `translations/admin.en.yaml` | +| Integration tests | `tests/Integration/` | +| Unit tests | `tests/Unit/` | +| Infra / prod setup | `docs/superpowers/specs/2026-05-19-infrastructure.md` |