Arsitektur Repository

Repository ini berisi tiga modul yang berjalan sendiri-sendiri: tools/ (Go), web/ (Astro + React), dan cli/ (npm). Ketiganya hanya bertemu di satu titik, yaitu pohon JSON di api/ yang disalin ke deploy/v2/ pada job deploy. Tidak ada server aplikasi; seluruh permukaan API adalah berkas statis yang sudah di-generate sebelumnya.

Tiga modul dan entrypoint-nya

Modul Go adalah sebuah Go module bernama data-wilayah dengan go 1.25 (go.mod:1-3¹). Satu binary go run ./tools memegang semua perintah: main membaca os.Args[1] lalu mendispatch ke runExtractCSV, runGenerateStaticAPI, runGenerateBoundaries, runAddHasPath, runGenerateMissings, atau runUpdateStats (tools/main.go:34-71²). Daftar perintah yang sama dicetak oleh printUsage ke os.Stderr ketika argumen tidak dikenali (tools/main.go:8-23³).

Website memakai base /api-wilayah-indonesia/ dan site https://www.emsifa.com (web/astro.config.mjs:7-14⁶). CLI hanya mempublikasikan direktori dist, sementara prebuild menyalin ../SKILL.md menjadi assets/SKILL.md agar ikut terbundel (cli/package.json:36-40⁷); tsdown mengonfigurasi entry: "src/index.ts", format: "esm", dan noExternal: [/./] sehingga semua dependency ikut masuk bundel (cli/tsdown.config.ts:3-17⁸). Pada commit ini baru satu subcommand yang terdaftar, yaitu skill (cli/src/index.ts:11-13⁹); detailnya ada di CLI @emsifa/wilayah.

Aliran artefak menuju deploy/v2/

graph TD
  SRC["data/*.csv (ephemeral)"] --> TOOLS["tools/ (Go, module data-wilayah)"]
  TOOLS -->|"generate-*"| API["api/ JSON tree"]
  WEB["web/ (Astro + React)"] -->|"npm run build"| DIST["web/dist"]
  DIST -->|"cp -r web/dist/*"| DEPLOY["deploy/"]
  API -->|"cp -r api/*"| V2["deploy/v2/"]
  DEPLOY --> GHP["branch gh-pages"]
  CLI["cli/ @emsifa/wilayah"] -->|"prebuild cp"| SKILL["assets/SKILL.md"]
  style SRC fill:#336791,color:#fff
  style API fill:#336791,color:#fff
  style V2 fill:#8b5cf6,color:#fff
  style GHP fill:#2d7d46,color:#fff
  style CLI fill:#f59e0b,color:#000
  style SKILL fill:#f59e0b,color:#000
%% fig: Aliran artefak tiga modul menuju deploy/v2
%% desc: tools/ menghasilkan pohon JSON di api/, web/ menghasilkan web/dist, dan keduanya disatukan di deploy/ sebelum dipublikasikan ke branch gh-pages. cli/ berdiri di luar aliran ini.

Job deploy membangun web/ lebih dulu lewat working-directory: web dengan npm ci lalu npm run build (.github/workflows/deploy.yml:25-29¹⁰). Modul Go baru dipakai setelahnya, dan seluruh perintahnya dijalankan dari akar repository. Setiap perintah Go me-resolve akar itu dengan repoRoot, yang menaiki direktori induk sampai menemukan .git (tools/generate_static_api.go:633-648¹¹).

Langkah Assemble publish dir merakit satu direktori keluaran: cp -r web/dist/* deploy/, touch deploy/.nojekyll, mkdir -p deploy/v2, lalu cp -r api/* deploy/v2/ (.github/workflows/deploy.yml:92-104¹²). Hasil deploy/ dipublikasikan ke branch gh-pages dengan publish_dir: ./deploy, publish_branch: gh-pages, dan keep_files: true (.github/workflows/deploy.yml:106-115¹³).

Batas antar modul

update-stats menutup rantai ini dengan menghitung ulang stats.json: setiap berkas berekstensi .json di bawah direktori keluaran dihitung sebagai satu endpoint, dan ukurannya dijumlahkan menjadi total_filesize serta total_disk_usage (tools/update_stats.go:62-88¹⁵). Karena itu angka total_endpoints bergantung langsung pada isi api/, bukan pada daftar rute yang ditulis manual.

⚠️ Trigger workflow hanya menyebut paths: ["web/**", "tools/**", "go.mod", ".github/workflows/deploy.yml"]. Perubahan di cli/ atau SKILL.md tidak memicu deploy, sehingga rilis CLI harus dilakukan terpisah dari pipeline situs.

⚠️ cp -r api/* deploy/v2/ tidak menghapus berkas lama di deploy/v2/, dan keep_files: true mempertahankan isi branch gh-pages. Berkas yang tidak lagi di-generate tetap tertinggal dan tetap dapat diakses sampai dihapus manual. Tata cara deploy selengkapnya ada di Deploy dan CI.

Urutan perintah Go yang dijalankan workflow, beserta peran tiap perintah terhadap isi api/, dibahas di Pipeline Generate dengan Go Tools.