Arsitektur layanan AIOS (ai-middleware), protokol SSE streaming multi-agent, integrasi data mart terdistribusi, pengamanan Zero-Write AST, serta panduan implementasi Backend Eksternal (BFF).

AIOS (`ai-middleware`)

Dokumen Sasaran: Tech Lead, Tim Backend Eksternal (BFF/Gateway), dan Data Engineer
Modul Utama: ai-middleware
Target Integrasi: Aplikasi Web NEXA Platform (Modul Agen AI & Tombol "Tanya AI")
Dokumentasi Frontend UI: Lihat Modul Dashboard: AI Agents

1. Ringkasan Eksekutif & Status Layanan

Gateway kognitif percakapan pada ai-middleware berfungsi sebagai gerbang utama asisten kognitif pimpinan (Analis Keputusan NEXA / GeoGPT). Gateway ini mengorkestrasi agen cerdas spesialis untuk menjawab kueri lintas pilar (keamanan, pangan, risiko wilayah, media) berbasis data riil dari Data Mart analitik NEXA tanpa halusinasi (Strict Grounded Generation).

Fungsionalitas Inti

Pipeline Multi-Agent Hub-and-Spoke:
- Early-Exit Scope Classifier: Memfilter kueri di luar domain operasional intelijen dan kebijakan publik.
- Tabular Analyst: Generator SQL analitik otomatis (Text-to-SQL) ke Data Mart PostgreSQL.
- Media Analyst: Pengekstrak bukti artikel dan isu terkini dari Elasticsearch & MinIO.
- Strategic Analyst: Pengambil memori episodik & konteks historis dari Qdrant Vector DB.
- Gemini Flash Synthesizer: Merangkum temuan seluruh agen menjadi narasi terstruktur dan kartu analitik visual (Hybrid Envelope).
Keamanan Data Mutasi (Strict Zero-Write): AST Parser (validate_and_sanitize_sql) aktif memblokir operasi mutasi (INSERT, UPDATE, DELETE, DROP, ALTER) pada level query planner sebelum menyentuh database.
Autentikasi Tenant API Key & Multi-User Scoping: Validasi header Authorization: Bearer <Tenant-Key> dan isolasi data per operator via X-User-ID: <UUID>.
Context Injection Lintas Modul: Parameter context_module dan context_payload untuk mengakomodasi trigger dari tombol "Tanya AI" pada modul lain (Peta Risiko, Early Warning, dll.).

2. Diagram Alur Integrasi End-to-End

Alur Eksekusi Inferensi AIOS

Siklus hidup inferensi end-to-end dari perayapan hingga intelijen multi-agen

01. Ingestion & Semantic Deduplication [B1/B2/B3 → C1 → C2 Qdrant]

Perayapan multi-kanal, pembersihan tag HTML, dan deduplikasi kemiripan vektor (≥ 0.85).

02. Primary AI Extraction [D1 News • D2 Social • vLLM]

Ekstraksi sentimen (-1 s/d +1), entitas NER, slang normalization, dan summary eksekutif.

03. AI-Middleware & 5-Pilar Agent Orchestration [Hybrid RAG • Multi-Agent Swarm]

Penambahan konteks historis RAG Qdrant dan analisis mendalam oleh 5 agen spesialis pilar.

04. Synthesis & Storage [Aggregation • Decision • Neo4j]

Agregasi statistik, rekomendasi kebijakan early warning, dan sinkronisasi graf relasi.

Alur Orkestrasi AI-Middleware (ai-middleware)

Orkestrasi multi-agent 5-pilar, hybrid RAG Qdrant, dan callback webhook

01. Ingestion Endpoint & Job Tracker [POST /api/v1/inference]

Menerima payload analisis dari D1/D2, memvalidasi schema, dan menetapkan Job ID eksekusi.

02. Hybrid RAG Context Retrieval [Qdrant Dense + BM25 Sparse]

Pencarian konteks latar belakang historis dan referensi regulasi relevan untuk memperkaya prompt agen.

03. 5-Pilar Multi-Agent Orchestration [Sosial / Politik / Ekonomi / Budaya / Hankam]

Routing taksonomi otomatis ke agen pilar spesifik untuk analisis intelijen mendalam berbasis peran.

04. Async Callback & Result Persistence [Webhook HTTP POST • MongoDB]

Mengirim hasil analisis matang kembali ke sistem pemanggil dan menyimpan log audit intelijen.

Alur Integrasi Decision Chat & SSE Streaming (ai-middleware)

Operator → Frontend → BFF Gateway → AIOS → Data Mart Konkuren → Streaming Token & Final Envelope

01. Inisiasi Kueri: Starter Prompt atau Tombol "Tanya AI" [Operator → FE]

Operator mengeklik kartu starter prompt di beranda atau menekan tombol "Tanya AI" dari modul lain dengan membawa konteks spesifik (modul asal dan context payload).

02. Autentikasi Pengguna & Injeksi Tenant API Key [FE → BFF → AIOS]

Frontend mengirim POST /api/chat/decision/stream ke Backend BFF. Backend memvalidasi JWT user, menyuntikkan header Authorization Bearer sk-nexa-... dan X-User-ID, lalu mem-proxy ke AIOS /api/v1/agents/decision-chat/stream.

03. Indikator Status Pemrosesan & Thought Progress [SSE Event: step]

AIOS memancarkan Server-Sent Event (SSE) bertipe "step" ke Backend secara real-time. Frontend merender thought progress untuk menginformasikan tahapan penalaran kepada operator.

04. Eksekusi Konkuren Data Mart Bebas Halusinasi [PG • ES • Qdrant → AIOS]

AIOS mengeksekusi 3 jalur pengambilan data nyata secara paralel: Text-to-SQL pada PostgreSQL Data Mart, pencarian bukti berita di Elasticsearch & S3, dan penarikan memori episodik di Qdrant Vector.

05. Sintesis Model Kognitif & Streaming Token Progresif [SSE Event: chunk]

Gemini Flash Synthesizer merangkai fakta data riil menjadi narasi analisis strategis, memancarkan token teks secara progresif via SSE event "chunk" sehingga teks langsung tertampil di layar obrolan tanpa jeda buffer.

06. Pengiriman Hybrid Envelope & Finalisasi [SSE Event: final_envelope & done]

AIOS mengirimkan payload JSON lengkap (komponen grafik Recharts, tabel data, peta sebaran, dan tombol aksi taktis). Event "done" menandai sesi streaming selesai dan status chat difinalisasi.

3. Matriks Pembagian Tanggung Jawab (RACI Matrix)

Komponen / Fungsionalitas	`ai-middleware`	Backend Eksternal (BE)	Frontend Eksternal (FE)
Pipeline AI & Multi-Agent Synthesis	Responsible (R)	Informed (I)	Informed (I)
Penyediaan Starter Prompts Statis	Informed (I)	Consulted (C)	Responsible (R)
Penerbitan & Pengelolaan Tenant API Key	Responsible (R)	Accountable (A)	-
Autentikasi User & Pengiriman `X-User-ID`	Consulted (C)	Responsible (R)	Accountable (A)
Reverse Proxy Non-Buffering (`X-Accel-Buffering`)	Consulted (C)	Responsible (R)	-
Pengiriman Konteks Tombol "Tanya AI"	Accountable (A)	Support (S)	Responsible (R)
Konsumsi Stream SSE (`step`, `chunk`, `envelope`)	Accountable (A)	Support (S)	Responsible (R)
Rendering Komponen Visual (Recharts, GFM, Chips)	-	-	Responsible (R)

Keterangan RACI

R = Responsible (Pelaksana), A = Accountable (Penanggung jawab), C = Consulted (Konsultan), I = Informed (Penerima info), S = Support (Pendukung).

4. Panduan Implementasi Tim Backend Eksternal (BE / BFF)

Backend Eksternal bertindak sebagai Backend-For-Frontend (BFF) yang mengamankan komunikasi antara browser klien dan gateway ai-middleware.

1. Mendaftarkan & Mengonfigurasi Tenant API Key

Dapatkan API Key unik (sk-nexa-...) melalui modul Gateway Admin ai-middleware (/api/gateway/applications).

Simpan nilai API Key pada Environment Variables Backend:

AI_MIDDLEWARE_BASE_URL=https://api.ai.dev.app-nexa.com
AI_MIDDLEWARE_API_KEY=sk-nexa-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Implementasi Endpoint Proxy SSE (`POST /api/chat/stream`)

Saat menerima request dari antarmuka Web FE:

Validasi token JWT pengguna di header request masuk.
Ekstrak UUID pengguna dari klaim token (user_id).
Lakukan HTTP Stream Proxy ke endpoint ai-middleware:
- URL Target: https://api.ai.dev.app-nexa.com/api/v1/agents/decision-chat/stream
- Headers Wajib:
  - Authorization: Bearer <AI_MIDDLEWARE_API_KEY>
  - X-User-ID: <UUID-Pengguna>
  - Content-Type: application/json
- Body: Teruskan payload JSON dari klien (pertanyaan, session_id, context_module, context_payload).

3. Konfigurasi Reverse Proxy / Ingress Nginx (Kritis)

Wajib Mematikan Response Buffering

Jika proxy Nginx mengaktifkan buffering, efek streaming token per token akan tertahan hingga seluruh respons selesai, merusak pengalaman visual responsif pada antarmuka.

Tambahkan konfigurasi berikut pada blok Nginx gateway:

location /api/chat/stream {
    proxy_pass http://backend_bff_service;

    # Matikan buffering untuk koneksi SSE real-time
    proxy_set_header Connection '';
    proxy_http_version 1.1;
    chunked_transfer_encoding off;
    proxy_buffering off;
    proxy_cache off;

    # Timeout disesuaikan untuk proses reasoning multi-agent
    proxy_read_timeout 60s;
    proxy_send_timeout 60s;

    # Teruskan header identitas
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Pastikan backend juga meneruskan response header X-Accel-Buffering: no ke browser klien.

Header	Tipe	Wajib	Keterangan
`Authorization`	String	Ya	Format: `Bearer sk-nexa-...` (Tenant API Key)
`X-User-ID`	UUID	Ya	ID unik operator untuk isolasi riwayat percakapan
`Content-Type`	String	Ya	`application/json`

Ragam Skenario Payload Request

{
  "pertanyaan": "Bagaimana indeks risiko nasional saat ini?",
  "session_id": null
}

Alur Event Server-Sent Events (SSE)

Nama Event SSE	Tipe Data	Deskripsi
`step`	Text / JSON	Memberikan update status pengerjaan sub-agent (misal: `"Menganalisis indikator risiko..."`, `"Mengecek data mart pangan..."`). Ditampilkan pada thought stepper UI.
`chunk`	Text	Token teks narasi progresif yang dialirkan secara real-time ke komponen Markdown viewer.
`final_envelope`	JSON Object	Objek lengkap berisi narasi final, visualisasi grafik (`chart_data`), bukti sumber data (`evidence`), dan saran prompt interaktif (`suggested_prompts`).
`done`	Text	Penanda bahwa seluruh pemrosesan inferensi selesai. Mengembalikan `session_id` aktif untuk disimpan di state klien.

6. Rencana Pengujian (Test & Validation Plan)

ID Uji	Skenario Pengujian	Hasil yang Diharapkan	Status Target
TC-01	Pengujian SSE Stream Dasar	Teks narasi mengalir token per token dan diakhiri `final_envelope` JSON yang valid.	Wajib Lolos
TC-02	Pengujian Tenant API Key	Request dengan API Key valid diterima; request dengan API Key palsu ditolak HTTP 401.	Wajib Lolos
TC-03	Isolasi Multi-User	User A tidak dapat membaca sesi percakapan atau memori User B melalui `GET /sessions`.	Wajib Lolos
TC-04	Pengujian Context Injection	Pertanyaan pendek seperti "Apa solusinya?" dengan `context_payload` pangan menghasilkan analisis komoditas pangan yang akurat.	Wajib Lolos
TC-05	Honest Timeout Test	Kueri kompleks yang memakan waktu >25 detik menghasilkan status kartu `timeout` yang transparan tanpa memproduksi data palsu/halusinasi.	Wajib Lolos
TC-06	Zero-Write AST Guard	Pertanyaan manipulatif yang berupaya memicu kueri DROP/UPDATE ditolak di tingkat AST parser tanpa menyentuh database.	Wajib Lolos

7. Jadwal & Estimasi Waktu (Timeline)

Fase Pelaksanaan	Penanggung Jawab	Aktivitas Kunci	Periode & Durasi	Status
Fase 1: Kesiapan AI	`ai-middleware`	Penyelesaian fitur & context injection	30 Sep 2026 (1 hari)	`Selesai`
Fase 2: Backend Gateway	Backend Eksternal (BFF)	Setup Tenant API Key, proxy route, & konfigurasi no-buffer	01–02 Okt 2026 (2 hari)	`Berjalan`
Fase 3: Frontend UI	Frontend Eksternal	Starter prompts, integrasi SSE client, & Recharts envelope	01–06 Okt 2026 (6 hari)	`Berjalan`
Fase 4: UAT & Rilis	Seluruh Tim & Tech Lead	Pengujian end-to-end, simulasi error, & validasi final	08 Okt 2026 (2 hari)	`Terjadwal`

AIOS