SuperSeller3000/docs/architecture.md

# 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: <raw-secret>` 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 <email> <password>
bin/console app:create-api-key <user-email> <description> [--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`                           |