# 📚 Dokumentasi Sistem Real-Time Earthquake Detection

## 📖 Panduan Membaca Dokumentasi

Dokumen-dokumen berikut akan membantu Anda memahami dan mengintegrasikan hardware deteksi gempa dengan sistem web dashboard real-time.

---

## 🚀 Mulai Dari Sini

### 1. **REALTIME_IMPLEMENTATION.md** ← START HERE
**Status:** 📋 Implementation Summary  
**Waktu Baca:** 10 menit  
**Untuk:** Pemahaman umum apa yang sudah diperbaiki

Dokumentasi ini menjelaskan:
- ✅ Apa yang sudah diperbaiki
- ✅ Perubahan yang dilakukan
- ✅ Cara menggunakan sistem
- ✅ Checklist kesiapan
- ✅ Troubleshooting umum

**👉 Baca ini terlebih dahulu untuk memahami overview**

---

### 2. **HARDWARE_INTEGRATION.md**
**Status:** 🔧 Integrasi Hardware  
**Waktu Baca:** 20 menit  
**Untuk:** Engineer Hardware / IoT Developer

Dokumentasi ini menjelaskan:
- 📱 Setup device registration
- 🔑 Cara mendapatkan API Key
- 💾 Format data yang harus dikirim
- 📤 Endpoint untuk kirim data
- 💓 Heartbeat mechanism
- 📝 Contoh kode (Python, Arduino, cURL)
- 🐛 Troubleshooting guide

**👉 Baca ini jika Anda adalah hardware engineer**

---

### 3. **API_RESPONSE_FORMAT.md**
**Status:** 📋 API Reference  
**Waktu Baca:** 15 menit  
**Untuk:** Backend Developer / API Integration

Dokumentasi ini menjelaskan:
- 🔌 Semua endpoint dan response format
- 📊 Data types yang didukung
- 🆗 HTTP status codes
- ❌ Error handling
- 🧪 Real-time display integration
- 📚 Batching & performance tips

**👉 Baca ini untuk detail teknis API**

---

### 4. **send_earthquake_data.py**
**Status:** 💻 Python Script  
**Waktu Jalankan:** 2 menit  
**Untuk:** Testing & Learning

Script ini menyediakan:
- ✅ Contoh code Python untuk send data
- ✅ Multiple examples (simple, complex, batch)
- ✅ Continuous stream simulation
- ✅ Error handling patterns
- ✅ Real sensor integration template

**👉 Jalankan ini untuk test API endpoint**

```bash
python send_earthquake_data.py
```

---

### 5. **test-realtime-api.php**
**Status:** ✅ Verification Script  
**Waktu Jalankan:** 1 menit  
**Untuk:** Verify setup

Script ini check:
- ✅ Database connection
- ✅ API endpoints
- ✅ Response formats
- ✅ JavaScript handler
- ✅ View setup

**👉 Jalankan ini untuk verify semua sudah setup**

```bash
php test-realtime-api.php
```

---

## 🎯 Quick Navigation by Role

### Saya adalah Admin / Project Manager
**Bacalah:**
1. REALTIME_IMPLEMENTATION.md (Overview)
2. Checklist bagian untuk pastikan semua ready

---

### Saya adalah Hardware Engineer
**Bacalah:**
1. REALTIME_IMPLEMENTATION.md (Quick Start)
2. HARDWARE_INTEGRATION.md (Detailed guide)
3. Jalankan send_earthquake_data.py untuk test

---

### Saya adalah Backend Developer
**Bacalah:**
1. REALTIME_IMPLEMENTATION.md (Architecture)
2. API_RESPONSE_FORMAT.md (Detailed reference)
3. Lihat contoh code di send_earthquake_data.py

---

### Saya adalah Frontend Developer
**Bacalah:**
1. REALTIME_IMPLEMENTATION.md (Real-Time Display)
2. API_RESPONSE_FORMAT.md (Response format)
3. Lihat /public/js/realtime.js untuk implementation

---

## 📊 System Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│              HARDWARE SENSOR                             │
│         (Deteksi getaran gempa)                          │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ POST /api/v1/devices/data
                   │ Header: X-API-Key
                   ↓
┌─────────────────────────────────────────────────────────┐
│           API SERVER (Laravel)                           │
│  - Validate & Process data                               │
│  - Save to database                                      │
│  - Broadcast to real-time handler                        │
└──────────────────┬──────────────────────────────────────┘
                   │
                   │ GET /api/v1/devices/{id}/statistics
                   │ GET /api/v1/devices/{id}/data
                   ↓
┌─────────────────────────────────────────────────────────┐
│           WEB BROWSER (JavaScript)                       │
│  - public/js/realtime.js                                 │
│  - Poll API setiap 5 detik                               │
│  - Update DOM dengan data terbaru                        │
└──────────────────┬──────────────────────────────────────┘
                   │
                   ↓
┌─────────────────────────────────────────────────────────┐
│      LIVE DASHBOARD (Real-Time Display)                  │
│  - Statistics update                                     │
│  - Data history table                                    │
│  - Device status                                         │
└─────────────────────────────────────────────────────────┘
```

---

## 🔑 Key Endpoints

### For Hardware (POST Data)
```
POST /api/v1/devices/data
Header: X-API-Key: {api_key}

Request body:
{
  "data": [{
    "type": "gempa",
    "value": 250,
    "timestamp": "ISO8601"
  }]
}
```

### For Dashboard (GET Data)
```
GET /api/v1/devices/{device_id}/statistics
GET /api/v1/devices/{device_id}/data
Header: Authorization: Bearer {token}
```

---

## ✅ Verification Checklist

Pastikan sebelum go-live:

- [ ] Database sudah punya test device
- [ ] API endpoints tertest dengan Postman
- [ ] Hardware sudah mendapatkan API key
- [ ] Test data sudah dikirim dari hardware
- [ ] Real-time display sudah show data di dashboard
- [ ] Heartbeat mechanism sudah implemented
- [ ] Error logs sudah di-monitor

---

## 🚀 Quick Start (5 Minutes)

### 1. Verify Setup (1 min)
```bash
cd /home/roky/projects/gempa-web-app
php test-realtime-api.php
```

### 2. Test API (2 min)
```bash
python send_earthquake_data.py
# Pilih contoh 1 untuk test simple send
```

### 3. Check Dashboard (2 min)
1. Buka browser: http://localhost:8000
2. Login ke admin
3. Pergi ke device details page
4. Lihat data update secara real-time

---

## 📞 Need Help?

### Problem: Data tidak tampil
- Check HARDWARE_INTEGRATION.md → Troubleshooting section
- Verify API endpoint dengan Postman
- Check storage/logs/laravel.log

### Problem: API return error
- Check API_RESPONSE_FORMAT.md → Error Handling section
- Verify API key ada di database
- Check database connectivity

### Problem: Real-time tidak update
- Check browser console (F12)
- Verify JavaScript polling interval
- Check network tab untuk API calls

---

## 📝 File Structure

```
/home/roky/projects/gempa-web-app/
├── REALTIME_IMPLEMENTATION.md    ← START HERE (Overview)
├── HARDWARE_INTEGRATION.md        (Hardware guide)
├── API_RESPONSE_FORMAT.md         (API reference)
├── DOCUMENTATION_INDEX.md         (This file)
├── send_earthquake_data.py        (Test script)
├── test-realtime-api.php          (Verify script)
│
├── app/Http/Controllers/Api/
│   └── DeviceController.php       (API methods)
│
├── public/js/
│   └── realtime.js                (Real-time handler)
│
├── resources/views/
│   ├── admin/devices/show.blade.php
│   └── devices/show.blade.php
│
├── bootstrap/
│   └── app.php                    (API routes registered)
│
└── routes/
    └── api.php                    (API endpoints)
```

---

## 🎓 Learning Path

### Untuk Pemula
1. Baca REALTIME_IMPLEMENTATION.md
2. Jalankan test-realtime-api.php
3. Jalankan send_earthquake_data.py - example 1
4. Lihat data di dashboard

### Untuk Intermediate
1. Baca semua dokumentasi
2. Study API_RESPONSE_FORMAT.md
3. Jalankan send_earthquake_data.py - example 4 (continuous)
4. Implement di real hardware

### Untuk Advanced
1. Study source code di DeviceController
2. Modify realtime.js untuk custom behavior
3. Implement WebSocket untuk real-time (future)
4. Optimize database queries

---

## 🔄 Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2026-05-19 | Initial implementation with API routes, methods, and response format fixes |

---

## 📞 Questions?

Silakan mereferensi:
1. **REALTIME_IMPLEMENTATION.md** - untuk overview
2. **HARDWARE_INTEGRATION.md** - untuk hardware questions
3. **API_RESPONSE_FORMAT.md** - untuk API questions
4. **storage/logs/laravel.log** - untuk error diagnosis

---

**Happy earthquake monitoring! 🌍**