# 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)

```mermaid
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

```mermaid
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

```mermaid
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)

```mermaid
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)

```mermaid
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 (geonet-console `ZammadTicketService`)
    FE-->>User: Tampilkan nomor tiket + pesan sukses
```

---

## 6. Peta Halaman Frontend

```mermaid
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

```mermaid
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)
```env
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`)
```env
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`)
```env
# 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)
```ts
{ 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)
```ts
{ 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.