update

doc/core-apps/ai_admin/features.md

@@ -0,0 +1,7 @@
+- ai_admin
+	- admin chat turns prompts or JSON bulk input into proposal cards; AI never executes directly
+	- routes: POST /ai/admin/plan, POST /ai/admin/execute (admin-only)
+	- cards carry tool name, args, missing fields (editable in UI), preview text
+	- execute validates args against tool JSON-schema, runs the tool, writes an audit-log entry
+	- depends on: core, auth, catalog, orders, ai_core
+	- room for growth: more tools (mail templates, bulk import, category mutation), undo history, approval levels, per-tool permissions, dry-run mode

doc/core-apps/ai_admin/specs.md

@@ -0,0 +1,4 @@
+- __init__.py (router, on_load)
+- planner.py (prompt/JSON → list of action cards)
+- tool_defs.py (JSON-schema per tool for argument validation)
+- manifest.yaml

doc/core-apps/ai_core/features.md

@@ -0,0 +1,7 @@
+- ai_core
+	- RAG infrastructure: LLMProvider interface + Ollama implementation, pgvector-backed document store, tool registry
+	- routes: POST /ai/query; admin: POST /ai/reindex, GET /ai/tools
+	- events subscribe: product.*, category.*, core.settings_updated (triggers embedding updates)
+	- depends on: core, catalog
+	- tools are proposals only — never executed directly; ai_admin turns them into confirmation cards
+	- room for growth: re-ranking, source citations, streaming responses, alternative LLM providers (OpenAI-compatible, Anthropic), chunking strategies, evaluation harness

doc/core-apps/ai_core/specs.md

@@ -0,0 +1,7 @@
+- __init__.py (router, on_load, tool registry)
+- models.py (AiDocument with pgvector column)
+- indexer.py (embed + upsert documents)
+- ollama_client.py (LLMProvider implementation)
+- tools.py (Tool base + registry)
+- reindex.py (full rebuild of embeddings)
+- manifest.yaml

doc/core-apps/ai_shop/features.md

@@ -0,0 +1,6 @@
+- ai_shop
+	- natural-language product search for customers; hybrid of embedding similarity and keyword boost
+	- routes: POST /ai/shop/search
+	- shop-aware system prompt (currency, user locale)
+	- depends on: core, catalog, ai_core
+	- room for growth: conversational follow-ups, session memory, filter parsing (price, size, color), spell correction, personalized ranking

doc/core-apps/ai_shop/specs.md

@@ -0,0 +1,2 @@
+- __init__.py (router, on_load)
+- manifest.yaml

doc/core-apps/auth/features.md

@@ -0,0 +1,7 @@
+- auth
+	- registration, login, refresh, logout, password change, own profile
+	- routes: POST /register, /login, /refresh, /logout, /change-password; GET/PUT /me
+	- events emit: user.registered, user.logged_in
+	- depends on: core
+	- seeds: admin@example.com + demo customer
+	- room for growth: OAuth/SSO, API-tokens for third-party apps, 2FA, refresh-token rotation, impersonation, B2B company accounts

doc/core-apps/auth/specs.md

@@ -0,0 +1,3 @@
+- __init__.py (router, on_load)
+- models.py (User, RefreshToken)
+- manifest.yaml

doc/core-apps/cart/features.md

@@ -0,0 +1,5 @@
+- cart
+	- per-user shopping cart, read/write items
+	- routes: GET /cart, POST /cart/items, PUT /cart/items/{id}, DELETE /cart/items/{id}
+	- depends on: core, auth, catalog
+	- room for growth: guest cart (session-based), merge guest cart into user cart on login, saved carts / wishlists, price snapshotting at add-time

doc/core-apps/cart/specs.md

@@ -0,0 +1,3 @@
+- __init__.py (router, on_load)
+- models.py (Cart, CartItem)
+- manifest.yaml

doc/core-apps/catalog/features.md

@@ -0,0 +1,7 @@
+- catalog
+	- products and categories, DE/EN i18n fields, image upload (local storage today)
+	- public routes (read from redis): GET /products, /products/{id}, /categories
+	- admin routes: POST/PUT/DELETE /admin/products, /admin/categories, image upload endpoint
+	- events emit: product.created, product.updated, product.deleted, category.created, category.updated, category.deleted
+	- depends on: core, auth
+	- room for growth: product variants, attributes/tags, SEO slugs, pluggable image storage (S3), stock reservations, price lists (B2B)

doc/core-apps/catalog/specs.md

@@ -0,0 +1,4 @@
+- __init__.py (router, on_load)
+- models.py (Product, Category)
+- projector.py (redis sync on product/category events)
+- manifest.yaml

doc/core-apps/checkout/features.md

@@ -0,0 +1,6 @@
+- checkout
+	- validate cart, take address + payment selection, produce order via payment provider
+	- routes: POST /checkout/preview, POST /checkout/confirm
+	- events emit: checkout.confirmed
+	- depends on: core, auth, catalog, cart, payment
+	- room for growth: coupon slot, shipping-method slot, tax plug-in point, address book, guest checkout, order-draft persistence

doc/core-apps/checkout/specs.md

@@ -0,0 +1,2 @@
+- __init__.py (router, on_load)
+- manifest.yaml

doc/core-apps/features.md

@@ -0,0 +1,6 @@
+- core-apps
+	- shipped with the system, required for a functional shop
+	- same mechanics as any other app (manifest.yaml, router, migrations, events, DI) — no special status in the loader
+	- typically declared `required: true` in manifest so they cannot be switched off
+	- distinct from custom-apps (optional / third-party, not shipped)
+	- cover: auth, product catalog, cart, checkout, payment, orders, mail, shipment (planned), plus the AI layer (ai_core, ai_shop, ai_admin)

doc/core-apps/mail/features.md

@@ -0,0 +1,6 @@
+- mail
+	- MailProvider service registered via DI; SMTP implementation (Mailhog in dev, real SMTP in prod)
+	- Jinja2 templates with DE/EN i18n
+	- no public routes — used by other apps (e.g. orders) through DI
+	- depends on: core
+	- room for growth: outbound queue with retries, provider abstraction (SendGrid, Postmark, SES), richer transactional templates, bounce/complaint handling

doc/core-apps/mail/specs.md

@@ -0,0 +1,2 @@
+- __init__.py (on_load, MailProvider, SMTP implementation)
+- manifest.yaml

doc/core-apps/orders/features.md

@@ -0,0 +1,7 @@
+- orders
+	- customer-facing order list + detail, admin-side management with status transitions
+	- routes: GET /orders, GET /orders/{id}; admin: GET /admin/orders, PUT /admin/orders/{id}/status
+	- events subscribe: checkout.confirmed (create order, trigger confirmation mail)
+	- events emit: order.created, order.status_changed
+	- depends on: core, auth, catalog, mail
+	- room for growth: returns, partial fulfillment, cancellations, invoice PDFs, shipment tracking, export (CSV/ERP)

doc/core-apps/orders/specs.md

@@ -0,0 +1,3 @@
+- __init__.py (router, on_load, event subscribers)
+- models.py (Order, OrderItem, OrderStatusHistory)
+- manifest.yaml

doc/core-apps/payment/features.md

@@ -0,0 +1,5 @@
+- payment
+	- PaymentProvider interface + DummyPayment (always "paid") for dev
+	- routes: GET /payment/methods
+	- depends on: core
+	- room for growth: real providers as separate apps (Stripe, Mollie, Klarna, PayPal), refund API, webhook handling, 3DS/SCA flow, split payments

doc/core-apps/payment/specs.md

@@ -0,0 +1,2 @@
+- __init__.py (router, on_load, DummyPayment provider)
+- manifest.yaml

doc/core-apps/specs.md

@@ -0,0 +1,11 @@
+- auth
+- catalog
+- cart
+- checkout
+- payment
+- orders
+- mail
+- ai_core
+- ai_shop
+- ai_admin
+- shipment (planned, not implemented)

doc/core/authentication/features.md

@@ -0,0 +1,6 @@
+- authentication
+	- "who are you?"
+	- password hashing with argon2
+	- JWT (15 min access) with refresh (30 days)
+	- identity dependencies (current_user_claims, optional_user, get_current_user_id, oauth2_scheme)
+	- room for growth: OAuth/SSO, API-tokens for third-party apps, 2FA, refresh-token rotation, impersonation

doc/core/authentication/specs.md

@@ -0,0 +1 @@
+- authentication.py

doc/core/authorization/features.md

@@ -0,0 +1,4 @@
+- authorization
+	- "what are you allowed to do?"
+	- role checks (require_admin today)
+	- room for growth: require_role, require_permission, per-resource checks (owner-of), B2B approval workflows, per-app permissions for marketplace apps

doc/core/authorization/specs.md

@@ -0,0 +1 @@
+- authorization.py

doc/core/cache/features.md

@@ -0,0 +1,5 @@
+- cache
+	- shared read-store / cache client (Redis today)
+	- backend writes, frontend reads
+	- apps keep the cache in sync via event handlers (projectors), not the core client
+	- room for growth: CacheProvider abstraction so the read-store becomes swappable

doc/core/cache/specs.md

@@ -0,0 +1 @@
+- cache.py

doc/core/config/features.md

@@ -0,0 +1,2 @@
+- config
+	- read .env into Settings object

doc/core/config/specs.md

@@ -0,0 +1 @@
+- config.py

doc/core/db/features.md

@@ -0,0 +1,4 @@
+- db
+	- base setup for ORM
+	- use SQLAlchemy
+	- provide get_db() dependency

doc/core/db/specs.md

@@ -0,0 +1 @@
+- db.py

doc/core/di/features.md

@@ -0,0 +1,3 @@
+- di
+	- global register for services
+	- no direct service import between apps

doc/core/di/specs.md

@@ -0,0 +1 @@
+- di.py

doc/core/events/features.md

@@ -0,0 +1,5 @@
+- events
+	- apps can react on events
+	- apps can emit events
+	- events persist in db (audit/replay)
+	- allow wildcard subscribe (e.g. product.*)

doc/core/events/specs.md

@@ -0,0 +1 @@
+- events.py

doc/core/i18n/features.md

@@ -0,0 +1,2 @@
+- i18n
+	- internationalisation helper for DE/EN text fields

doc/core/i18n/specs.md

@@ -0,0 +1 @@
+- i18n.py

doc/core/loader/features.md

@@ -0,0 +1,6 @@
+- loader
+	- load apps as python module
+	- discover apps/*/manifest.yaml
+	- order by app dependency (topological sort), circles not allowed
+	- check for conflicts
+	- mount each app router under /api/<app>

doc/core/loader/specs.md

@@ -0,0 +1 @@
+- loader.py

doc/core/main/features.md

@@ -0,0 +1,5 @@
+- main
+	- entrypoint for backend
+	- build fastAPI
+	- run loader on lifespan startup
+	- expose /health and core settings routes

doc/core/main/specs.md

@@ -0,0 +1 @@
+- main.py

doc/core/middleware/features.md

@@ -0,0 +1,4 @@
+- middleware
+	- central place to install FastAPI middlewares (install_middlewares(app))
+	- today: CORS (allowed origins from .env)
+	- room for growth: request-id, access logging, rate-limit, security headers (HSTS/CSP), compression

doc/core/middleware/specs.md

@@ -0,0 +1 @@
+- middleware.py

doc/core/migrations/features.md

@@ -0,0 +1,5 @@
+- migrations
+	- orchestrator (migrations.py): discover per-app migration folders (apps/<name>/migrations/), configure alembic version_locations dynamically, coordinate multi-head merging
+	- startup check: fail fast if schema is not up to date
+	- migrations/ directory: alembic version store (today still holds all migrations centrally; per-app folders are the target state)
+	- use alembic

doc/core/migrations/specs.md

@@ -0,0 +1,2 @@
+- migrations.py
+- migrations/ (Alembic version store)

doc/core/seed/features.md

@@ -0,0 +1,2 @@
+- seed
+	- demo data (admin, demo customer, categories, products)

doc/core/seed/specs.md

@@ -0,0 +1 @@
+- seed.py

doc/core/settings/features.md

@@ -0,0 +1,6 @@
+- settings
+	- key-value store for shop settings (runtime-changeable, e.g. shop_name, currency)
+	- postgres is source of truth
+	- mirrored to redis on write
+	- emits core.settings_updated event
+	- distinct from config (which only reads .env infrastructure values)

doc/core/settings/specs.md

@@ -0,0 +1 @@
+- settings.py

doc/custom-apps/features.md

@@ -0,0 +1,7 @@
+- custom-apps
+	- not shipped with the system; installed on top
+	- same mechanics as core-apps (manifest, router, migrations, events, DI) — loader does not distinguish
+	- typically declared required: false → can be switched off; can declare conflicts_with to prevent incompatible pairs
+	- two categories: optional apps (same team, shipped later) and third-party apps (marketplace, external developers)
+	- planned optional apps (from base.md): wishlist, reviews, coupons / discount engine, product recommendations, multi-vendor, subscriptions
+	- room for growth: app signing / verification, loader version-compat checks, per-app permission declarations, isolated migration namespaces, install/uninstall lifecycle hooks, marketplace registry

doc/custom-apps/specs.md

@@ -0,0 +1,7 @@
+- manifest.yaml (name, version, depends_on, conflicts_with, required: false, provides)
+- __init__.py (router: APIRouter, optional on_load() for event handlers / DI registration)
+- models.py (optional, with own SQLAlchemy Base subclass)
+- projector.py (optional, redis read-store sync via event handlers)
+- migrations/ (optional, alembic version files discovered by core migrations orchestrator)
+- i18n/ (optional, DE/EN strings)
+- frontend components under frontend/shop and/or frontend/admin (optional)

doc/features.md

@@ -2,4 +2,3 @@
 - AI search: Filter products by search with AI
 - AI admin helper: Execute commands by description 
 - Products, Orders, Users, Events, Settings
-- 

doc/specs.md

@@ -1,15 +1,12 @@
-- pyhton: backend language 
+- python: backend language 
 - fastAPI: Rest-API framework, Async, OpenAPI Docs
 - Pydantic: Validate API 
 - SQLAlchemy: ORM
 - Alembic: Migrations
 - Postgres: Relational database 
 - pgvector: Vector columns for search, RAG search
-- Redis: Cache for backend-frontend comminication 
+- Redis: Cache for backend-frontend communication 
 - Ollama: LLM for chat / planning and LLM for embeddings
 - Vue: Frontend and admin framework with router and pinia as SPA
 - Meilisearch: Search server with fulltext
-- Mailhog: Dummy mailing 
-
-App-Loader, DI, Event-Bus, Settings, Redis-Projektor, Security, Seed
-auth, catalog, cart, checkout, payment, orders, mail, ai_core, ai_shop, ai_admin, hello
+- Mailhog: Dummy mailing