managarten/apps-archived/memoro/apps/landing/docs/PROJECT-ARCHITECTURE.md

Memoro Website - Projekt-Architektur-Dokumentation

📋 Übersicht

Die Memoro-Website ist eine mehrsprachige Marketing-Website für eine KI-gestützte App zur Gesprächsdokumentation und Notizenerstellung. Die Website wurde mit Astro 5.3.0 als statische Website entwickelt und unterstützt Deutsch (de) als Standardsprache sowie Englisch (en).

🎯 Projektziel

Die Website dient als zentrale Marketing- und Informationsplattform für die Memoro-App und bietet:

• Produktpräsentation und Feature-Übersicht
• Anleitungen und Dokumentation
• Blog und News-Bereich
• Team-Vorstellung
• Preisgestaltung und Pläne
• Branchenspezifische Lösungen
• Download-Möglichkeiten

🛠 Technologie-Stack

Core Framework

• Astro 5.3.0: Static Site Generator mit hervorragender Performance
• TypeScript: Strict Mode für Typsicherheit
• MDX: Für erweiterte Content-Erstellung mit Komponenten

Styling & UI

• Tailwind CSS 3.4: Utility-first CSS Framework
• Custom Theme System: Zentralisierte Design-Tokens in /src/theme/index.js
• Typography Plugin: Für optimale Text-Darstellung
• Dark Theme: Durchgängiges dunkles Design (#181818 Hintergrund)

Content Management

• Astro Content Collections: Strukturierte Content-Verwaltung mit Zod-Schemas
• 15+ Content-Typen: Blog, Team, Features, Guides, Industries, etc.
• Mehrsprachigkeit: Vollständige de/en Unterstützung

Integrationen

• Sitemap: Automatische Generierung für alle Sprachen
• RSS Feeds: Für jede Content-Collection und Sprache
• Icons: Astro-Icon mit Material Design Icons (MDI)
• Analytics: Plausible & Umami Integration

📁 Projektstruktur

/
├── src/
│   ├── components/          # Wiederverwendbare Astro-Komponenten
│   │   ├── atoms/           # Kleine, atomare Komponenten
│   │   ├── detail/          # Detail-Seiten-Komponenten
│   │   ├── experiments/     # A/B-Testing Komponenten
│   │   ├── industries/      # Branchen-spezifische Komponenten
│   │   └── layouts/         # Layout-Komponenten
│   │
│   ├── content/            # Alle Inhalte mit Zod-Schemas
│   │   ├── blog/          # Blog-Artikel (de/en Unterordner)
│   │   ├── team/          # Team-Profile
│   │   ├── features/      # Feature-Beschreibungen
│   │   ├── guides/        # Anleitungen
│   │   ├── industries/    # Branchenlösungen
│   │   ├── testimonials/  # Kundenstimmen
│   │   ├── blueprints/    # Vorlagen für Aufnahmen
│   │   ├── memories/      # Memory-Typen
│   │   ├── faqs/         # Häufige Fragen
│   │   ├── changelog/     # Produkt-Updates
│   │   ├── statistics/    # Nutzungsstatistiken
│   │   ├── calendar/      # Content-Kalender
│   │   ├── authors/       # Autoren-Profile
│   │   ├── wallpapers/    # Hintergrundbilder
│   │   ├── contracts/     # Rechtliche Dokumente
│   │   ├── dataprotection/# Datenschutz-Dokumente
│   │   └── pages/         # Hauptseiten-Inhalte
│   │
│   ├── i18n/              # Internationalisierung
│   │   ├── ui.ts          # UI-Übersetzungen
│   │   └── utils.ts       # i18n-Hilfsfunktionen
│   │
│   ├── layouts/           # Seiten-Layouts
│   │   ├── Layout.astro   # Standard-Layout
│   │   └── HomeLayout.astro # Spezielles Home-Layout
│   │
│   ├── pages/             # Routing-Struktur
│   │   ├── [lang]/        # Dynamisches Sprach-Routing
│   │   ├── admin/         # Admin-Bereich
│   │   ├── de/            # Deutsche RSS-Feeds
│   │   └── en/            # Englische RSS-Feeds
│   │
│   ├── styles/            # Globale Styles
│   │   └── base.css       # Basis-CSS mit Tailwind
│   │
│   ├── theme/             # Theme-Konfiguration
│   │   └── index.js       # Design-System-Tokens
│   │
│   ├── utils/             # Hilfsfunktionen
│   │   └── experiments.ts # A/B-Testing Utilities
│   │
│   └── middleware.ts      # Request-Middleware für i18n
│
├── public/                # Statische Assets
│   ├── images/           # Bilder organisiert nach Typ
│   │   ├── blog/
│   │   ├── brand/
│   │   ├── guides/
│   │   ├── industries/
│   │   ├── product_photos/
│   │   ├── screenshots/
│   │   ├── team/
│   │   └── wallpaper/
│   └── rss/              # RSS-Feed Styles
│
├── docs/                 # Projekt-Dokumentation
├── context/              # Kontext-Dokumente für KI
├── plans/                # Projekt-Pläne
└── posts/                # Social Media Posts

🌍 Internationalisierung (i18n)

Konfiguration

• Default Locale: Deutsch (de)
• Unterstützte Sprachen: Deutsch (de), Englisch (en)
• Routing: Präfix-basiert (/de/..., /en/...)
• Fallback: Automatische Weiterleitung zur Standardsprache

Implementierung

• Middleware: Behandelt Sprach-Weiterleitungen und 404s
• Content-Organisation: Sprachspezifische Unterordner in Collections
• UI-Übersetzungen: Zentralisiert in src/i18n/ui.ts
• Sitemap: Enthält alle Sprachversionen

📚 Content Collections

Übersicht der Collections

Die Website nutzt 15+ typisierte Content Collections mit Zod-Schemas:

1. blog: Artikel mit Metadaten (Autor, Tags, Kategorie)
2. team: Team-Profile mit Rollen und Social Links
3. features: Produkt-Features mit Icons und Kategorien
4. guides: Tutorials mit Schwierigkeitsgrad und Dauer
5. industries: Branchenlösungen mit Statistiken und FAQs
6. testimonials: Kundenstimmen nach Typ kategorisiert
7. blueprints: Aufnahme-Vorlagen für verschiedene Szenarien
8. memories: KI-generierte Inhaltstypen
9. faqs: Häufige Fragen nach Kategorien
10. changelog: Produkt-Updates und Release Notes
11. statistics: Wochen- und Monatsberichte
12. calendar: Content-Planung mit Events
13. authors: Autoren-Profile mit Statistiken
14. wallpapers: Hintergrundbilder mit Download-Tracking
15. dataprotection: Datenschutz-Dokumente
16. contracts: Rechtliche Dokumente
17. pages: Hauptseiten-Inhalte

Schema-Validierung

Jede Collection hat ein striktes Zod-Schema für:

• Typ-Sicherheit
• Konsistente Datenstruktur
• Automatische Validierung beim Build
• IntelliSense-Unterstützung in der IDE

🎨 Design-System

Theme-Konfiguration

Zentralisiertes Theme in /src/theme/index.js:

{
  colors: {
    primary: '#3B82F6',      // Blau
    secondary: '#10B981',    // Grün
    background: {
      global: '#181818',     // Dunkler Hintergrund
      card: 'rgba(50, 50, 50, 0.8)',
      cardHover: 'rgba(50, 50, 50, 0.99)'
    },
    text: {
      primary: '#F9FAFB',    // Heller Text
      secondary: '#D1D5DB',  // Sekundärer Text
      tertiary: '#9CA3AF'    // Tertiärer Text
    }
  }
}

Tailwind-Erweiterungen

• Custom Font Sizes: Hero, Display, Heading mit responsiven Varianten
• Typography Plugin: Angepasst für Dark Theme
• Custom Utilities: scrollbar-none, bg-gradient-radial
• Group-Open Variant: Für Details-Elemente

🚀 Build & Deployment

Build-Prozess

npm run dev      # Entwicklungsserver (localhost:4321)
npm run build    # Production Build nach ./dist/
npm run preview  # Vorschau des Production Builds
npm run astro check  # TypeScript Type-Checking

Statische Generierung

• Vollständig statisch: Alle Seiten werden zur Build-Zeit generiert
• Keine Server-Runtime: Optimale Performance
• getStaticPaths(): Für dynamische Routen
• Optimierte Assets: Automatische Bild-Optimierung mit Sharp

📊 Analytics & Tracking

Plausible Analytics

• Cookieless Tracking: DSGVO-konform
• Event-Tracking: Detailliertes Nutzerverhalten
• Funnel-Analyse: Conversion-Tracking
• Custom Events: Download, CTA-Clicks, etc.

Umami Analytics

• Self-Hosted Option: Datenschutz-freundlich
• Real-Time Stats: Live-Besucherdaten
• Keine Cookies: Privacy-first Ansatz

🧪 Experimente & A/B-Testing

PostHog Integration

• Feature Flags: Für kontrollierte Rollouts
• A/B-Tests: Hero-Varianten, CTA-Buttons
• Conversion-Tracking: Erfolgsmetriken

Implementierte Tests

• Hero-Section Varianten
• CTA-Button Tests
• Navigation Download-Button

🔒 Sicherheit & Datenschutz

DSGVO-Konformität

• Datenschutzerklärung: Mehrsprachig verfügbar
• Cookie-Consent: Optional für erweiterte Features
• Datenminimierung: Nur notwendige Daten
• TOMs: Technische und organisatorische Maßnahmen dokumentiert

Content Security

• Statische Generierung: Keine Server-Vulnerabilities
• TypeScript: Typ-sichere Entwicklung
• Validierung: Zod-Schemas für alle Inhalte

🎯 Besondere Features

1. Recording Blueprints

Vorgefertigte Vorlagen für verschiedene Aufnahme-Szenarien:

• Büro-Meetings
• Baustellendokumentation
• Akademische Vorlesungen
• Kundengespräche

2. Memory-System

KI-generierte Inhaltstypen aus Aufnahmen:

• Zusammenfassungen
• Aufgaben & Termine
• Blog-Beiträge
• Social Media Posts

3. Mana-Credit-System

Flexibles Abrechnungsmodell:

• Tägliche Mana-Gutschriften
• Mana-Potions zum Nachkaufen
• Maximale Mana-Limits je Plan

4. Multi-Collection RSS

RSS-Feeds für jede Content-Collection:

• Sprachspezifisch
• Automatisch generiert
• XSLT-Styling

5. Content-Kalender

Integrierte Planung für Content-Erstellung:

• Monatsplanung
• Status-Tracking
• Multi-Autor-Support

📈 Performance-Optimierungen

Build-Optimierungen

• Static Site Generation: Keine Server-Laufzeit
• Asset-Optimierung: Automatische Bild-Kompression
• Code-Splitting: Optimale Bundle-Größen
• Lazy Loading: Für Bilder und Komponenten

Frontend-Optimierungen

• Tailwind Purge: Nur verwendete CSS-Klassen
• Font-Optimierung: System-Fonts mit Fallbacks
• Minimal JavaScript: Nur wo notwendig
• Service Worker: Für Offline-Support (geplant)

🛠 Entwickler-Tools

Verfügbare Skripte

• npm run dev: Lokale Entwicklung
• npm run build: Production Build
• npm run preview: Build-Vorschau
• npm run astro check: Type-Checking

Debug-Tools

• Admin-Bereich: /admin/ für Content-Übersicht
• Author-Management: /admin/authors
• Find-Untranslated: Script für fehlende Übersetzungen

📝 Code-Konventionen

Komponenten

• PascalCase: Für Komponentennamen
• Props-Interfaces: TypeScript-Definitionen
• Import-Reihenfolge: Externe → Interne

Content

• Frontmatter: Zod-validiert
• MDX-Support: Komponenten in Markdown
• Sprachordner: de/en Struktur

Styling

• Tailwind-First: Utility-Klassen bevorzugt
• Kebab-Case: Für Custom-CSS
• Keine Inline-Styles: Außer absolut notwendig

🚦 Deployment-Strategie

Hosting

• Static Hosting: Optimiert für CDN-Deployment
• Asset-CDN: Für Bilder und Medien
• Multi-Region: Für optimale Latenz

CI/CD

• Automatische Builds: Bei Git-Push
• Type-Checking: Vor jedem Build
• Sitemap-Generierung: Automatisch
• RSS-Feed-Updates: Bei Content-Änderungen

📊 Monitoring & Wartung

Analytics-Dashboard

• Besucher-Statistiken
• Conversion-Tracking
• Event-Analyse
• Funnel-Visualisierung

Content-Management

• Regelmäßige Blog-Posts
• Feature-Updates
• Team-Änderungen
• FAQ-Erweiterungen

Performance-Monitoring

• Lighthouse-Scores
• Core Web Vitals
• Bundle-Size-Tracking
• Build-Zeit-Optimierung

🔮 Zukünftige Erweiterungen

Geplante Features

• PWA-Support
• Erweiterte Suche
• Newsletter-Integration
• Mehr Sprachen
• API-Dokumentation
• Video-Tutorials

Technische Verbesserungen

• Service Worker
• WebP-Bildformat
• Erweiterte Caching-Strategien
• GraphQL-API (optional)
• CMS-Integration (optional)

📞 Support & Dokumentation

Interne Dokumentation

• /docs/: Technische Dokumentation
• /context/: KI-Kontext-Dokumente
• /plans/: Projekt-Roadmaps
• CLAUDE.md: KI-Assistenz-Guidelines

Externe Ressourcen

• Astro Dokumentation
• Tailwind CSS
• MDX
• Zod

---

Letztes Update: Januar 2025 Version: 2.0.0 Maintainer: Memoro Development Team