# ECGO — Tech Stack & Workflow

> Stack finalized: 2026-09-08

---

## Keputusan Arsitektur

| Komponen | Teknologi | Alasan |
|---|---|---|
| **Primary Language** | TypeScript / JavaScript | Cloudflare-native, MCP SDK TS lebih mature |
| **API / Backend** | Cloudflare Workers | Serverless, no cold start, edge global, ~$5/month |
| **Dashboard** | Cloudflare Pages | Static HTML/JS, CDN global, gratis |
| **Database Prod** | MySQL → Hyperdrive | Via Cloudflare Hyperdrive proxy ke external MySQL |
| **Logs / Analitik** | PostgreSQL → Hyperdrive | Via Cloudflare Hyperdrive |
| **Edge Storage** | Cloudflare D1 / KV | App state, cache, lightweight data |
| **ML Heavy (opsional)** | Python REST API di VPS | Hanya jika butuh sklearn/TF/PyTorch — dipanggil via HTTP dari Worker |
| **Mobile Frontend** | Flutter | Consume REST API dari Workers |
| **MCP Server** | TypeScript MCP SDK | `@modelcontextprotocol/sdk` |
| **Issue Tracking** | Linear (via MCP) | Ticket langsung dari Claude |
| **Documentation** | GitHub — `ecgo platform` | Source of truth semua kode & docs |

---

## Arsitektur End-to-End

```
┌─────────────────────────────────────────────────────┐
│                  CLOUDFLARE ECOSYSTEM                │
│                                                     │
│  Pages (Dashboard HTML/JS)                          │
│       │ fetch()                                     │
│       ▼                                             │
│  Workers (TypeScript)  ←── MCP Server               │
│       ├── Hyperdrive ──→ MySQL (prod data)          │
│       ├── Hyperdrive ──→ PostgreSQL (logs)          │
│       ├── D1          ── app state / cache          │
│       └── Workers AI  ── simple inference           │
│                                                     │
└─────────────────────────────────────────────────────┘
         │ HTTP (jika butuh heavy ML)
         ▼
┌─────────────────────────────┐
│  VPS / Fly.io (Python)      │
│  FastAPI REST endpoint      │
│  sklearn / TF / PyTorch     │
│  → hanya dipanggil kalau    │
│    Workers tidak cukup      │
└─────────────────────────────┘
         │ REST API
         ▼
┌──────────────┐
│ Flutter App  │
│ Mobile Client│
└──────────────┘
```

---

## Rules

1. **Default TypeScript** — semua kode baru di Workers/Pages pakai TypeScript
2. **Python hanya via REST** — kalau butuh ML berat, buat endpoint Python terpisah di VPS, panggil dari Worker via `fetch()`
3. **Database lewat Hyperdrive** — jangan connect langsung MySQL/PostgreSQL dari Workers, selalu lewat Hyperdrive untuk connection pooling
4. **MCP via TS SDK** — `@modelcontextprotocol/sdk` untuk semua MCP integration
5. **Dokumentasi ke GitHub** — semua kode push ke repo `ecgo platform`
6. **Ticket ke Linear** — setiap automation task punya Linear ticket (via MCP)

---

## Alur Kerja

### Buat Fitur Baru
```
Identifikasi masalah (02_automation/identified_problems/)
    → Buat Linear ticket (via MCP)
    → Kode di Workers (TypeScript)
    → Test local dengan Wrangler
    → Deploy ke Cloudflare Workers
    → Update docs di GitHub (ecgo platform)
    → Update status Linear ticket
```

### Jika Butuh ML
```
Identifikasi bahwa Workers tidak cukup (memory > 128MB / butuh sklearn)
    → Buat Python FastAPI endpoint di VPS
    → Expose sebagai REST API
    → Panggil dari Worker: fetch('https://ml.ecgo.internal/predict', ...)
    → Worker tetap sebagai orchestrator
```

### Naming Convention

| Jenis | Format |
|---|---|
| Worker endpoint | `src/routes/DEPT_FUNGSI.ts` |
| Problem doc | `DEPT_problem_YYYYMMDD.md` |
| Improvement doc | `DEPT_improvement_NAMA.md` |
| Python ML service | `ml-services/NAMA_MODEL/main.py` |

---

## Biaya Estimasi

| Item | Harga |
|---|---|
| Cloudflare Pages | Gratis |
| Cloudflare Workers (paid) | $5/month (10M requests) |
| Cloudflare Hyperdrive | $0.15/million queries |
| VPS Python ML (opsional) | $4-7/month (Hetzner/Contabo) |
| **Total minimum** | **$5/month** |