Teknis — Documentation Site

Situs dokumentasi RAGA berbasis VitePress, di-deploy publik di docs.raga.tlab.co.id. Menjadi rumah untuk dokumentasi produk maupun dokumentasi arsitektur teknis seluruh service RAGA.

Repository

Key	Value
Git Remote	https://git.tlab.co.id/tarantula/web/documentation-api-chat.git
Branch Aktif	main

git clone https://git.tlab.co.id/tarantula/web/documentation-api-chat.git
cd documentation-api-chat

Catatan: repo ini berada di namespace web, berbeda dari service backend (service) dan dashboard admin (dashboard).

Tech Stack

Layer	Teknologi
Static Site Generator	VitePress 1.3
Diagram	vitepress-plugin-mermaid + mermaid (di-wrap lewat withMermaid() di config)
Web Server (produksi)	Nginx
Runtime Build	Node.js 20

Struktur Folder

documentation-api-chat/
├── docs/
│   ├── .vitepress/
│   │   ├── config.mjs          # Nav, sidebar (per locale), konfigurasi mermaid & search
│   │   └── cache/               # Cache build VitePress (di-gitignore)
│   ├── index.md                 # Landing page (hero + fitur), redirect root ke /id/ diatur di nginx
│   ├── assets/                  # Gambar/screenshot, dipakai lintas locale via path /assets/...
│   ├── id/                      # Konten Bahasa Indonesia (locale utama / root)
│   │   ├── introduction/
│   │   ├── getting-started/
│   │   ├── integrations/
│   │   └── architecture/        # Dokumentasi arsitektur teknis (halaman ini ada di sini)
│   └── en/                      # Konten Bahasa Inggris, mirror struktur docs/id/
├── swagger/                     # Aset statis swagger-ui-dist — lihat catatan di bawah
├── nginx.conf                   # Konfigurasi Nginx untuk serve hasil build
├── Dockerfile                   # Image development (docs:dev)
├── Dockerfile.prod              # Multi-stage build produksi -> Nginx
└── docker-compose.dev.yml

Catatan: folder swagger/ di root berisi salinan tidak lengkap dari swagger-ui-dist (file swagger-initializer.js, index.css, dan favicon yang dirujuk index.html tidak ada di folder ini). Folder ini juga tidak dirujuk dari navigasi VitePress manapun — tampak seperti sisa percobaan mounting Swagger UI statis yang belum selesai/tidak terpakai.

Konfigurasi (docs/.vitepress/config.mjs)

Satu file konfigurasi mengatur kedua locale:

• locales.root — locale id (Bahasa Indonesia), link: '/id/', jadi locale default di path root.
• locales.en — locale en (Inggris), link: '/en/'.
• Tiap locale punya themeConfig.nav (menu atas) dan themeConfig.sidebar (menu samping) sendiri — keduanya harus diupdate manual & simetris saat menambah halaman baru, karena VitePress tidak men-generate sidebar otomatis dari struktur folder.
• themeConfig.search.provider: 'local' — pencarian full-text bawaan VitePress, tanpa layanan eksternal (Algolia, dsb).
• Konfigurasi di-wrap dengan withMermaid() dari vitepress-plugin-mermaid agar code block ```mermaid dirender sebagai diagram, bukan teks biasa.

Struktur sidebar memakai nesting bertingkat (items di dalam items) untuk mengelompokkan service — misalnya section "04 Arsitektur" → grup "Services"/"Dashboard"/"Web" → tiap service → halaman Overview/Teknis/Change Log.

Build & Deploy

Perintah Lokal

npm install

# Development server (hot-reload)
npm run docs:dev

# Build statis
npm run docs:build

# Preview hasil build
npm run docs:preview

Docker Produksi (Dockerfile.prod)

Build multi-stage: install dependency → npm run docs:build → hasil docs/.vitepress/dist disalin ke image nginx:stable beserta nginx.conf.

Nginx (nginx.conf)

• Root path (/) di-redirect 301 ke /id/ — locale Indonesia adalah pintu masuk default.
• Asset di /assets/ diberi header cache 10y, immutable (aman karena nama file biasanya tidak berubah setelah publish).
• try_files $uri $uri.html $uri/ =404 — mendukung URL tanpa ekstensi .html sesuai output VitePress.

CI/CD

Pipeline GitLab CI (.gitlab-ci.yml) menjalankan tiga stage saat push ke main: build (SSH ke server, git pull, docker build -f Dockerfile.prod), deploy (docker compose up --force-recreate), dan cleanup (docker builder prune). Tidak ada langkah migrasi database atau service eksternal lain yang terlibat — situs ini murni file statis.

Alur Penulisan Dokumentasi

Dokumentasi arsitektur di situs ini (section Arsitektur) ditulis mengikuti pola konsisten untuk tiap service:

1. Overview — peran service dalam platform, tech stack ringkas, cara kerja singkat, ringkasan satu paragraf.
2. Teknis — repository, tech stack detail, struktur folder, environment variable, endpoint API, diagram alur (mermaid), integrasi eksternal.
3. Change Log — riwayat versi disusun dari git tag dan git log repo masing-masing service, bukan ditulis manual dari ingatan.

Detail konvensi ini didefinisikan dalam skill internal (dokumentasi-teknis) yang dipakai untuk menjaga konsistensi format, termasuk aturan untuk tidak menyalin nilai secret/kredensial apa pun yang ditemukan saat eksplorasi kode ke dalam halaman dokumentasi.