FretCalc

Progressive Web App zur präzisen Berechnung von Bundpositionen für Saiteninstrumente

FretCalc ist ein Bundpositionsrechner, der Musikinstrumentenbauern ermöglicht, exakte Bundpositionen für verschiedene Mensuren, Stimmungen und Tonleitern zu berechnen - auch für historische Instrumente. Die Anwendung generiert sowohl visuelle SVG-Vorlagen als auch detaillierte Positionstabellen mit 3-stelliger Dezimalpräzision. Außerdem lassen sich Entwürfe teilen, speichern und widerherstellen. Spieler haben zudem die Möglichkeit anhand der Bünde verschiedene Tonleitern eines Instruments zu erforschen und in Skalen reinzuhören.

Live

https://fret-calc.netlify.app/

---

Projektarchitektur

FretCalc folgt einer modernen Single-Page-Application (SPA) Architektur mit folgenden Kernprinzipien:

Architektur-Highlights

• Component-Based Architecture: React mit TypeScript für typsichere, wiederverwendbare UI-Komponenten
• State Management: Zentralisierter App-State mit Zustand für vorhersehbare State-Updates
• Progressive Enhancement: Vollständige Offline-Funktionalität durch Service Worker und PWA-Technologie
• Responsive Design: Mobile-First Ansatz mit adaptiven Layouts für alle Bildschirmgrößen
• Type Safety: Strikte TypeScript-Konfiguration verhindert Runtime-Fehler bereits zur Compile-Zeit
• Internationalisierung: Mehrsprachige Unterstützung (DE/EN) durch react-i18next
• Docker-basierte Entwicklung: Konsistente Entwicklungsumgebung über alle Systeme hinweg

Technologie-Stack

• Frontend: React, TypeScript, Vite
• Styling: TailwindCSS für utility-first CSS und themebares Farbschema
• State: Zustand für globales State Management
• PWA: Workbox für Service Worker und Offline-Support
• Icons: FontAwesome für konsistente Ikonografie
• Testing: Vitest für Unit- und Integration-Tests
• Build: Vite für schnelle Builds und HMR
• Deployment: Netlify mit Forms-Integration

Design-Prinzipien

1. Separation of Concerns: Klare Trennung von Logik (lib/), UI (components/) und State (state/)
2. Reusability: Wiederverwendbare Form- und UI-Komponenten in components/commons/
3. Testability: Umfassende Test-Coverage für Business-Logik
4. Accessibility: Semantisches HTML und ARIA-Labels für Screen-Reader-Support
5. Performance: Vite-basiertes Vendor-Chunking und optimierte Bundle-Größe
6. Scalability: Modulare Struktur ermöglicht problemlose Feature-Erweiterung in allen Belangen

---

Vorteile der Architektur

Performance

• Vite sorgt für blitzschnelle Builds (< 2s) und Hot Module Replacement
• Automatisches Vendor-Chunk-Splitting durch Vite für optimale Caching-Strategien
• Service Worker ermöglicht Instant-Loading bei wiederholten Besuchen
• Optimierte Assets durch automatische Image-Kompression

Type Safety

• Strikte TypeScript-Konfiguration verhindert Common-Pitfalls
• Type Guards für alle externen Daten (URL-Parameter, LocalStorage)
• Compile-Time-Validierung reduziert Runtime-Fehler drastisch

Testbarkeit

• Pure Functions in lib/music-theory/ sind einfach zu testen
• Umfassende Unit-Tests mit hoher Coverage für Business-Logik (96+ Tests)
• Snapshot-Tests für UI-Komponenten und Übersetzungen
• Vitest mit Happy-DOM für schnelle Test-Ausführung

Progressive Enhancement

• Installierbar und Offline-First: App funktioniert komplett ohne Internet
• Adaptive UI: Mobile- und Desktop taugliches Layout

Internationalisierung

• Einfache Erweiterung um neue Sprachen
• Typsichere Übersetzungs-Keys durch TypeScript
• Automatische Sprach-Detektion basierend auf Browser-Settings

Developer Experience

• Docker-basiert: docker compose up oder Makefile-Commands nutzen und loslegen
• Hot Reload: Änderungen sofort im Browser sichtbar
• NPM-Scripts: Standardisierte Build- und Test-Commands

Wartbarkeit & Skalierbarkeit

• Klare Ordnerstruktur: Jeder Ordner hat eine eindeutige Verantwortung
• Kleinteiligs: Übersichtliche kleinteile React-Components und Funktionen
• Versionskontrolle: app-version.ts für Release-Tracking
• Modulare Architektur: Neue Features können unabhängig hinzugefügt werden
• Component-Library: Wiederverwendbare UI-Komponenten in commons/
• State-Separation: Zustand kann bei Bedarf auf Zustand-Slices aufgeteilt werden
• Erweiterbar für Lazy Loading: Architektur ermöglicht einfache Integration von Route-basiertem Code-Splitting
• Plugin-System: Vite-Plugins ermöglichen einfache Build-Erweiterungen

Barrierefreiheit

• WAI-ARIA: ARIA-Labels für wichtige Interaktionselemente (Buttons, Overlays, Tabs)
• Keyboard-Navigation: Button- und Tab-Komponenten sind per Tastatur navigierbar
• Semantisches HTML: Verwendung korrekter HTML5-Elemente wo möglich
• Fokus-Management: Sichtbare Fokus-Indikatoren durch TailwindCSS
• Farbkontraste: Design mit hohen Kontrastverhältnissen
• Pregnanz: Interatkive UI-Elemente haben ein konsistentes Farbschema

---

Ordnerstruktur

Root-Level

.
├── docker-compose.yml          # Docker-Orchestrierung für Dev-Environment
├── Makefile                    # Build- und Deployment-Shortcuts
├── netlify.toml               # Netlify-Deployment-Konfiguration
└── webclient/                 # Haupt-Applikationsverzeichnis

webclient/ - Hauptanwendung

webclient/
├── Dockerfile                 # Container-Definition für Production-Build
├── index.html                # HTML-Template mit Netlify-Form-Integration
├── package.json              # Dependencies und NPM-Scripts
├── vite.config.ts           # Vite-Build-Konfiguration mit PWA-Plugin
├── tsconfig.json            # TypeScript-Compiler-Einstellungen (strict mode)
└── pwa-assets.config.json   # Konfiguration für PWA-Icons und -Assets

src/ - Quellcode

src/components/ - React-Komponenten

components/commons/ - Wiederverwendbare Basis-Komponenten

• Button.tsx - Primärer Button mit Varianten
• Card.tsx - Container-Komponente für Content-Gruppierung
• ScrollToTop.tsx - Scroll-to-Top Button
• Tabs.tsx - Tab-Navigation-Komponente
• Tooltip.tsx - Hover-Tooltips mit Z-Index-Management
• Form/ - Form-Komponenten mit einheitlichem Styling
  • Input.tsx - Text-Input
  • Label.tsx - Form-Label-Komponente
  • Select.tsx - Select-Dropdown mit optionalem Icon-Support
  • RangeSlider.tsx - Range-Slider mit Wert-Anzeige
  • Textarea.tsx - Multi-Line Text-Input
• PWA/ - Progressive Web App Komponenten
  • PWAInstallBanner.tsx - Install-Prompt für PWA
  • PWAInstallCard.tsx - PWA-Installations-Karte
• Tables/ - Tabellen-Komponenten
  • TableHeader.tsx - Tabellen-Header mit Sortierung
  • TableCell.tsx - Wiederverwendbare Tabellenzelle

components/FretCalculator/ - Feature-spezifische Komponenten

• FretCalculator.tsx - Haupt-Container der Anwendung
• AppHeader.tsx - Header mit Navigation und Settings
• AppFooter.tsx - Footer mit Kontakt-Integration
• StickyHeader.tsx - Sticky Header für Mobile-Navigation
• ShareUrlCard.tsx - URL-Sharing-Funktionalität
• ResultsPanel/ - Berechnungsergebnisse
  • ResultsPanel.tsx - Anzeige der Berechnungsergebnisse (Tabelle/SVG)
  • SVGGenerator.tsx - SVG-Template-Generator für Bundpositionen
  • FrequencyPlayer.tsx - Audio-Player für Tonfrequenzen mit Wellenform-Unterstützung
• ConfigurationPanel/ - Input-Panel für Konfigurationsparameter
  • ConfigurationPanel.tsx - Haupt-Konfigurationspanel
  • TuningSystemField.tsx - Auswahl zwischen gleichstuftiger Stimmung (moderner Standard) und reiner Stimmung
  • ConcertPitchField.tsx - Freie Eingabe für Kammerton (400-460 Hz), so sind auch historische Kammertöne möglich
  • OpenNoteField.tsx - Saitenstimmung-Auswahl
  • ScaleField.tsx - Tonleiter-Konfiguration (Dur/Moll)
  • ScaleLengthField.tsx - Mensur-Eingabe
  • ZeroPointField.tsx - Nullpunkt-Auswahl (Sattel/Steg)
  • CalculationCapField.tsx - Berechnungslimit (Oktaven)
• MobileSettingsOverlay/ - Mobile Settings
  • MobileSettingsOverlay.tsx - Haupt-Overlay-Container
  • LanguageSetting.tsx - Sprachauswahl um die Browser-Detection zu überschreiben (DE/EN)
  • UnitSetting.tsx - Einheitenwahl (cm/inch)
  • VolumeSetting.tsx - Lautstärke-Regler
  • WaveformSetting.tsx - Wellenform-Auswahl für den Sound-Player (Sinus, Rechteck, Sägezahn, Dreieck)
• Overlays/ - Overlay-Komponenten
  • MobileOverlayWrapper.tsx - Wiederverwendbarer Overlay-Container
  • ContactOverlay.tsx - Netlify-kompatibles Kontaktformular
  • SavedConfigurationsOverlay/ - Konfigurationsverwaltung
    • SavedConfigurationsOverlay.tsx - Overlay für gespeicherte Konfigurationen
    • SavedConfigurationsCard.tsx - Verwaltung gespeicherter Konfigurationen mit IndexedDB

src/lib/ - Business Logic & Utilities

lib/music-theory/ - Musik-Theorie und Berechnungslogik:

• fret-calc.ts - Hauptberechnungsmodul für Bundpositionen (3-Dezimal-Präzision) mit Unterstützung für gleichstuftiger Stimmung und reine Stimmung
• just-intonation.ts - Reine Stimmung Berechnungen mit 5-Limit Tuning
• note-frequencies.ts - Dynamische Frequenzberechnung mit frei wählbarem Kammerton (12-Ton-Gleichstufige-Stimmung)
• note-names.ts - Notennamen und Enharmonik
• scale-steps.ts - Tonleiter-Definitionen (Dur, Moll)
• semitone-mappings.ts - Halbton-Zuordnungen für verschiedene Tunings

Utility-Funktionen:

• unit-converter.ts - Umrechnung zwischen cm und inch
• number-parser.ts - Robustes Parsing von Zahlen-Inputs
• generate-csv.ts - CSV-Export-Generator mit Metadaten
• download-file.ts - File-Download-Helper
• local-storage.ts - LocalStorage-Wrapper mit Type-Safety
• offline-db.ts - IndexedDB (Dexie.js) für Offline-Konfigurationsspeicherung
• tailwind-utils.ts - TailwindCSS-Utility-Helfer (cn-Funktion)
• app-version.ts - Versions-Management und Metadaten-Generierung
• fontawesome.ts - FontAwesome-Icon-Library-Konfiguration

src/state/ - Globaler State

• appState.ts - Zustand Store mit allen App-Settings (Mensur, Tuning, Tonleiter, UI-Präferenzen)
• index.ts - State-Exports und Type-Definitionen

src/i18n/ - Internationalisierung

• config.ts - i18next-Konfiguration
• locales/de.json - Deutsche Übersetzungen
• locales/en.json - Englische Übersetzungen
• Vollständige Übersetzung aller UI-Texte, Labels und Fehlermeldungen inkl. Aria-Labels

src/hooks/ - Custom React Hooks

• usePWAInstall.ts - PWA-Install-Prompt-Management
• useUrlState.ts - URL-basiertes State-Sharing für Konfigurationen

public/ - Statische Assets

Icons, Favicons, Open Graph Images und andere statische Ressourcen

coverage/ - Test-Coverage-Reports

HTML-Reports der Code-Coverage (generiert durch Vitest)

dist/ - Production Build

Generiertes Production-Bundle (wird von npm run build erstellt)

vite-plugins/ - Custom Vite Plugins

• html-env-plugin.ts - Environment-Variable-Injection in HTML

---

Quick Start

# Development starten
docker compose up

# Tests ausführen
docker compose exec webclient npm test

# Production Build
docker compose exec webclient npm run build

---

## Deployment

Die Anwendung ist optimiert für **Netlify**-Deployment, abgesehen von dem im Footer verlinkten Kontakt formular, funktioniert sie aber auch auf generischen Hosts

Vorteile von Netlify (free tier)

- Automatische Builds bei Git-Push
- Netlify Forms für Kontaktformular
- CDN-Distribution weltweit
- HTTPS by default

---

**Entwickelt von Chris Vaupel**