KuppelSimulation/JS/README.md

# Observatory Simulation 🔭

Eine realistische Observatoriums-Simulation mit NFC-Tag-basierter Kuppelsteuerung, WebSocket-Architektur und smooth Teleskop-Tracking.

## Features

- 🔭 **Teleskop-Rotation**: Automatische 1 U/min CW-Rotation mit manueller Steuerung
- 🏠 **Intelligente Kuppel**: NFC-Tag-basierte Positionierung mit smooth Bewegung  
- 🌐 **WebSocket-Architektur**: Multi-Task-System mit Real-time-Kommunikation
- 📱 **Responsive UI**: Modern dark theme mit Touch-Steuerung
- 🎯 **360°-Bug-frei**: Korrekte Winkeldifferenz-Berechnungen
- 🏷️ **36 NFC-Tags**: Alle 10° für realistische Positionserkennung

## Docker Deployment 🐳

### Quick Start

```bash
# Repository klonen
git clone <repository-url>
cd KuppelSimulation/JS

# Mit Docker Compose starten
docker compose up -d

# Simulation öffnen
open http://localhost:3005
```

### Manuelle Docker Commands

```bash
# Docker Image bauen
docker build -t observatory-simulation .

# Container starten
docker run -d \\
  --name observatory-sim \\
  -p 3005:3005 \\
  observatory-simulation

# Container Logs anzeigen
docker logs observatory-sim

# Container stoppen
docker stop observatory-sim
```

### Production Setup mit Nginx

```bash
# Production Profile aktivieren
docker compose --profile production up -d

# Zugriff über Port 80/443
open http://observatory.local
```

## Development Setup 💻

### Lokale Entwicklung

```bash
# Dependencies installieren
npm install

# Development Server starten
npm start

# Öffne http://localhost:3005
```

### Verfügbare Befehle

```bash
npm start          # Server starten
npm run dev        # Development mode mit auto-reload
npm test           # Tests ausführen  
npm run lint       # Code linting
npm run build      # Production build
```

## System-Architektur 🏗️

```
┌─────────────────┐    WebSocket    ┌─────────────────┐
│   Telescope     │ ◄──────────────► │      Server     │
│   (Rotation)    │                 │   (Socket.io)   │
└─────────────────┘                 └─────────────────┘
                                            │
┌─────────────────┐    WebSocket            │    WebSocket
│     Dome        │ ◄──────────────────────┼────────────────► ┌─────────────────┐
│  (NFC Tracking) │                        │                  │  Visualization  │
└─────────────────┘                        │                  │   (Canvas)      │
                                           │                  └─────────────────┘
                                           ▼
                                  ┌─────────────────┐
                                  │   Web Browser   │
                                  │  (User Interface)│
                                  └─────────────────┘
```

## Steuerung 🎮

### Teleskop
- **Automatisch**: 6°/sec CW-Rotation (1 U/min)
- **+15° Button**: Schnelle CW-Bewegung  
- **+45° Button**: Große CW-Bewegung
- **-15° Button**: Schnelle CCW-Bewegung
- **-45° Button**: Große CCW-Bewegung

### Kuppel (automatisch)
- **NFC-Tag-Navigation**: 36 Tags alle 10°
- **Intelligente Trigger**: Bei 6° Teleskop-Abweichung
- **Smooth Bewegung**: 0.5°/Frame (15°/sec)
- **CW-Puffer**: Für große Sprünge

## Technische Details ⚙️

### Docker Features
- **Multi-Stage Build**: Optimierte Image-Größe
- **Non-Root User**: Sicherheit durch `observatory` User  
- **Health Checks**: Automatische Container-Überwachung
- **Alpine Linux**: Minimale Basis für kleine Images
- **Volume Support**: Persistente Daten möglich

### WebSocket Events
```javascript
// Teleskop → Server
'telescope-position': { angle: 123.5 }

// Kuppel → Server  
'dome-position': { angle: 145.0, slotWidth: 20 }

// Server → Clients (Broadcast)
'telescope-position': { angle: 123.5 }
'dome-position': { angle: 145.0, slotWidth: 20 }
```

### NFC-Tag-System
```javascript
// Tag-Berechnung
tagIndex = Math.floor(angle / 10)  // 0-35
tagAngle = tagIndex * 10 + 5       // Mitte des Tags

// Beispiel
angle: 123° → tagIndex: 12 → tagAngle: 125°
```

## Environment Variables 🔧

```bash
NODE_ENV=production    # Produktions-Modus
PORT=3005             # Server Port
LOG_LEVEL=info        # Logging Level
```

## Monitoring & Debugging 📊

### Container Logs
```bash
# Real-time Logs
docker logs -f observatory-sim

# Letzte 100 Zeilen
docker logs --tail 100 observatory-sim
```

### Browser Console
- Teleskop-Positionen: `[Telescope] Broadcasting position: X°`
- Kuppel-Tracking: `[Dome] MOVING: X° → Y°, Dir=CW/CCW` 
- WebSocket: `[Visualization] Received dome position: X°`

### Health Check
```bash
# Container Status prüfen
docker ps

# Health Status
docker inspect --format='{{.State.Health.Status}}' observatory-sim
```

## Production Considerations 🏭

### Performance
- **Image-Größe**: ~50MB (Alpine + Node.js)
- **Memory**: ~64MB Runtime  
- **CPU**: Minimal (Event-driven)
- **Skalierung**: Horizontal über Load Balancer

### Sicherheit
- Non-Root Container User
- Minimale Attack Surface (Alpine)
- Keine sensitive Daten im Image
- Network Isolation über Docker Networks

### Backup
```bash
# Container-Export
docker export observatory-sim > observatory-backup.tar

# Volume-Backup (falls verwendet)
docker run --rm -v observatory-data:/data -v $(pwd):/backup alpine tar czf /backup/data-backup.tar.gz /data
```

## Troubleshooting 🔧

### Häufige Probleme

**Port 3005 bereits belegt:**
```bash
# Port-Usage prüfen
lsof -i :3005
netstat -tulpn | grep 3005

# Anderen Port verwenden
docker run -p 3006:3005 observatory-simulation
```

**Container startet nicht:**
```bash
# Detaillierte Logs
docker logs observatory-sim

# Container-Inspektion
docker inspect observatory-sim
```

**WebSocket-Verbindung fehlschlägt:**
- Firewall-Einstellungen prüfen
- Browser-Console für JS-Fehler checken  
- Network-Tab in DevTools analysieren

---

## License

MIT License - Observatory Simulation Project