# Context Index (AI Entry Point)

> **Versi Dokumen:** 1.0.0
> **Terakhir Diperbarui:** 2026-06-23
> **Status:** Aktif
> **Pemilik:** Tim Pengembang GeoNet / GIS Portal

---

# Tujuan

Dokumen ini merupakan **titik masuk utama (Single Entry Point)** bagi seluruh AI Agent dan Developer untuk repository **server-connection**.

Setiap AI **WAJIB** membaca dokumen ini terlebih dahulu sebelum melakukan analisis, implementasi, perubahan kode, refactoring, penghapusan, deployment, maupun pembuatan dokumentasi.

Dokumen ini **bukan** tempat menyimpan seluruh informasi proyek, melainkan **peta navigasi** menuju seluruh dokumentasi yang tersedia.

---

# Filosofi Proyek

Proyek ini menerapkan prinsip **AI Native Development**.

Artinya:

* Dokumentasi adalah bagian dari source code.
* Setiap perubahan wajib terdokumentasi.
* Repository merupakan sumber kebenaran utama (Single Source of Truth).
* AI tidak boleh mengandalkan riwayat percakapan.
* Seluruh pengetahuan proyek harus tersimpan dalam repository.
* Developer sering berpindah perangkat (PC, Laptop, Workstation) — AI Agent harus tetap bisa melanjutkan tanpa riwayat chat.

---

# Aturan Utama AI

Sebelum melakukan pekerjaan apa pun, AI wajib:

1. Membaca file ini (`context-index.md`).
2. Membaca dokumentasi yang berkaitan dengan tugas.
3. Memahami arsitektur yang ada.
4. Memastikan tidak ada konflik dengan keputusan arsitektur sebelumnya.
5. Memperbarui dokumentasi setelah implementasi selesai.
6. Mengikuti protokol sync di `perintah.md` sebelum menyatakan pekerjaan selesai.

Implementasi tanpa dokumentasi dianggap **belum selesai**.

---

# Urutan Membaca Dokumentasi

AI wajib membaca dokumen sesuai urutan berikut:

1. `context-index.md` (file ini)
2. `me.md` — Profil & infrastruktur
3. `perintah.md` — Protokol sync dokumentasi
4. Dokumen spesifik modul (lihat tabel Struktur Dokumentasi di bawah)
5. Rules yang relevan di `.cursor/rules/`

Jangan membaca seluruh repository apabila tidak diperlukan.

---

# Struktur Dokumentasi

## 1. Profil & Infrastruktur

**Lokasi:** `.cursor/me.md`

**Berisi:**

* Profil user (IT end-to-end: network, server, storage, GIS, licensing)
* Stack & aset yang sudah dimiliki (Laravel 12, FastAPI, Python, SQL Server, PostgreSQL)
* Monitoring & Identity (Zabbix, Windows Server 2012 R2 AD)
* Compute & Virtualization (Proxmox, VM Database, VM Docker, VM Ollama)
* Network & Storage (MikroTik CCR2004, QNAP TS-932X)
* Endpoint (laptop user, GPO deploy)
* Lingkungan development (OS dev, Docker lokal, deploy, SSH)
* Ruang lingkup tanggung jawab
* Preferensi kerja (Bahasa Indonesia, jangan duplikasi Zabbix, PostgreSQL untuk baru)
* Aplikasi di repo `server-connection` (geonet-console, databaselist, sqlservercheck)
* URL operasional
* File konteks terkait
* Rules Cursor (prioritas)
* Status proyek
* Deploy cepat

**Ringkasan Profil User:**

User adalah **IT Administrator** yang mengelola infrastruktur end-to-end:

- **Network & Security:** MikroTik CCR2004 (gateway, routing, firewall)
- **Compute & Virtualization:** Proxmox (VM host), PostgreSQL/SQL Server (database), Docker (containers)
- **Identity:** Windows Server 2012 R2 Active Directory (domain user management, GPO deploy)
- **Storage:** QNAP TS-932X (NAS SMB)
- **Monitoring:** Zabbix (alerting real-time)
- **Endpoint:** Banyak laptop user (Windows, domain-joined)
- **GIS & Licensing:** Software licensing tracking

**Preferensi Kerja:**

- Bahasa komunikasi: **Bahasa Indonesia**
- Jangan duplikasi fungsi Zabbix — Zabbix tetap pusat alerting real-time
- PostgreSQL untuk aplikasi/CMDB baru; SQL Server untuk legacy/GIS
- Minimalkan scope perubahan; ikuti konvensi existing code
- Jangan commit kecuali diminta eksplisit
- Documentation first — sinkronkan `.cursor/` setelah sesi besar

**Baca saat:** Selalu — konteks lingkungan & preferensi user.

---

## 2. Rules Cursor

**Lokasi:** `.cursor/rules/`

**Berisi:**

| File | Isi | Scope |
|------|-----|-------|
| `00-project-context.mdc` | Struktur repo, host SSH, deploy | Selalu |
| `01-enterprise-principles.mdc` | Prinsip enterprise & UX wajib | Selalu |
| `02-implementation-status.mdc` | Status fitur geonet-console (audit) | Selalu |
| `03-ai-behavior.mdc` | Perilaku agent, larangan, bahasa | Selalu |
| `04-geonet-uiux.mdc` | Standar UI/UX | `geonet-console/`, `databaselist/` |
| `05-laravel-backend.mdc` | Service layer, API, audit | `*.php` di apps |
| `06-infrastructure.mdc` | SSH, Mikrotik, skrip deploy | `scripts/`, `server/` |

**Baca saat:** Selalu — rules aktif untuk AI Agent.

---

## 3. Perintah (Sync Protocol)

**Lokasi:** `perintah.md` (root repo)

**Berisi:**

* Indeks cepat operasional (profil, konteks repo, status fitur, ringkasan agent)
* Aplikasi & stack produksi
* URL produksi (domain `gisportal.id`)
* Deploy dari laptop (PowerShell scripts)
* File konteks (update saat sync)
* Rules (daftar lengkap)
* Pertanyaan sync (checklist AI wajib akhir sesi)
* Sync terakhir (changelog singkat)

**Baca saat:** Akhir sesi / sebelum nyatakan done (wajib).

---

## 4. AGENTS.md

**Lokasi:** `AGENTS.md`

**Berisi:**

* Rules aktif (daftar lengkap dengan scope)
* Aplikasi utama (geonet-console, databaselist, sqlservercheck)
* Dokumentasi sumber (referensi lengkap)
* Ollama + NAS Project Search (ringkasan agent)
  * Ringkasan keputusan
  * Arsitektur
  * API (target geonet-console)
  * Timeline rekomendasi
  * Checklist go-live
* Verifikasi agent aktif

**Baca saat:** Saat kerja Ollama/NAS search atau verifikasi rules.

---

## 5. Server Documentation

**Lokasi:** `server/`

**Berisi:**

* `host.md` — Daftar host & IP
* Audit server (Mikrotik, database, webserver, AD-LDAP, Zabbix, QNAP, Ollama)
* Konfigurasi Mikrotik (dual-wan, failover, hybrid, split-DNS)
* `migrate-geonet-console.md` — Rencana migrasi databaselist → geonet-console
* `ollama-nas-project-search-requirements.md` — Requirement lengkap Ollama + NAS search
* Konfigurasi nginx, SQL scripts

**Baca saat:** Saat kerja infrastruktur, Mikrotik, atau migrasi.

---

## 6. README & Quick Reference

**Lokasi:** `readme.txt`

**Berisi:**

* SSH commands (Mikrotik, reverse proxy, main database, AD-LDAP)
* Remote Docker Development (model kerja)
* SSH key setup
* Deploy dari laptop (PowerShell scripts)
* URL setelah deploy
* Edit .env di server

**Baca saat:** Saat deploy atau SSH ke server.

---

# Informasi Aplikasi

## Aplikasi di Repo

| Folder | URL Produksi | Stack Server | Status |
|--------|--------------|--------------|--------|
| `geonet-console/` | https://console.gisportal.id | `/opt/stacks/geonet-console/` | ✅ Aktif |
| `databaselist/` | https://databaselist.gisportal.id | `/opt/stacks/databaselist/` | ⚠️ Redirect ke console |
| `sqlservercheck/` | https://sqlservercheck.gisportal.id | `/opt/stacks/sqlservercheck/` | ✅ Aktif |

## URL Produksi

### geonet-console

| Fungsi | URL |
|--------|-----|
| Login / dashboard | https://console.gisportal.id |
| API Clients (OAuth2 + API Tokens + Service Tokens) | https://console.gisportal.id/api-clients |

### databaselist (redirect ke console)

| Fungsi | URL |
|--------|-----|
| Daftar database | https://databaselist.gisportal.id/ |
| LDAP Users | https://databaselist.gisportal.id/ldap-users |
| LDAP Groups | https://databaselist.gisportal.id/ldap-groups |
| DB Connections | https://databaselist.gisportal.id/database-connections |
| Mail SMTP & template | https://databaselist.gisportal.id/mail-settings |
| Audit Logs | https://databaselist.gisportal.id/audit-logs |
| API Docs | https://databaselist.gisportal.id/api-docs |
| Profile (user) | https://databaselist.gisportal.id/profile |
| REST API | https://databaselist.gisportal.id/api/v1 |

### sqlservercheck

| Fungsi | URL |
|--------|-----|
| Tool cek SQL Server | https://sqlservercheck.gisportal.id/ts |
| | https://sqlservercheck.gisportal.id/nts |

---

# Service Tokens

Service Tokens adalah fitur di `geonet-console` untuk mengelola Bearer token microservice secara terpusat. Berbeda dari OAuth2 (flow kompleks) dan API Token (untuk user/script), Service Tokens khusus untuk autentikasi service-to-service sederhana.

## Arsitektur

- **Tabel:** `service_tokens` (di database `geonet_console`, bukan `geonetagent_dev`)
- **Model:** `app/Models/ServiceToken.php`
- **Service:** `app/Services/ServiceTokenService.php`
- **Controller (web):** `app/Http/Controllers/ApiClientController.php`
- **Controller (API):** `app/Http/Controllers/Api/V1/ServiceTokenController.php`
- **Migration:** `database/migrations/2026_06_23_130000_create_service_tokens_table.php`
- **UI:** `/api-clients` — tab ketiga di bawah API Tokens dan OAuth2 Clients

## Schema Tabel

| Kolom | Tipe | Deskripsi |
|-------|------|-----------|
| `id` | UUID PK | Identifier unik |
| `name` | varchar(100) | Nama token (e.g., "GeoNetAgent-Production") |
| `service` | varchar(50) | Nama service (e.g., "GeoNetAgent", "Databaselist") |
| `token_prefix` | varchar(16) unique | 16 karakter awal untuk identifikasi di UI |
| `token_hash` | varchar(64) unique | SHA256 hash token lengkap |
| `is_active` | boolean | Status aktif/revoked |
| `expires_at` | timestamptz nullable | Waktu kedaluwarsa (null = tidak expire) |
| `created_by` | varchar(100) | Username yang membuat token |
| `created_at` | timestamptz | Waktu pembuatan |
| `last_used_at` | timestamptz nullable | Waktu terakhir digunakan |

## API Endpoints (REST)

| Method | Endpoint | Fungsi |
|--------|----------|--------|
| GET | `/api/v1/service-tokens` | List semua token |
| POST | `/api/v1/service-tokens` | Buat token baru |
| GET | `/api/v1/service-tokens/{id}` | Detail token |
| POST | `/api/v1/service-tokens/{id}/revoke` | Revoke (nonaktifkan) |
| POST | `/api/v1/service-tokens/{id}/regenerate` | Regenerate (buat baru, revoke lama) |
| DELETE | `/api/v1/service-tokens/{id}` | Hapus permanen |

## Web Routes

| Method | Route | Fungsi |
|--------|-------|--------|
| POST | `/api-clients/service-tokens` | Buat token (redirect ke `/api-clients`) |
| POST | `/api-clients/service-tokens/{id}/revoke` | Revoke token |
| POST | `/api-clients/service-tokens/{id}/regenerate` | Regenerate token |
| DELETE | `/api-clients/service-tokens/{id}` | Hapus token |

## Zero Impact pada GeoNetAgent

- Database `service_tokens` ada di `geonet_console`, **bukan** di `geonetagent_dev`
- GeoNetAgent collector (`auth.py`) tetap membaca tabel `agent_tokens` di `geonetagent_dev`
- Tidak ada perubahan pada kode collector atau agent PowerShell
- Deploy fitur ini **tidak mengganggu** agent yang sudah terinstall

---

# Informasi Infrastruktur

## Host SSH

| Host | IP | Port | User | Fungsi |
|------|-----|------|------|--------|
| Mikrotik | 10.100.1.1 / 192.168.0.1 | 255 | admin | Gateway, routing, firewall |
| Reverse proxy | 10.100.1.24 | 22 | root | Nginx, Docker, stack `/opt/stacks/*` |
| Main database | 10.100.1.25 | 22 | root | PostgreSQL, SQL Server |
| AD-LDAP | 10.100.1.40 | 22 | Administrator | Windows Server 2012 R2 AD |
| Main webserver | 10.100.1.41 | 22 | Administrator | Web server |
| Zabbix | 10.100.1.42 | 22 | root | Monitoring Server |
| Ollama (aiopr) | 10.100.1.26 | 22 | geonet/root | AI inference (POC) |
| QNAP | 10.100.1.10 | 22 | admin | NAS SMB |

## Model Kerja

Edit kode di laptop → deploy via SSH → build & run di server. **Kredensial `.env` hanya di server**, jangan sync dari laptop.

## Deploy Commands

```powershell
.\scripts\deploy-geonet-console.ps1
.\scripts\deploy-databaselist.ps1
.\scripts\deploy-sqlservercheck.ps1
.\scripts\deploy-databaselist.ps1 -NoBuild   # restart tanpa rebuild
```

---

# Status Fitur (geonet-console)

## Sudah Ada

- Laravel 11, PostgreSQL (app + audit), LDAP auth & manajemen user/grup
- Multi database dinamis (SQL Server, PostgreSQL, MySQL/MariaDB)
- Docker + deploy script + Nginx reverse proxy
- Audit log web/API + beacon page-view/duration
- API v1 + Passport OAuth2 + API token + Swagger UI
- **Service Tokens** — Bearer token management untuk microservice (GeoNetAgent, Databaselist, dll.) di `/api-clients`
- Service layer kuat (15+ services, termasuk `ServiceTokenService`)
- UI: Turbo SPA, dark/light/system, PWA install, tabel mobile action sheet

## Partial

- API Management (belum gateway/rate-plan penuh)
- Security (belum MFA/SSO/RBAC granular)
- Audit immutable (belum DB trigger/hash chain)
- PWA (belum push notification & background sync)
- Production hardening (Tailwind CDN di prod, default password di compose example)
- Clean architecture (Application layer ada, Domain belum)

## Belum

- CMS, MFA, SSO user (SAML/OIDC), Maker Checker, Four Eyes Principle
- Repository pattern, DTO formal, Event driven, Queue processing
- Approval queue UI

---

# Ollama + NAS Project Search

**Status:** Direncanakan (belum diimplementasi di geonet-console).

**Dokumen lengkap:** `server/ollama-nas-project-search-requirements.md`

### Ringkasan Keputusan

| Pertanyaan | Jawaban |
|------------|---------|
| Ollama bisa langsung scan `\\10.100.1.10\project`? | **Tidak** — perlu **indexer + PostgreSQL** |
| Multi-folder (project, Marketing, dll.)? | **Ya** — via env **indexer**, bukan env Ollama |
| Host Ollama POC & CPU | **VM `10.100.1.26` (aiopr)** — dedicated Ubuntu 22.04 |
| Host Ollama GPU (target) | Migrasi **Windows 11 + GPU** (~6 bulan) |
| Model Ubuntu → Windows portable? | **Ya** — copy `~/.ollama/models/` atau `ollama pull` ulang |
| Indeks RAG pindah ke PC Windows? | **Tidak perlu** — tetap di PostgreSQL `10.100.1.25` |
| License code / tanggal expired dari PDF? | **Ya** — `license_registry` + parser terstruktur |

### API Target (geonet-console)

| Endpoint | Method | Fungsi |
|----------|--------|--------|
| `/api/v1/project-search/ask` | POST | Query natural language + optional `sources[]` |
| `/api/v1/project-search/index/status` | GET | Status indeks per source |
| `/api/v1/project-search/sources` | GET | Daftar source dari env |
| `/api/v1/license-search/ask` | POST | Query license natural language |
| `/api/v1/license-search/code/{code}` | GET | Lookup exact license code |
| `/api/v1/license-search/expiring` | GET | License mendekati expired |
| `/api/v1/license-search/reindex` | POST | Re-parse file (admin, audit) |

---

# Checklist Sebelum Implementasi

AI wajib memastikan:

☐ Sudah membaca `context-index.md`

☐ Sudah membaca `me.md` — profil & infrastruktur

☐ Sudah membaca `perintah.md` — protokol sync

☐ Sudah membaca rules yang relevan di `.cursor/rules/`

☐ Sudah memahami status implementasi (`02-implementation-status.mdc`)

☐ Sudah memahami arsitektur yang ada

---

# Checklist Setelah Implementasi

AI wajib memperbarui:

☐ `perintah.md` — sync terakhir (wajib akhir sesi)

☐ `me.md` — jika infrastruktur berubah

☐ Rules yang relevan — jika workflow berubah

☐ `AGENTS.md` — jika ada perubahan roadmap Ollama/NAS

☐ `context-index.md` — jika ada dokumen baru

---

# Prinsip Pengembangan

Setiap perubahan harus memenuhi prinsip berikut:

* Mudah dipahami developer baru.
* Mudah dipahami AI Agent lain (tanpa riwayat chat).
* Mudah diaudit.
* Mudah di-maintain.
* Memiliki rollback plan.
* Memiliki dokumentasi lengkap.
* Tidak menghasilkan technical debt yang tidak terdokumentasi.
* Repository adalah sumber kebenaran utama.

---

# Penutup

Repository ini dirancang agar:

* Developer baru dapat memahami proyek dengan cepat.
* AI Agent mana pun dapat melanjutkan pekerjaan tanpa kehilangan konteks.
* Seluruh pengetahuan proyek tersimpan di dalam repository.
* Dokumentasi selalu selaras dengan implementasi.

Repository adalah sumber kebenaran utama.

Jika terjadi perbedaan antara implementasi dan dokumentasi, AI wajib memperbarui dokumentasi hingga keduanya konsisten.

---

# Bahasa & Gaya

* Komunikasi dengan user: **Bahasa Indonesia**
* Kode & komentar: **English** (konvensi industri)
* Dokumentasi `.cursor/`: **Bahasa Indonesia** (kecuali istilah teknis)