LDAPWeb/ARCHITECTURE.md

Arsitektur Super Apps — GIS Portal (my.gisportal.id)

Dokumen ini adalah referensi cepat untuk AI agent / developer baru. Update terakhir: Juli 2026

---

1. Arsitektur Keseluruhan (High-Level)

graph TB
    subgraph USER["Pengguna"]
        BROWSER["Browser / PWA\nmy.gisportal.id"]
        AGENT["GeoNet Agent\n(Windows PC/Laptop)"]
    end

    subgraph SERVER24["App Server — 10.100.1.24 (Docker)"]
        NGINX["Nginx\nReverse Proxy + SSL"]

        subgraph APPS["Aplikasi"]
            FE["my-portal\nNext.js 16 + React 19\nmy.gisportal.id"]
            CONSOLE["geonet-console\nLaravel 11\nconsole.gisportal.id"]
            COLLECTOR["geonet-collector\nFastAPI\nagent.gisportal.id"]
            ZAMMAD["Zammad ⏳\nTicketing\nticket.gisportal.id"]
        end

        subgraph OPS["Operasional"]
            GRAFANA["Grafana + Loki\nMonitoring & Log"]
            N8N["n8n\nAutomation"]
            NODERED["Node-RED\nWorkflow"]
            UPTIME["Uptime Kuma\nUptime Monitor"]
            DOCKGE["Dockge\nDocker Manager"]
        end
    end

    subgraph STORAGE["Storage"]
        PGCONSOLE[("PostgreSQL\ngeonet-console")]
        PGCOLLECTOR[("PostgreSQL\ncollector")]
        OSS["QNAP QuObjects OSS\nfile.gisportal.id\nBucket: super-apps"]
    end

    subgraph IDENTITY["Identity — 10.100.1.40"]
        AD["Windows AD\nLDAP / Active Directory"]
    end

    subgraph PLANNED["Direncanakan ⏳"]
        MAILCOW["Mailcow\nmail.gisportal.id"]
        CONTENT["geonet-content\nPosting/Feed"]
        PUSH["geonet-push\nPush Notification"]
    end

    BROWSER -->|HTTPS| NGINX
    AGENT -->|HTTPS POST report| NGINX
    NGINX --> FE
    NGINX --> CONSOLE
    NGINX --> COLLECTOR
    NGINX -.-> ZAMMAD

    CONSOLE -->|LDAP bind| AD
    CONSOLE --- PGCONSOLE
    CONSOLE -->|S3 API| OSS
    CONSOLE -.->|"create ticket ⏳"| ZAMMAD

    COLLECTOR --- PGCOLLECTOR

    FE -->|"API /api/v1/*"| CONSOLE
    FE -->|"API assets/*"| COLLECTOR
    FE -.->|"Static files"| OSS

---

2. Arsitektur Backend Services

graph LR
    subgraph CONSOLE["geonet-console (Laravel 11)"]
        direction TB
        AUTH["Auth\nLDAP login\nJWT token"]
        ME["Profile /me\navatar OSS"]
        PERM["Permissions\ngroup_permissions\nLDAP group mapping"]
        ASSET_C["Asset API\nbridge ke collector"]
        FEEDBACK["Feedback\nPOST /feedback\nbug & saran"]
        SVCTOKEN["Service Tokens\nmicroservice auth"]
        LDAPMGMT["LDAP Management\nuser, group CRUD"]
    end

    subgraph COLLECTOR["geonet-collector (FastAPI)"]
        direction TB
        INGEST["Agent Ingest\nPOST /report"]
        ASSETS["Asset CRUD\nlist, detail, edit"]
        SNAP["Snapshots\nhardware history"]
        AUDIT_C["Audit Log\nperubahan aset"]
    end

    PGCON[("PostgreSQL\ngeonet-console")]
    PGCOL[("PostgreSQL\ncollector")]
    AD2["Active Directory\n10.100.1.40"]
    OSS2["QNAP OSS\nfile.gisportal.id"]

    AUTH -->|bind| AD2
    ME --> OSS2
    CONSOLE --- PGCON
    COLLECTOR --- PGCOL
    ASSET_C -->|HTTP| COLLECTOR

---

3. Alur Auth & Permission

sequenceDiagram
    participant Browser
    participant FE as my-portal (Next.js)
    participant Console as geonet-console
    participant AD as Active Directory (LDAP)

    Browser->>FE: POST /api/login {username, password}
    FE->>Console: POST /api/v1/auth/login
    Console->>AD: LDAP bind — verifikasi kredensial
    AD-->>Console: OK + groups[]
    Console->>Console: Resolve permissions dari group_permissions
    Console-->>FE: {token, username, groups[], permissions[]}
    FE-->>Browser: Set httpOnly cookie → redirect /dashboard

    Browser->>FE: GET /dashboard
    FE->>Console: GET /api/v1/me (Bearer token)
    Console-->>FE: {username, display_name, groups[], permissions[]}
    FE-->>Browser: Render sidebar/nav (filter by permissions)

---

4. Alur GeoNet Agent (PC Reporting)

sequenceDiagram
    participant PC as Windows PC/Laptop
    participant GPO as Group Policy (AD)
    participant Agent as GeoNet Agent Script
    participant Collector as geonet-collector

    GPO->>PC: Startup/Shutdown Task trigger
    PC->>Agent: Jalankan UserAgent.ps1
    Agent->>Agent: Kumpulkan data hardware\n(CPU, RAM, Disk, GPU, Network, OS)
    Agent->>Agent: Cek versi manifest.json\nauto-update jika ada versi baru
    Agent->>Collector: POST /api/v1/agent/report\n{hostname, snapshot, ...}
    Collector->>Collector: Simpan asset + snapshot
    Collector-->>Agent: 200 OK

    Note over PC,Agent: Task: GeoNetAgent-Report-Startup\nGeoNetAgent-Report-Logon\nGeoNetAgent-Report-Shutdown

---

5. Alur Feedback → Tiket (Rencana Integrasi Zammad)

sequenceDiagram
    participant User as User (Browser)
    participant FE as my-portal
    participant Console as geonet-console
    participant Zammad as Zammad ⏳

    User->>FE: Klik tombol Feedback
    FE->>FE: Tampilkan FeedbackDialog\n(form bug/saran + auto-capture page, user, timestamp)
    User->>FE: Isi form & klik Kirim
    FE->>Console: POST /api/v1/feedback\n{type, title, message, context}
    Console->>Console: Simpan ke tabel feedback
    Console-->>FE: {id, status: open}
    Console-)Zammad: POST /api/v1/tickets ⏳\nauto-create tiket
    FE-->>User: Tampilkan nomor tiket + pesan sukses

---

6. Peta Halaman Frontend

graph TD
    subgraph AUTH["Autentikasi"]
        LOGIN["/login"]
    end

    subgraph APP["App (AuthGuard + Layout)"]
        DASH["/dashboard"]
        PROFILE["/profile"]

        subgraph ASSET["Asset Management"]
            ASSETLIST["/asset-management"]
        end

        subgraph ADMIN["Admin (admin.*)"]
            USERS["/admin/users"]
            GROUPS["/admin/groups"]
            PERMS["/admin/permissions"]
        end

        subgraph PLANNED2["Direncanakan ⏳"]
            TICKET["/ticket\n→ Zammad"]
            MAIL["/mail\n→ Mailcow"]
            MONITOR["/monitoring\n→ Grafana"]
            NOTIF["/notification\n→ Push Service"]
            ATTEND["/attendance"]
            LEAVE["/leave"]
        end

        FEEDBACK_BTN["FeedbackButton\n(floating, semua halaman)"]
    end

    LOGIN --> DASH
    DASH --- PROFILE
    DASH --- ASSETLIST
    DASH --- ADMIN
    DASH --- PLANNED2
    FEEDBACK_BTN -.->|"POST /api/v1/feedback"| CONSOLE2["geonet-console"]

---

7. Infrastruktur & Topologi Jaringan

graph TB
    subgraph INTERNET["Internet"]
        USERS2["Pengguna Eksternal"]
    end

    subgraph LAN["LAN — 10.100.1.x"]
        GW["Mikrotik Gateway\n10.100.1.1"]

        subgraph SERVERS["Servers"]
            S24["10.100.1.24\nApp Server\n(Docker: portal, console,\ncollector, nginx, monitoring)"]
            S25["10.100.1.25\nMain Database\n(PostgreSQL)"]
            S40["10.100.1.40\nAD-LDAP\n(Active Directory)"]
            S42["10.100.1.42\nZabbix\n(Network Monitor)"]
            S26["10.100.1.26\nOllama\n(AI Inference CPU)"]
            QNAP["10.100.1.10\nNAS QNAP TS-932X\n(OSS S3, NFS)"]
        end

        subgraph PROXMOX["Proxmox Hypervisor"]
            PDEV["10.100.1.101\nDev Proxmox"]
            POPR["10.100.1.102\nOpr Proxmox\n(VM 103: monitoring)"]
        end

        subgraph ARCGIS["ArcGIS Enterprise (Dev)"]
            A51["10.100.1.51\nArcGIS Base\n(Portal + Server + DS Relational)"]
            A52["10.100.1.52\nArcGIS DS Object"]
            A53["10.100.1.53\nArcGIS DS Spatio"]
        end
    end

    USERS2 -->|HTTPS| GW
    GW --> S24
    S24 --> S25
    S24 --> S40
    S24 --> QNAP

---

Permission System

Permission Key	Fungsi
profile.view / profile.edit	Halaman profile
dashboard.view	Halaman dashboard
asset_mgmt.view / asset_mgmt.manage	Asset Management
cmdb.view / cmdb.manage / cmdb.assign_owner	CMDB
geonet_agent.view	GeoNet Agent
monitoring.view	Monitoring
ticketing.view / ticketing.create / ticketing.manage	Ticketing
mail.view	Mail
admin.users / admin.groups / admin.permissions	Admin panel

Default group mapping (seeder):

• Domain Admins → semua 17 permissions
• IT-Admin → 13 permissions
• IT-Staff → 11 permissions
• Management → 9 permissions
• Staff/HR → 6 permissions

---

Environment Variables Penting

Frontend (my-portal / Next.js)

NEXT_PUBLIC_API_URL=https://console.gisportal.id
NEXT_PUBLIC_COLLECTOR_URL=https://collector.gisportal.id
NEXT_PUBLIC_COLLECTOR_TOKEN=<token>

Backend geonet-console (Laravel, /opt/stacks/geonet-console)

LDAP_HOST=10.100.1.40
LDAP_PORT=389
LDAP_BASE_DN=DC=geonet,DC=co,DC=id
OSS_ENDPOINT=http://10.100.1.10:8010
OSS_BUCKET=super-apps
OSS_ACCESS_KEY_ID=super-apps:0Jq7KbF31eJzd4k3LSXN

Backend geonet-collector (FastAPI, /opt/stacks/geonetagent-collector)

# Source: /opt/stacks/geonetagent-collector/collector-src/
# Docker build context: ./collector-src

---

Lokasi Server & Deploy

Komponen	Server	Path	Deploy Command
FE Next.js	10.100.1.24	/opt/stacks/my-portal/	docker compose build && up -d
geonet-console	10.100.1.24	/opt/stacks/geonet-console/	docker compose up -d
geonet-collector	10.100.1.24	/opt/stacks/geonetagent-collector/	docker compose build && up -d
Nginx config	10.100.1.24	/etc/nginx/conf.d/	nginx -s reload

SSH akses: ssh -m hmac-sha1 root@10.100.1.24 -p 22

---

Schema Key — Collector API

CollectorAsset (list item)

{ id, hostname, display_name, asset_type, status, manufacturer, model,
  serial_number, owner_ldap_username, owner_display_name, owner_email,
  last_seen_at, snapshot_count, primary_physical_mac }

CollectorSnapshotSummary (flat — root level, BUKAN nested .system)

{ os_name, os_version, os_build, cpu_model, ram_gb, gpu_model,
  last_boot_at, agent_version,
  system?: { form_factor, chassis_label, ... },
  cpu?: { model, cores, logical_processors, max_clock_mhz },
  disks?: [...], network?: [...], memory_summary?: {...} }

---

Microservice Yang Direncanakan (Belum Dibangun)

Service	Domain (rencana)	Status
Mailcow	mail.gisportal.id	🔴 Belum
Zammad (ticketing)	zammad.gisportal.id	🔴 Belum
geonet-content (posting)	content.gisportal.id	🔴 Belum
geonet-push (push notif VAPID)	push.gisportal.id	🔴 Belum

Lihat backlog.md untuk detail tugas dan prioritas pengerjaan.