Dokumentation
Developer-Dokumentation
Architektur, Komponenten-Bibliothek, API-Referenz und Deployment-Guide für Spotlight Service.
🏗️ Architektur
Tech Stack
Next.js 15 App Router, TypeScript, Tailwind CSS, Vercel Deployment
Projektstruktur
src/app (Routes), src/components, src/lib, public/
Datenfluss
Client → API Routes → External Services. localStorage für Demo-Daten.
State Management
React State + localStorage. Kein Redux. Server Components wo möglich.
🧩 Komponenten
UI-Komponenten
MagneticButton, AnimatedCounter, SocialProofToast, InstallBanner
Layout-Komponenten
DashboardClient, Navbar, Footer, BreadcrumbJsonLd
Formular-Komponenten
Free-Check Form, Contact Form, Lead-Status-Dropdown
SEO-Komponenten
BreadcrumbJsonLd, OG-Image API, Sitemap, Robots.txt
🔌 API-Referenz
REST-Endpunkte
22 API-Routes: /api/free-check, /api/chat, /api/checkout etc.
Auth & Rate-Limits
Dashboard-Auth, Stripe-Webhook-Sig, Cron-Secret. Rate-Limits pro Endpunkt.
GROQ Integration
Streaming-Client mit Rate-Limiting und Context-Injection (groq-client.ts)
📦 Bibliotheken (src/lib)
Lead-Scoring V2
Multi-Signal-Scoring mit Behavioral-Signalen. Grades A-D, Priorities hot/warm/cold.
A/B Testing
ab-testing.ts: Varianten-Zuordnung, Conversion-Tracking, localStorage.
Offline Queue
offline-queue.ts: Formular-Queue mit exponentiellem Backoff.
Push Notifications
push-notifications.ts: SW-Integration, Notification-Click-Handler.
Roles & Tenants
RBAC (admin/manager/viewer), Multi-Tenant mit Tenant-Switcher.
Audit Log
audit-log.ts: Alle Dashboard-Aktionen, Filter, CSV-Export.
Dunning
dunning.ts: Überfällige Zahlungen, Reminder-Queue, Invoice-Badges.
Upsell Analytics
upsell-analytics.ts: Conversion-Rates nach Tier, Trigger, Score-Range.
Referral Loop
referral-loop.ts: Auto-Codes, Tracking, Milestone-Rewards (3→1 Monat frei).
Launch Readiness
launch-readiness.ts: 20 automatisierte Checks, 100-Punkte-Score.
🚀 Deployment
Vercel
git push → Vercel auto-deploy. Environment Variables in Dashboard.
Environment Variables
GROQ_API_KEY, STRIPE_SECRET_KEY, CRON_SECRET etc.
Cron Jobs
/api/cron/digest (wöchentlich), /api/cron/recheck (täglich), /api/cron/sms-reminder.
🤝 Beitragen
Code-Style
TypeScript strict, Prettier, ESLint. Components: function components, hooks oben.
Commits
Conventional Commits: feat:, fix:, docs:, chore:. Deutsch für User-Facing.
Branches
main → auto-deploy. Feature-Branches: feat/123-beschreibung.