Developer Documentation

Dokumentasi teknis lengkap untuk developer dan admin yang memelihara project AI Chat ini.

Arsitektur Sistem

Quick Start

1. Akses Server

ssh -p 10072 root@69.197.187.172

2. Cek Status Service

pm2 list                    # Cek Express server
ss -tlnp | grep 4096         # Cek AI backend
curl http://127.0.0.1:4096/global/health  # Test health

3. Restart Express

pm2 restart landing-page
pm2 logs landing-page --lines 50

4. Cek AI Backend

systemctl status opencode          # Cek status service
systemctl restart opencode          # Restart jika perlu
journalctl -u opencode -f           # Lihat log

Server Backend (server.js)

Item	Nilai
File	/var/www/landing-page/server.js
Framework	Express 5.2.1
Port	8080
Process Manager	PM2 (fork mode)
OC Proxy Target	127.0.0.1:4096

Konfigurasi

Variable	Nilai	Deskripsi
PORT	8080	Port Express server
OC_PORT	4096	Port AI backend
ADMIN_PASSWORD	AzisAdmin2026!	Password admin panel
MAX_IMAGE_SIZE	4000	Maksimum gambar (px)
RATE_LIMIT	5/60s	Rate limit bug reports

Routing Order (35 Routes)

#	Route	Method	Deskripsi
1	/api/admin/login	POST	Login admin, return token 1 jam
2	/api/generate	POST	Generate dokumen (PDF/DOCX/HTML)
3	/api/documents	GET	List file dokumen
4	/api/documents/:filename	DEL	Hapus dokumen
5	/api/generate-image	POST	Generate gambar via Python
6	/api/sessions	GET	List sesi user
7	/api/sessions	POST	Simpan/update sesi
8	/api/sessions/:id	DEL	Hapus sesi
9	/api/user/token	POST	Buat user token
10	/api/bugs	GET	List bug reports
11	/api/bugs	POST	Kirim bug report (rate limit 5/60s)
12	/api/admin/users	GET	List semua user (admin)
13	/api/admin/user/:userId	GET	Detail sesi user (admin)
14	/api/admin/user/:userId	DEL	Hapus semua sesi user (admin)
15	/api/admin/session/:uid/:sid	DEL	Hapus sesi tertentu (admin)
16	/api/admin/bugreports	GET	List bug (admin)
17	/oc/session/:id/permission/:pid/reply	POST	Reply permission ke AI
18	/oc/*	ALL	Proxy ke ZISCODE AI backend
19	/workspace	GET	Serve workspace home page
20	/workspace/editor	GET	Serve editor page
21	/health	GET	Health check endpoint
22	/api/workspace/projects	GET	List project user
23	/api/workspace/projects	POST	Buat project baru (validasi nama duplikat)
24	/api/workspace/projects/:id	DEL	Hapus project
25	/api/workspace/projects/:id/files	GET	List file project + projectName
26	/api/workspace/projects/:id/newfile	POST	Buat file baru
27	/api/workspace/projects/:id/exec	POST	Jalankan perintah shell (whitelist)
28	/api/workspace/projects/:id/run	POST	Jalankan Node.js/PHP server
29	/api/workspace/projects/:id/deploy	POST	Deploy ke URL publik
30	/api/workspace/projects/:id/rename	PUT	Rename project (validasi duplikat)
31	/api/workspace/projects/:id/duplicate	POST	Duplicate project ("Name - Copy")
32	/api/workspace/projects/:id/file/*	PUT	Save/update file (auto-save)
33	/api/workspace/projects/:id/file/*	DEL	Hapus file
34	/preview/:projectId/:filepath	GET	Preview file (auto-check public/)
35	/deploy/:userId/:projectId/*	GET	Serve deployed files (auto-check public/)

Frontend UI (index.html)

Item	Nilai
File	/var/www/landing-page/public/index.html
Framework	Vanilla HTML/CSS/JS (no framework)
External Libs	highlight.js 11.9.0, Google Fonts Inter
Theme	Dark (Slate palette: #0f172a)

Layout Structure

┌──────────────┬──────────────────────────────────┐
│   SIDEBAR    │              MAIN                │
│  260px       │                                  │
│  - New Chat  │  Header: title + status          │
│  - Sessions  │  Chat Area: messages             │
│  - Footer    │  Input: textarea + send + mode   │
└──────────────┴──────────────────────────────────┘

CSS Classes Penting

Class	Deskripsi
.sidebar	Container sidebar, width 260px
.sidebar.open	Sidebar terbuka (mobile)
.msg.user	Pesan user (biru, kanan)
.msg.ai	Pesan AI (gelap, kiri)
.code-wrap	Code block dengan label bahasa
.mode-badge	Badge BUILD/PLAN
.typing	Animasi 3 dot
.welcome	Layar selamat datang

Mode Chat

Mode	Badge	Deskripsi
build	BUILD	Eksekusi langsung
plan	PLAN	Perencanaan

File Upload

User dapat mengirim file (gambar, dokumen, kode) langsung ke AI tanpa storage server.

Item	Nilai
Metode	Base64 data URI (inline)
Tombol	(attach) di samping textarea
Format	Gambar: png, jpg, gif, webp | Dokumen: pdf, txt, md | Kode: json, csv, py, js, html, css
Max ukuran	10MB per file
Max file	3 sekaligus
Auto-switch	Saat upload file → otomatis pindah ke MiMo V2.5 Free
Preview	Gambar: max 200x150px, klik untuk lightbox | File lain: icon tipe + nama
Persist	Gambar tetap ada setelah reload (disimpan di session JSON)

Model Selector

User dapat memilih model AI melalui dropdown di controls row. Saat upload file, model otomatis switch ke MiMo V2.5 Free (support file + gambar).

Model	File	Gambar	Biaya
big-pickle	❌	❌	Gratis
mimo-v2.5-free	✅	✅	Gratis
deepseek-v4-flash-free	❌	❌	Gratis
hy3-free	❌	❌	Gratis
nemotron-3-ultra-free	❌	❌	Gratis

Markdown Rendering

Syntax	Output	HTML
**teks**	Bold	<strong>
*teks*	Italic	<em>
~~teks~~	Strikethrough	<del>
`kode`	Inline code	<code>
```lang ... ```	Code block	.code-wrap
|header|	Tabel	<table>
---	Garis horizontal	<hr>
# Heading	Bold	<strong>

Image Lightbox

Gambar yang diupload dan ditampilkan di bubble chat bisa diklik untuk melihat versi besar.

Item	Nilai
Trigger	Klik gambar di bubble chat
Tampilan	Overlay gelap (z-index: 600) + gambar besar di tengah
Tutup	Klik × atau klik area gelap
Info	Filename + ukuran di bawah gambar
Mobile	Responsive, tidak buka about:blank

API Reference

Base URL: https://azissn2102.web.id

Public Endpoints

Method	Endpoint	Deskripsi	Auth
GET	/api/sessions	List sesi user	userId param
POST	/api/sessions	Simpan/update sesi	userId in body
DEL	/api/sessions/:id	Hapus sesi	userId param
POST	/api/generate	Generate dokumen	Public
GET	/api/documents	List dokumen	Public
DEL	/api/documents/:name	Hapus dokumen	Public
POST	/api/generate-image	Generate gambar	Public
POST	/api/bugs	Kirim bug report	Rate limit
GET	/api/bugs	List bugs	Public

Admin Endpoints

Method	Endpoint	Deskripsi
POST	/api/admin/login	Login, dapat token
GET	/api/admin/users	List semua user
GET	/api/admin/user/:uid	Detail sesi user
DEL	/api/admin/user/:uid	Hapus semua sesi
DEL	/api/admin/session/:uid/:sid	Hapus sesi
GET	/api/admin/bugreports	List bugs (admin)

Backend Proxy

Method	Endpoint	Target
GET	/oc/global/health	Health check
POST	/oc/session	Buat session AI
POST	/oc/session/:id/message	Kirim pesan
POST	/oc/session/:id/permission/:pid/reply	Balas permission

Session Management

Item	Nilai
Lokasi	/var/www/landing-page/sessions/
Format	JSON per user: {userId}.json
User ID	Cookie chat_uid (auto-generated)

Format Sesi

{
  "id": "sess_abc123",
  "title": "Judul chat (maks 40 char)",
  "messages": [
    { "text": "...", "role": "user|ai", "mode": "build|plan" }
  ],
  "updatedAt": "ISO timestamp"
}

Flow

• Chat baru: POST /oc/session → POST /oc/session/:id/message → POST /api/sessions
• Lanjut chat: POST /oc/session/:id/message → POST /api/sessions
• Hapus: DELETE /api/sessions/:id

Session Data Storage

Disimpan sebagai file JSON di folder sessions/. Setiap user memiliki satu file JSON berisi array sesi.

/var/www/landing-page/sessions/{userId}.json

User ID

• Dibuat otomatis saat pertama kali akses: user_{random}{timestamp}
• Disimpan di cookie chat_uid (expires: 1 tahun)
• Frontend mengirim userId sebagai query parameter atau request body

Server Functions

Function	Deskripsi
getSessionsFile(userId)	Return path file JSON user
loadSessions(userId)	Baca dan parse file JSON
saveSessions(userId, sessions)	Tulis array sesi ke file
sanitize(userId)	Bersihkan userId (hanya [a-zA-Z0-9_-])

Admin Panel

Item	Nilai
File	/var/www/landing-page/public/admin.html
URL	https://azissn2102.web.id/admin.html
Password	AzisAdmin2026!
Token Storage	localStorage (admin_token)
Token Expiry	1 jam (3600 detik)

Fitur

• Users Tab: List user, lihat sesi, hapus sesi/user
• Bugs Tab: Lihat laporan bug dari pengguna
• Autentikasi via header X-Admin-Token

Alur Autentikasi

1. Buka /admin.html
2. Cek token di localStorage
3. Jika ada → cek validitas via GET /api/admin/users
4. Jika valid → tampilkan panel
5. Jika tidak → tampilkan form login
6. Login → POST /api/admin/login → simpan token

Admin Endpoints Detail

Endpoint	Method	Deskripsi
/api/admin/login	POST	Login, dapat token 1 jam
/api/admin/users	GET	List user dengan jumlah session
/api/admin/user/:userId	GET	Detail semua sesi user
/api/admin/user/:userId	DELETE	Hapus SEMUA sesi user
/api/admin/session/:uid/:sid	DELETE	Hapus sesi tertentu
/api/admin/bugreports	GET	List semua bug reports

Backend Proxy

Implementasi

Fungsi proxyToOC() menggunakan req.body (sudah di-parse oleh express.json()).

function proxyToOC(targetPath, req, res) {
  const body = req.body ? Buffer.from(JSON.stringify(req.body)) : Buffer.alloc(0);
  // Forward ke 127.0.0.1:4096
  // Response di-pipe langsung
}

// Generic proxy
app.use("/oc", (req, res) => {
  proxyToOC(req.url, req, res);
});

// Permission proxy (route spesifik)
app.post("/oc/session/:id/permission/:pid/reply", ...)

Error Handling

Error	Response	Penyebab
ECONNREFUSED	502	AI backend tidak berjalan
Timeout	504	Request terlalu lama
EPIPE	502	Koneksi terputus

Permission System

ZISCODE AI meminta izin sebelum menjalankan aksi (baca file, jalankan script, dll).

Alur

User kirim pesan
  → AI proses
    → Butuh izin? → Tampilkan Permission Dialog
      → Allow (Once)    → POST reply: "once"
      → Allow (Always)  → POST reply: "always"
      → Reject          → POST reply: "reject"
    → Setelah reply → Kirim "Lanjutkan" otomatis

Response Permission dari OpenCode

{
  "parts": [{
    "type": "permission-request",
    "id": "perm_xyz123",
    "action": "read file: /etc/passwd",
    "resources": ["/etc/passwd"]
  }]
}

Reply Values

Reply	Deskripsi
once	Izinkan sekali ini saja
always	Izinkan untuk semua aksi serupa
reject	Tolak aksi

Document Generator

User dapat generate dokumen dari respons AI dengan menekan tombol Doc atau otomatis saat pesan mengandung keyword tertentu.

Item	Nilai
Tombol	Doc toggle di controls row + dropdown format
Format	PDF, DOCX, HTML, ODT, RTF, EPUB
Tool	pandoc 3.1.3 + pdflatex
Auto-detect	Keyword: pdf, docx, proposal, dokumen, dll
Auto-generate	Setelah AI respond → POST /api/generate → tampilkan badge download
Badge	PDF Ready — Download
Output	/var/www/landing-page/public/downloads/

Flow

1. Klik tombol Doc → toggle aktif (hijau)
2. Format selector muncul: [PDF] [DOCX] [HTML] [ODT] [RTF] [EPUB]
3. User ketik pesan → kirim
4. AI merespons → otomatis generate dokumen
5. Badge PDF Ready muncul → klik untuk download

Server Functions

Function	Deskripsi
loadBugs()	Baca bugs.json
saveBugs(bugs)	Tulis bugs.json
rateCheck(key, limit, windowMs)	Rate limiting

Pandoc Commands

# PDF
pandoc file.md -o file.pdf --pdf-engine=pdflatex -V geometry:margin=1in -V fontsize=11pt

# DOCX
pandoc file.md -o file.docx

# HTML
pandoc file.md -o file.html --standalone

Bug Reporting

Item	Nilai
Data File	/var/www/landing-page/bugs.json
Rate Limit	5 request / 60 detik per userId
Status	new, reviewed, fixed

Fields yang Dikirim

Field	Max	Deskripsi
message	500 char	Deskripsi bug dari user
rawText	2000 char	Teks mentah pesan AI
htmlSnap	3000 char	Snapshot HTML pesan
userAgent	-	Browser info
viewport	-	Ukuran layar

Frontend Flow

1. Hover pesan AI → tombol "Lapor Bug" muncul
2. Klik → buka modal bug
3. Isi deskripsi (opsional)
4. Klik "Kirim Laporan"
5. POST ke /api/bugs dengan data
6. Toast "Laporan terkirim!" muncul 3 detik

Admin View

1. Buka Admin Panel → tab "Bugs"
2. List bug reports dengan status badge (new = merah)
3. Klik → lihat detail: raw text + metadata

Image Generator

Item	Nilai
Script	/var/www/landing-page/public/generate.py
Library	Python3 + Pillow (PIL)
Max Size	4000 x 4000 px
Output	/var/www/landing-page/public/images/
Format	PNG

# Manual execution
python3 /var/www/landing-page/public/generate.py <width> <height> <color> [filename]

ZISCODE Workspace

IDE berbasis browser untuk coding website. Akses: https://azissn2102.web.id/workspace

Fitur

Fitur	Deskripsi
Buat Project	HTML/CSS/JS, Node.js, PHP
File Tree	Navigasi file, New File/Folder, Delete
Code Editor	CodeMirror 6, syntax highlighting, auto-save
Live Preview	iframe render HTML, auto-refresh
Terminal	xterm.js, jalankan perintah shell
Run Server	Node.js (auto-port), PHP (php -S)
Deploy	Symlink ke /deploy/:userId/:projectId/
AI Assistant	Chat dengan AI, auto-edit kode
Mobile UI	Tab navigation, drawer, responsive

Project Types

Type	Template	Run Command
html	index.html, style.css, script.js	Static (preview only)
node	package.json, server.js	node server.js (auto-port)
php	index.php, style.css	php -S localhost:PORT

Struktur File

/var/www/workspace/
├── projects/
│   └── {userId}/
│       └── {projectId}/
│           ├── .ziscode.json    ← Meta project
│           ├── index.html
│           ├── style.css
│           └── script.js
├── deployed/
│   └── {userId}/
│       └── {projectId}/ → symlink
└── servers/
    └── {userId}_{projectId}.pid

Workspace API

Project Endpoints

Method	Endpoint	Deskripsi
GET	/api/workspace/projects	List project user (dengan fileCount)
POST	/api/workspace/projects	Buat project baru (validasi nama duplikat)
PUT	/api/workspace/projects/:id/rename	Rename project
POST	/api/workspace/projects/:id/duplicate	Duplicate project ("Name - Copy")
DEL	/api/workspace/projects/:id	Hapus project

File Endpoints

Method	Endpoint	Deskripsi
GET	/api/workspace/projects/:id/files	List file project
POST	/api/workspace/projects/:id/newfile	Buat file baru
POST	/api/workspace/projects/:id/exec	Jalankan perintah shell
POST	/api/workspace/projects/:id/run	Jalankan Node.js/PHP server
POST	/api/workspace/projects/:id/deploy	Deploy ke URL publik

Preview & Deploy

Method	Endpoint	Deskripsi
GET	/preview/:projectId/:filepath	Preview file project
GET	/deploy/:userId/:projectId/*	Serve deployed files

Mobile UI

Workspace mendukung mobile dengan tab navigation di bawah layar.

Tab Navigation

Tab	Icon	Fungsi
Files		File tree drawer
Editor		Code editor (CodeMirror)
Preview		Live preview HTML
AI		AI assistant chat
Terminal		xterm.js terminal
Run		Run output panel

Mobile Layout

┌──────────────────────────────┐
│ [←] Project Name  [▶][🚀][📁]│  ← Topbar
├──────────────────────────────┤
│                              │
│  [Editor / Preview / etc]    │  ← Active panel
│                              │
├──────────────────────────────┤
│ [Files][Editor][Preview]     │  ← Tab bar (fixed)
│ [AI][Terminal][Run]          │
└──────────────────────────────┘

Keamanan

Area	Metode	Catatan
Chat UI	Cookie userId	Auto-generated, tidak ada login
Admin Panel	Password + Token	Token 1 jam, header X-Admin-Token
File Delete	Path traversal check	Blokir .., /, \
Bug Report	Rate limiting	5 req/60s per userId
Image Gen	Size limit	Maks 4000px + sanitize input
XSS	escHtml()	Escape <, >, &, " di semua output

Environment

Item	Nilai
OS	Linux (Debian/Ubuntu)
Node.js	v18+ (PM2 managed)
Python	Python 3 + Pillow
Nginx	Reverse proxy (:80 → :8080)
SSH	Port 10072
Express	PM2 (fork mode) — Port 8080
ZISCODE AI	systemd (opencode.service) — Port 4096
VPS IP	69.197.187.172
Domain	azissn2102.web.id
RAM	961MB total (~861MB terpakai)
CPU	1 core (Intel Xeon E3-12xx v2)

Known Issues & Resolved Issues

Resolved Issues

Tanggal	Issue	Perbaikan
22/07	File Persistence hilang saat refresh	Save/restore openTabs ke localStorage
22/07	Tidak ada fitur duplikat project	POST /duplicate + tombol UI
22/07	Tidak ada fitur rename project	PUT /rename + tombol UI
22/07	AI chat tidak auto-scroll	MutationObserver + scrollIntoView
22/07	AI Assistant tanpa icon/formatting	Robot/user icon, code blocks, typing indicator
22/07	Duplicate name validation	Validasi case-insensitive saat buat/rename
21/07	Preview 404 untuk Node.js projects	Auto-check public/ subfolder
21/07	AI JSON Parse Error	Tangkap HTML response, timeout 3 menit
21/07	Font Awesome Icons teks plain	Fix getFileIcon() wrapper + separator
21/07	File Tree Folder tidak bisa collapse	toggleFolder() + chevron + JS display
21/07	"? files" di home page	API menghitung fileCount
21/07	Project ID tampil bukan nama	API /files mengembalikan projectName
21/07	AI chat persist	localStorage ws_ai_{projectId}
21/07	Tab persist	localStorage ws_editor_{projectId}
20/07	ZISCODE Workspace IDE	CodeMirror, Terminal, Preview, Deploy, AI
20/07	ZISCODE branding	Ganti semua referensi OpenCode
17/07	Image Lightbox	Mobile-friendly lightbox overlay
17/07	File upload persist	Gambar tetap setelah reload
17/07	Model selector	MiMo V2.5 Free support file
17/07	Mobile controls row	Compact, wrap
17/07	Format selector alignment	doc-group container
16/07	Proxy Express 5 fix	app.use + req.body
16/07	OpenCode via systemd	opencode.service
16/07	Sidebar UI fix	Flexbox, spacing, mobile
16/07	Markdown rendering	Italic, strikethrough, hr
16/07	Table CSS restore	.msg table styling

Remaining Issues

Status	Issue	Dampak
LOW	Playwright MCP aktif di produksi	Memakan 93MB RAM
NOTE	AI response time bervariasi	1-3 menit tergantung complexity

Changelog

Tanggal	Perubahan	File
22/07	Rename project feature	server.js, workspace.html
22/07	Duplicate project feature	server.js, workspace.html
22/07	File persistence (openTabs restore)	editor.html
22/07	AI auto-scroll (MutationObserver)	editor.html
22/07	Duplicate name validation	server.js
22/07	docs.html comprehensive update	docs.html
21/07	AI Assistant display upgrade	editor.html
21/07	File tree folder toggle	editor.html
21/07	Preview/deploy route fix (public/)	server.js
21/07	Project name display fix	server.js, editor.html
21/07	AI error handling + timeout 3 min	editor.html
21/07	Font Awesome icons fix	editor.html
21/07	AI chat persist (localStorage)	editor.html
21/07	File tabs persist (localStorage)	editor.html
21/07	Duplicate name validation	server.js
21/07	File count display	server.js
20/07	ZISCODE Workspace IDE	workspace.html, server.js
20/07	ZISCODE branding	All files
20/07	Workspace Phase 2 (Terminal, Deploy)	workspace.html, server.js
17/07	Document Generator toggle ( Doc)	index.html
17/07	Image Lightbox (mobile-friendly)	index.html
17/07	File upload persist	index.html
17/07	Model selector (MiMo V2.5 Free)	index.html
17/07	Mobile controls row (compact)	index.html
17/07	Format selector alignment fix	index.html
17/07	Update semua dokumentasi	*.md, docs.html, help.html
16/07	Buat dokumentasi lengkap	docs/*.md, AGENTS.md
16/07	Fix proxy Express 5	server.js
16/07	Jalankan AI via systemd	opencode.service
16/07	Perbaiki sidebar UI	index.html
16/07	Tambah markdown rendering	index.html
16/07	Restore CSS tabel	index.html