Technical — Documentation Site

RAGA's documentation site, built on VitePress, deployed publicly at docs.raga.tlab.co.id. Home to both product documentation and technical architecture documentation for every RAGA service.

Repository

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

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

Note: this repository lives under the web namespace, unlike the backend services (service) and admin dashboards (dashboard).

Tech Stack

Layer	Technology
Static Site Generator	VitePress 1.3
Diagrams	vitepress-plugin-mermaid + mermaid (wrapped via withMermaid() in the config)
Web Server (production)	Nginx
Build Runtime	Node.js 20

Folder Structure

documentation-api-chat/
├── docs/
│   ├── .vitepress/
│   │   ├── config.mjs          # Nav, sidebar (per locale), mermaid & search config
│   │   └── cache/               # VitePress build cache (gitignored)
│   ├── index.md                 # Landing page (hero + features); root redirect to /id/ handled in nginx
│   ├── assets/                  # Images/screenshots, used across locales via /assets/... paths
│   ├── id/                      # Indonesian content (primary / root locale)
│   │   ├── introduction/
│   │   ├── getting-started/
│   │   ├── integrations/
│   │   └── architecture/        # Technical architecture docs (this page lives here)
│   └── en/                      # English content, mirrors docs/id/'s structure
├── swagger/                     # Static swagger-ui-dist assets — see the note below
├── nginx.conf                   # Nginx config for serving the build output
├── Dockerfile                   # Development image (docs:dev)
├── Dockerfile.prod              # Multi-stage production build -> Nginx
└── docker-compose.dev.yml

Note: the swagger/ folder at the repo root contains an incomplete copy of swagger-ui-dist (the swagger-initializer.js, index.css, and favicon files referenced by its index.html are missing from this folder). It's also not linked from any VitePress navigation — it looks like leftover from an unfinished/unused attempt at mounting a static Swagger UI.

Configuration (docs/.vitepress/config.mjs)

A single config file drives both locales:

• locales.root — the id (Indonesian) locale, link: '/id/', making it the default locale at the root path.
• locales.en — the en (English) locale, link: '/en/'.
• Each locale has its own themeConfig.nav (top menu) and themeConfig.sidebar (side menu) — both must be updated manually and kept symmetric when adding new pages, since VitePress does not auto-generate the sidebar from folder structure.
• themeConfig.search.provider: 'local' — VitePress's built-in full-text search, no external service (Algolia, etc.).
• The config is wrapped with withMermaid() from vitepress-plugin-mermaid so ```mermaid code fences render as diagrams instead of plain text.

The sidebar structure uses multi-level nesting (items inside items) to group services — e.g. the "04 Architecture" section → "Services"/"Dashboard"/"Web" groups → each service → its Overview/Technical/Change Log pages.

Build & Deploy

Local Commands

npm install

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

# Static build
npm run docs:build

# Preview the build output
npm run docs:preview

Production Docker (Dockerfile.prod)

Multi-stage build: install dependencies → npm run docs:build → the resulting docs/.vitepress/dist is copied into an nginx:stable image along with nginx.conf.

Nginx (nginx.conf)

• The root path (/) is 301 redirected to /id/ — the Indonesian locale is the default entry point.
• Assets under /assets/ get a 10y, immutable cache header (safe since filenames typically don't change after publishing).
• try_files $uri $uri.html $uri/ =404 — supports extension-less URLs matching VitePress's output.

CI/CD

The GitLab CI pipeline (.gitlab-ci.yml) runs three stages on push to main: build (SSH to the server, git pull, docker build -f Dockerfile.prod), deploy (docker compose up --force-recreate), and cleanup (docker builder prune). No database migration or other external service is involved — this site is purely static files.

Documentation Writing Workflow

The architecture documentation on this site (the Architecture section) follows a consistent pattern for every service:

1. Overview — the service's role in the platform, a brief tech stack, how it works, and a one-paragraph summary.
2. Technical — repository, detailed tech stack, folder structure, environment variables, API endpoints, flow diagrams (mermaid), external integrations.
3. Change Log — version history compiled from each service repository's git tag and git log, not written manually from memory.

These conventions are defined in an internal skill (dokumentasi-teknis) used to keep the format consistent, including a rule against ever copying any secret/credential value discovered while exploring source code into a documentation page.