Architektur

Die Website ist eine Next.js-16-Anwendung (App Router), die beim Build als statisches HTML erzeugt wird, gestaltet mit der YuTheme-Designsprache, gehostet auf Vercel. Es gibt kein Server-Runtime.

Stack

• Next.js 16 (App Router, statische Generierung)
• React 19
• TypeScript
• pnpm (Paketmanager, Version via packageManager gepinnt)
• Turborepo-Monorepo (apps/, packages/)
• next-intl für die sieben Sprachen, localePrefix: as-needed
• YuTheme-Tokens und redaktionelle Konventionen (siehe design.md)
• Lucide-Icons via lucide-react
• Schriften: Geist Variable und Geist Mono Variable via next/font/local

Das einzige Client-JavaScript ist eine kleine Menge Hydration: das mobile Menü des Headers, Scrollspy, sanftes Anker-Scrolling und Scroll-Reveals.

Struktur

apps/web/src/
  app/
    [locale]/
      layout.tsx            Dokument-Shell, Fonts, Metadata, JSON-LD
      page.tsx              einseitige Homepage
      docs/page.tsx         Dokumentations-Index
      docs/[slug]/page.tsx  einzelne Dokumentationsseiten
      globals.css           YuTheme-Tokens, Basis-Styles, Motion
    sitemap.ts              Sitemap für alle Sprachen
    robots.ts
  components/
    Analytics.tsx           Umami-Hook, env-gesteuert, standardmäßig inert
    Footer.tsx
    Header.tsx              fixer Header, Scrollspy, mobile Schublade
    Icon.tsx                Lucide-Icon-Map, typisierte Namen
    Reveal.tsx              Scroll-Reveal via IntersectionObserver
    sections/
      Hero.tsx              Headline + Terminal-Karte
      About.tsx
      WhatIDo.tsx           Kartenraster
      HowIWork.tsx
      WhereILive.tsx
      SelectedWork.tsx      Liste öffentlicher Arbeiten
  data/site.ts              Site-Konstanten: URLs, Navigation
  i18n/                     Routing, Request-Config, typisierte Navigation
  lib/docs.ts               Markdown-Pipeline für Dokumentationsseiten
packages/
  content/                  docs/-Quellen, pro Sprache mit EN-Fallback
  i18n/                     Sprachliste + Messages der sieben Locales
  ui/styles/                kanonisches YuTheme-CSS, Token-Referenz

Lokalisierung

• Sprachen: en (Standard, ohne Präfix), pt, es, fr, de, ja, zh-CN.
• Der UI-Text lebt in packages/i18n/messages/<locale>.json.
• Die Dokumentation lebt in packages/content/docs/<locale>/; fehlt einer Sprache eine Datei, wird die englische Version als Fallback geliefert.
• Die Routen sind statisch: jede Sprache und jeder Doc-Slug wird beim Build über generateStaticParams vorgerendert.

Docs-Pipeline

Dokumentationsseiten lesen den Ordner packages/content/docs/ über packages/content/src/index.ts:

• jede Doc ist eine Markdown-Datei mit Frontmatter: title, description, order, updated;
• die App rendert sie mit remark/rehype (GFM, Slugs auf Headings, Autolinks, bereinigtes HTML) unter /docs/<slug>, mit Index unter /docs;
• @ellamizuki/content bleibt extern zum App-Bundle (serverExternalPackages), damit die Dateisystem-Lesezugriffe in Produktion funktionieren.

Weil die Sammlung denselben Ordner liest, der im Repository versioniert ist, bleiben die Docs synchron: eine Quelle der Wahrheit, zwei Ansichten (Website-Seite und Repo-Dateien).

Datenfluss

• Beim Build: Next.js rendert /, /docs, /docs/* für jede Sprache vor.
• Der Inhalt ist vorgerendert; es gibt keinen Server, keine API, keine Laufzeitdaten.
• Analytics (Umami) wird nur injiziert, wenn NEXT_PUBLIC_UMAMI_SRC und NEXT_PUBLIC_UMAMI_WEBSITE_ID beim Build gesetzt sind.

Konventionen

• Semantisches HTML mit einem einzigen h1 pro Seite.
• Abschnitts-Headings in Ordnung (h2 dann h3), keine übersprungenen Ebenen.
• Externe Links öffnen in einem neuen Tab mit rel="noopener noreferrer".
• Von next-intl gerenderte Links bekommen nie einen bereits präfixierten href; das Sprachpräfix wird immer von den Navigations-Helfern ergänzt.
• Reduced Motion wird überall respektiert: Shimmer, Reveals und Übergänge sind hinter prefers-reduced-motion geschaltet.