# Konzept: Skalierbare Subdomain-Architektur für kotsch.tech

- **Datum:** 2026-06-09
- **Status:** Freigegeben (Konzept) → bereit für Umsetzungsplan
- **Autor:** Arthur Kotsch + Claude
- **Topic:** Umbau der Laravel-Monolith-App in eine registry-getriebene Subdomain-Architektur mit gemeinsamem Design-System

---

## 1. Ziel & Vision

kotsch.tech wird von einer pfadbasierten Single-Domain-Site (`kotsch.tech/webtools`, `/apple`, …) zu einer **skalierbaren Subdomain-Architektur** umgebaut: jeder inhaltliche Bereich bekommt seine eigene Subdomain (`webtools.kotsch.tech`, `ios.kotsch.tech`, …), während die nackte Domain `kotsch.tech` zum **zentralen Hub** wird, von dem aus man alles perfekt erreicht — und zu dem man von überall zurückkommt.

**Leitprinzipien:**
1. **Maximal skalierbar** — neue Subdomain = ein Registry-Eintrag, keine Infrastruktur-Arbeit.
2. **Eine App, ein Deploy** — kein Microservice-Albtraum; Subdomains sind ein Routing-/Präsentations-Thema, kein Infra-Thema.
3. **Risikofrei für SEO/AdSense** — Parallelbetrieb: alte URLs bleiben gültig, Subdomain wird Canonical.
4. **Markenfamilie** — geteilte Design-DNA + eigener Akzent pro Subdomain; **kein generischer KI-Look**.

---

## 2. Getroffene Entscheidungen (verbindlich)

| # | Frage | Entscheidung |
|---|---|---|
| 1 | SEO-Migration | **Parallelbetrieb** — alte Pfade + Subdomain beide gültig, Subdomain = Canonical, keine 301 in Phase 1 |
| 2 | Umfang | **Voller Umzug** — alle Bereiche werden Subdomains |
| 3 | Hub | **Beides** — neue Hub-Startseite **und** globale Navigation auf jeder Subdomain |
| 4 | Endergebnis dieser Phase | **Konzept + Plan zuerst**, Umsetzung nach Freigabe |
| 5 | Technische Architektur | **Zentrale Registry** (`config/subdomains.php`) speist Routing, Canonical, Navigation, Hub, Sitemaps |
| 6 | iOS-Subdomain | `ios.kotsch.tech` |
| 7 | News-Subdomain | `news.kotsch.tech` |
| 8 | Extra-Subdomains | `admin.kotsch.tech` **ja**; `dokumente` bleibt auf dem Hub |
| 9 | Apex vs. www | **Apex** (`kotsch.tech`) = Hub; `www` → 301 |
| 10 | Shop-Konflikt | Laravel-Shop bekommt `shop.kotsch.tech`; „AI Creator Shop" zieht auf `ai-shop.kotsch.tech` |
| 11 | Tunnel-Routing | **Wildcard** `*.kotsch.tech → localhost:85` + Carve-outs für bestehende Separat-Apps |
| 12 | Design-Richtung | Geteilte DNA + Akzent-Layer + Anti-KI-Doktrin (freigegeben) |

---

## 3. Ist-Zustand (verifiziert)

- **Stack:** Laravel 12 (PHP 8.2+), eine App, `DocumentRoot C:/xampp/htdocs/kotsch.tech/kotsch-tech/public`.
- **Serving:** Cloudflare → **cloudflared-Tunnel** (remote-managed, Token; Tunnel-ID `976872d1-cdcd-46c2-90ce-e7c828a4698b`) → **Apache/XAMPP** auf **Port 85** (`<VirtualHost *:85>`, `ServerName localhost`). Requests erreichen Laravel über Loopback (`::1`); `TrustProxies` steht bereits auf `*`.
- **Port-85-vhost ist ein Port-Catch-all** → er beantwortet *jeden* Host-Header auf Port 85. **Daher ist keine Apache-Änderung nötig.**
- **Sessions:** `SESSION_DRIVER=database` (zentral in DB), `SESSION_DOMAIN` aktuell `null`.
- **i18n:** pfadbasiert (`/de/...`, `/en/...`) via `LocalizedPageController` (Sub-Request-Dispatch) + Catch-all `/{locale}/{path?}`. HTML-Post-Processing für EN via `EnglishHtmlLocalizer`.
- **SEO heute:** eine `/sitemap.xml` (alle Pfade + de/en), `/robots.txt`, Canonical-Basis aktuell `www.kotsch.tech`.
- **Bereits existierende Separat-Apps** (eigene Ports, **nicht** Teil der Laravel-App): `files.kotsch.tech` (:8081), `shop.kotsch.tech`→AI Creator Shop (:8082), `invoice.kotsch.tech` (:8083), `aitools.kotsch.tech` (:8084), `mail.kotsch.tech` (:443, Roundcube).

---

## 4. Subdomain-Landkarte (Soll)

### 4.1 Hub — `kotsch.tech` (Apex)
Launchpad-Startseite + globale Bauteile. Bleibt direkt hier:
- Recht: `/impressum`, `/datenschutz`, `/agb`
- `/kontakt` (zentrales Formular)
- `/dokumente` (wissenschaftliche PDFs)
- Technische Endpunkte: `/go`, `/p/{token}` (PDF-Teilen), `/download/{app}`, `/csrf-token`
- SEO-Steuerung: `/sitemap.xml` (→ Sitemap-Index), `/robots.txt`, `/ads.txt`
- `index1`–`index20` (Varianten, `noindex`)
- `www.kotsch.tech` → 301

### 4.2 Laravel-Subdomains (alle = dieselbe App auf :85)

| Subdomain | Basis-Pfad | Inhalt | Umfang |
|---|---|---|---|
| `ios.kotsch.tech` | `/apple` | iOS-/Apple-Apps | 13 Apps (mehrere live im App Store) + 2 macOS-Apps |
| `windows.kotsch.tech` | `/windows` | Windows-Programme | 9 Programme |
| `android.kotsch.tech` | `/android` | Android-Apps | dynamisch (in Vorbereitung) |
| `webtools.kotsch.tech` | `/webtools` | Online-Tools | 220+ Tools |
| `shop.kotsch.tech` | `/shop` | Laravel-Shop | 11 Produkte + Checkout/PayPal |
| `hosting.kotsch.tech` | `/hosting` | Hosting | Übersicht, Web, vServer |
| `news.kotsch.tech` | `/news` | Artikel & Ratgeber | AdSense-Inhalte |
| `it-hilfe.kotsch.tech` | `/it-hilfe` | IT-Support | + `/support` |
| `webdesign.kotsch.tech` | `/webdesign` | Webdesign-Studio | Studio + ~22 Demos |
| `admin.kotsch.tech` | `/admin` | Admin-Panel | Dashboard, Shop-Verwaltung, 2FA · `noindex` |

### 4.3 Bestehende Separat-Apps (unverändert, nur `shop`→`ai-shop` umbenannt)
`files` (:8081) · `ai-shop` (:8082) · `invoice` (:8083) · `aitools` (:8084) · `mail` (:443)

> **Skalierung:** Durch die Wildcard ist jede künftige Subdomain (`mac.`, `ki.`, …) nur ein Registry-Eintrag entfernt.

---

## 5. Architektur (registry-getrieben)

### 5.1 Die Registry — `config/subdomains.php` (einzige Wahrheitsquelle)

```php
return [
    'webtools' => [
        'host'       => 'webtools.kotsch.tech',
        'base'       => '/webtools',          // Pfad-Prefix → Parallelbetrieb
        'label'      => 'Web-Tools',
        'tagline'    => '220+ kostenlose Online-Tools',
        'icon'       => 'wrench',
        'accent'     => '#0FB5C9',            // Tier-1-Token (Design)
        'accent_2'   => null,
        'font_display' => 'JetBrains Mono',
        'motif'      => 'gears',              // 3D-Signatur
        'sitemap'    => 'webtools',
        'nav_group'  => 'tools',
        'index'      => true,                 // erscheint auf dem Hub
        'noindex'    => false,
    ],
    // … 1 Eintrag pro Subdomain
];
```

Diese Datei speist: Routing · Canonical · globale Navigation · Hub-Kacheln · Sitemaps/robots/ads.txt · Analytics-Labels · **Design-Tokens**.

### 5.2 Drei kleine Bausteine (je eine Aufgabe)

**`app/Http/Middleware/ResolveSubdomain.php`** — „welcher Inhalt?"
Liest den Host, schlägt in der Registry nach, stellt dem bestehenden Routing den `base`-Pfad voran — per Sub-Request (analog `LocalizedPageController`). `webtools.kotsch.tech/farb-konverter` → intern `/webtools/farb-konverter`. Locale bleibt vorn (`/en/...` → `/en/webtools/...`). Schleifenschutz: wenn Pfad bereits mit `base` beginnt, überspringen. **Null Routen-Duplikate.**

**`app/Http/Middleware/CanonicalUrl.php`** — „was sagt Google?"
Setzt in jeder HTML-Antwort den `<link rel="canonical">` auf die Subdomain-URL (Registry-Rückwärts-Mapping Pfad→Host) — auf beiden Versionen. HTML-Post-Processing analog `EnglishHtmlLocalizer`.

**`app/Providers/SubdomainServiceProvider.php`** — verdrahtet Registry → Middleware, Blade-Helfer (`subdomain_url()`), View-Composer für Nav/Canonical/Design-Tokens.

### 5.3 Session & Sicherheit
- `.env`: `SESSION_DOMAIN=.kotsch.tech` → Login (Admin) & Warenkorb (Shop) gelten subdomain-übergreifend (DB-Sessions sind bereits zentral; kein Logik-Umbau).
- `TrustHosts` auf `^(.+\.)?kotsch\.tech$` → Host-Header-Spoofing-Schutz.
- Hinweis: Der Session-Cookie ist damit für alle Subdomains lesbar. Akzeptabel (ein Owner, `http_only`); Admin bleibt funktional auf eigener Subdomain.

### 5.4 Geänderte / neue Dateien
- **Neu:** `config/subdomains.php`, `app/Http/Middleware/ResolveSubdomain.php`, `app/Http/Middleware/CanonicalUrl.php`, `app/Providers/SubdomainServiceProvider.php`, `app/Support/SubdomainRegistry.php` (Helfer)
- **Geändert:** `bootstrap/app.php` (Middleware + TrustHosts), `.env` (SESSION_DOMAIN), `routes/web.php` (ads.txt/sitemap-index-Routen, host-bewusste robots), Layouts (Nav/Footer/Canonical/Design-Tokens-Einbindung)
- **Unangetastet:** die 700+ bestehenden Views & die fachlichen Controller/Routen

---

## 6. Infrastruktur

### 6.1 Cloudflare Tunnel (im Zero-Trust-Dashboard, da remote-managed)
- **Wildcard-Public-Hostname** `*.kotsch.tech` → Service `http://localhost:85`.
- **Carve-outs (spezifischer → Vorrang):** `files`→:8081, `ai-shop`→:8082, `invoice`→:8083, `aitools`→:8084, `mail`→:443. `shop` wird (neu) auf :85 geroutet.
- Voraussetzung Wildcard: DNS-CNAME `*.kotsch.tech` (proxied) auf den Tunnel. Apex + `www` ebenfalls auf den Tunnel; `www`→301 via Cloudflare-Redirect-Rule.

### 6.2 DNS & TLS
- Cloudflare **Universal SSL** deckt `kotsch.tech` + `*.kotsch.tech` (eine Wildcard-Ebene) → alle Subdomains abgedeckt, kein Zertifikats-Aufwand.
- Tunnel verschlüsselt Edge→Origin; Origin-Service plain HTTP auf `localhost:85` genügt.

### 6.3 Apache
- **Keine Änderung nötig** (der `*:85`-vhost ist Port-Catch-all). Optionale Härtung später: dedizierter vhost mit `ServerName kotsch.tech` + `ServerAlias *.kotsch.tech` zur Klarheit/Logging.

### 6.4 Fallback
Falls Wildcard im remote-managed Tunnel Probleme macht: pro Subdomain einen expliziten Public-Hostname → :85 anlegen (mehr Klicks, gleiche Funktion).

---

## 7. Design-System

### 7.1 Anti-KI-Doktrin (recherche-belegt)
Kernregel: **konkrete Constraints statt vager Beschreibungen.**

| KI-Verräter | Gegenmittel |
|---|---|
| Inter/Roboto/System-Fonts | Charaktervolle Schrift-Paarung; extreme Weight-/Größenkontraste |
| Lila→Blau-Verlauf auf Weiß | Entschlossene Hell-Paletten; Farbe semantisch |
| Zentrierter Hero + 2 Buttons | Editoriales/asymmetrisches (Broken-Grid-)Layout |
| 3 Icon-Karten im Raster | Split-Screen, Pull-Quotes, versetzte Reveals |
| Generische 3D-Blobs | Maßgeschneiderte 3D-Szenen pro Subdomain |
| Überall 16px-Radius + 0.1-Schatten | Eigene, konsequente Form-/Schatten-Sprache |
| Vage Claims | Konkrete Texte in Arthurs Stimme |

> **Vorgaben beachten:** nur Hell (kein Dark-Mode), Heavy-3D als Marken-Signatur, Inhalte unverändert. Anti-KI = *entschlossene* Farben, nicht dunkel.

### 7.2 Geteilte DNA (auf jeder Subdomain identisch)
Raster-Prinzip, Spacing-Rhythmik, Body-Font, Komponenten-Formen, 3D-Bewegungssprache, globale Nav, Footer, Licht-Theme.

### 7.3 Akzent-Layer (3-Stufen-Tokens, aus der Registry)
```
Tier 1  --accent: <registry>     → Tier 2  --color-action: var(--accent)
                                  → Tier 3  --button-bg: var(--color-action)
```
Eine Basis-Stylesheet + pro Subdomain `:root`-Overrides (via `data-subdomain` / Inline-Custom-Props aus der Registry).

### 7.4 Identitäten pro Subdomain

| Subdomain | Akzent | Persönlichkeit | Display-Font | 3D-Signatur |
|---|---|---|---|---|
| Hub | `#FF5D2E` Vermillion / Papier `#F6F4EF` | Dachmarke | Clash Display | Konstellation aller Motive |
| ios | `#0A84FF` / Graphit | Premium, luftig | Cabinet Grotesque | Glas-App-Kacheln |
| windows | `#1B6CF2` / Stahl | Engineered | Space Grotesk | Gekippte Fenster-Ebenen |
| android | `#19C37D` | Verspielt | Clash Display | Modulare Roboter-Blöcke |
| webtools | `#0FB5C9` / Millimeterpapier | Werkstatt | JetBrains Mono + Sans | Zahnräder/Wireframes |
| shop | `#0F8A4F` + Gold `#C8962B` / Creme | Hochwertig | Fraunces + Sans | Produkt auf Podest |
| hosting | `#14B8A6` / Carbon | Schnell, verlässlich | Space Grotesk | Server-Rack/Datenflüsse |
| news | `#F4B41A` Amber / Zeitungsweiß | Redaktionell | Fraunces (Serif) | Faltendes Papier |
| it-hilfe | `#FF7A45` Coral | Menschlich | Cabinet Grotesque | Helfer-Schild |
| webdesign | `#E6259A` Magenta + Cyan | Kreativ, mutig | Bricolage Grotesque | Morphende Swatches |
| admin | `#64748B` Slate | Funktional | IBM Plex Sans | — |

Body-Font durchgehend gleich (z.B. Satoshi/Source Sans 3 — lesbar, nicht-KI).

---

## 8. SEO

| Baustein | Konzept |
|---|---|
| Canonical | Ein `<link rel="canonical">` → Subdomain-URL, auf beiden Versionen. Hub-Seiten → Apex. |
| Sitemaps | Pro Subdomain eigene `/sitemap.xml`; Apex `/sitemap.xml` wird Sitemap-Index. Registry-getrieben. |
| robots.txt | Pro Host, Verweis auf eigene Sitemap. `admin.` → `Disallow: /` + `noindex`. |
| `ads.txt` | Host-übergreifende Route liefert dieselbe `ads.txt` auf jeder Subdomain (**AdSense-Pflicht**). |
| hreflang | de/en-Alternates zeigen auf Subdomain-Varianten, konsistent mit Canonical. |
| Search Console | Eine **Domain-Property** (`kotsch.tech`, DNS-TXT) deckt Apex + alle Subdomains ab. Sitemap-Index einreichen. |
| www→Apex | 301 via Cloudflare-Redirect-Rule. |
| Phase 2 (optional) | Nach bestätigter Indexierung: alte Pfade 301 → Subdomain für maximale Konsolidierung. |

---

## 9. Hub & globale Navigation

- **Globale Nav (jede Subdomain):** Logo→Hub, Bereichs-Switcher (Mega-Menü, aktuelle Subdomain in Akzentfarbe), de/en-Umschalter, Kontakt-CTA. Technisch **namespaced**, um den früheren `nav{fixed}`-Konflikt zu vermeiden.
- **Hub-Startseite:** Hero = 3D-Konstellation; Launchpad-Kacheln im gebrochenen Raster (Akzent + 3D-Mini-Szene + Tagline + Live-Zahl); dynamische Schaufenster (news/shop/apps aus DB).
- **Footer (geteilt):** Verzeichnis aller Subdomains + Recht + Kontakt (stärkt interne Verlinkung).

---

## 10. Rollout-Phasen

**Phase 0 — Vorbereitung (kein Live-Effekt)**
- Registry `config/subdomains.php` anlegen (alle 10 Subdomains + Hub).
- `SubdomainRegistry`-Helfer + Unit-Test.

**Phase 1 — Routing & Session (1 Subdomain als Pilot, z.B. `webtools`)**
- `ResolveSubdomain`-Middleware + `bootstrap/app.php` einhängen.
- `SESSION_DOMAIN=.kotsch.tech`, `TrustHosts`.
- Tunnel: Wildcard `*.kotsch.tech`→:85 + Carve-outs; `shop`→:85; `ai-shop` anlegen; `www`→301.
- Verifikation am Pilot, dann restliche Subdomains (reine Registry-Einträge).

**Phase 2 — SEO**
- `CanonicalUrl`-Middleware; per-Subdomain Sitemaps + Sitemap-Index; host-bewusste `robots.txt`; `ads.txt`-Route; hreflang. Search-Console-Domain-Property + Sitemap-Einreichung.

**Phase 3 — Design-System**
- Token-Basis + Akzent-Overrides aus Registry; geteilte Nav/Footer/Layout; Anti-KI-Refactor der Schlüssel-Templates. (Hier `frontend-design`/`taste-skill` einsetzen.)

**Phase 4 — Hub-Startseite**
- Neue Launchpad-Startseite + dynamische Schaufenster.

**Phase 5 (optional, später)** — 301 Pfad→Subdomain nach bestätigter Indexierung.

---

## 11. Testing & Verifikation

- **Unit:** Registry-Lookups (Host→base, Pfad→Canonical), Schleifenschutz.
- **Feature:** `webtools.kotsch.tech/farb-konverter` rendert dieselbe View wie `/webtools/farb-konverter`; Canonical zeigt auf Subdomain auf *beiden*; `/en/...` funktioniert; admin auf `admin.` mit Login; Shop-Warenkorb über Subdomain-Wechsel hinweg erhalten.
- **SEO:** `ads.txt` auf jeder Subdomain erreichbar; per-Subdomain-Sitemap valide; Sitemap-Index referenziert alle; robots korrekt.
- **Browser-Verifikation** (preview_*): Pilot-Subdomain rendert, Konsole fehlerfrei, Nav-Switcher funktioniert.
- **Last/Smoke:** Wildcard fängt unbekannte Hosts → Hub/404 sauber.

---

## 12. Rollback

- **Tunnel:** Wildcard-Hostname entfernen → Subdomains tot, Apex unverändert. Sofortiger Rollback.
- **Laravel:** Middleware in `bootstrap/app.php` auskommentieren → reiner Pfad-Betrieb wie heute. `SESSION_DOMAIN` zurück auf `null`.
- Da **Parallelbetrieb**, sind die alten Pfade nie abgeschaltet — null Datenverlust-/Ranking-Risiko.

---

## 13. Risiken & offene Punkte

- **Wildcard im remote-managed Tunnel:** falls nicht unterstützt → explizite Hostnames (Fallback 6.4).
- **Canonical-Kollision:** bestehende Views, die bereits `<link rel="canonical">` setzen, müssen erkannt/normalisiert werden (CanonicalUrl ersetzt statt dupliziert).
- **Locale × Subdomain:** Sub-Request-Verschachtelung (Subdomain-Rewrite + Locale-Rewrite) braucht sorgfältige Reihenfolge + Tests.
- **AdSense:** prüfen, ob die Subdomains in AdSense „Sites" erscheinen müssen oder per `ads.txt` automatisch abgedeckt sind.
- **macOS-Apps** unter `ios.` (OneBar, SmoothRide): bewusst akzeptiert; später ggf. `mac.kotsch.tech`.
- **Git:** Projekt ist aktuell **kein** Git-Repo → keine Versionierung/Commit des Specs möglich (optional `git init`).

---

## 14. Quellen (Anti-KI-Design-Recherche)
- prg.sh — *Why Your AI Keeps Building the Same Purple Gradient Website*
- 925studios — *AI Slop Web Design Guide 2026*
- Wix — *Avoid Generic AI Website Content*
- Shuffle — *Why Do Most AI-Generated Websites Look the Same?*
- Brad Frost — *The Many Faces of Themeable Design Systems*
- Frontend Masters — *Exploring Multi-Brand Systems with Tokens and Composability*