# BAGIAN 1: ARSITEKTUR UMUM APLIKASI
## (Overall Application Architecture)

---

## 1.1 System Architecture Overview

Diagram ini menunjukkan arsitektur keseluruhan sistem Ortax Omnichannel dari perspektif high-level, mencakup semua layer dari pengguna hingga database.

```mermaid
flowchart TB
    subgraph USERS["PENGGUNA"]
        AGENT["Agent / Staff<br/>Role: member"]
        ADMIN["Admin / Owner<br/>Role: admin, owner"]
        CUSTOMER["Customer<br/>External User"]
    end

    subgraph CHANNELS["EXTERNAL CHANNELS<br/>(Platform API)"]
        WA["WhatsApp Business API<br/>(Meta Graph API)"]
        IG["Instagram Graph API<br/>(Meta Graph API)"]
        TG["Telegram Bot API<br/>(Telegram)"]
        FB["Facebook Messenger<br/>(Meta Graph API)"]
        TT["TikTok<br/>(Planned)"]
    end

    subgraph FE["FRONTEND APPLICATION<br/>React 19 + Vite + MUI v7"]
        direction TB
        FE_AUTH["Auth Module<br/>sign-in, sign-up, forgot/reset password"]
        FE_CHAT["Chat Module<br/>82 files - conversations, messages, real-time"]
        FE_CAMP["Campaign Module<br/>33 files - templates, recipients, execution"]
        FE_TICKET["Ticket Module<br/>25 files - CRUD, lifecycle, attachments"]
        FE_SETTINGS["Settings Module<br/>20+ pages - admin panels"]
    end

    subgraph BE["BACKEND APPLICATION<br/>Hono + Drizzle ORM + Bun"]
        direction TB
        BE_API["API Gateway<br/>/api/v1"]
        BE_AUTH_ENGINE["Better-Auth Engine<br/>session, RBAC, API keys"]
        BE_SERVICES["47 Service Modules<br/>business logic layer"]
        BE_WEBHOOK["Webhook Receivers<br/>WhatsApp, Instagram, Telegram"]
        BE_QUEUE["RabbitMQ Worker<br/>distributed processing"]
    end

    subgraph REALTIME["REAL-TIME LAYER"]
        PUSHER["Pusher<br/>private-room, private-channel, private-post"]
        SOCKET["Socket.IO<br/>new-message, new-conversation"]
    end

    subgraph DB_LAYER["DATABASE & STORAGE"]
        PG["PostgreSQL<br/>schema: omnichannel<br/>30+ tables"]
        UPLOAD["File Storage<br/>Local / S3 / GCS / Azure"]
    end

    USERS -->|"Browser<br/>HTTPS"| FE
    CUSTOMER -->|"Send Message"| CHANNELS
    CHANNELS -->|"Webhook POST"| BE_WEBHOOK
    FE -->|"REST API<br/>/api/v1/*"| BE_API
    BE_API --> BE_AUTH_ENGINE
    BE_API --> BE_SERVICES
    BE_SERVICES --> PG
    BE_SERVICES --> UPLOAD
    BE_WEBHOOK --> BE_QUEUE
    BE_QUEUE --> BE_SERVICES
    BE_SERVICES -->|"Trigger Events"| REALTIME
    REALTIME -->|"Push to Client"| FE
    CHANNELS -->|"API Response"| BE_SERVICES

    style USERS fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    style CHANNELS fill:#FFF3E0,stroke:#FF9800,color:#E65100
    style FE fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    style BE fill:#FCE4EC,stroke:#E91E63,color:#880E4F
    style REALTIME fill:#F3E5F5,stroke:#9C27B0,color:#4A148C
    style DB_LAYER fill:#E0F7FA,stroke:#00BCD4,color:#006064
```

---

## 1.2 User Journey Flowchart (Alur Pengguna Umum)

Diagram ini menunjukkan alur perjalanan pengguna dari pertama kali membuka aplikasi hingga menggunakan fitur-fitur utama.

```mermaid
flowchart TD
    START([User Opens App]) --> HAS_SESSION{Has Active<br/>Session Cookie?}

    HAS_SESSION -->|"Yes"| AUTH_CHECK{Session Valid?<br/>better-auth verify}
    HAS_SESSION -->|"No"| LOGIN["Login Page<br/>/auth/sign-in"]

    AUTH_CHECK -->|"Valid"| HAS_WORKSPACE{Has Active<br/>Workspace?}
    AUTH_CHECK -->|"Invalid / Expired"| LOGIN

    LOGIN --> SIGNIN_PAGE["Sign-In Page<br/>(BetterAuth.SignInPage)"]
    SIGNIN_PAGE --> INPUT_CREDS["Input Email & Password"]
    INPUT_CREDS --> SUBMIT["POST /api/v1/auth/sign-in<br/>better-auth client"]
    SUBMIT --> VALID{Credentials Valid?}
    VALID -->|"No"| SHOW_ERR["Show Error Message<br/>'Invalid email or password'"]
    SHOW_ERR --> SIGNIN_PAGE
    VALID -->|"Yes"| SET_COOKIE["Session Cookie Set<br/>User Context Loaded"]
    SET_COOKIE --> HAS_WORKSPACE

    HAS_WORKSPACE -->|"No"| CREATE_WS["Create Workspace<br/>/dashboard/workspace/create"]
    HAS_WORKSPACE -->|"Yes"| DASHBOARD["Dashboard<br/>Redirect to /dashboard/chat"]

    CREATE_WS --> WS_FORM["Workspace Creation Form<br/>Input: workspace name"]
    WS_FORM --> WS_API["authClient.organization.create()<br/>+ setActive(organization)"]
    WS_API --> DASHBOARD

    DASHBOARD --> SIDEBAR{{"Sidebar Navigation<br/>MainLayout"}}

    SIDEBAR -->|"Chat"| CHAT["/dashboard/chat<br/>Real-time Conversations"]
    SIDEBAR -->|"Social Media"| SOCIAL["/dashboard/social-media<br/>Instagram Posts"]
    SIDEBAR -->|"Campaign"| CAMP["/dashboard/campaign<br/>Marketing Campaigns"]
    SIDEBAR -->|"Contact"| CONTACT["/dashboard/contact<br/>Contact Management"]
    SIDEBAR -->|"Tickets"| TICKET["/dashboard/ticket<br/>Issue Tracking"]
    SIDEBAR -->|"Settings"| SETTINGS["/dashboard/settings<br/>Configuration Panel"]

    CHAT --> CHAT_FLOW["Chat Flow<br/>(see FE Chat Detail)"]
    CAMP --> CAMP_FLOW["Campaign Flow<br/>(see FE Campaign Detail)"]
    TICKET --> TICKET_FLOW["Ticket Flow<br/>(see FE Ticket Detail)"]
    SETTINGS --> SETTINGS_FLOW["Settings Flow<br/>(see FE Settings Detail)"]

    style START fill:#C8E6C9,stroke:#4CAF50
    style DASHBOARD fill:#BBDEFB,stroke:#2196F3
    style SHOW_ERR fill:#FFCDD2,stroke:#F44336
```

---

## 1.3 Application Navigation Structure

Struktur navigasi lengkap yang tersedia di sidebar dashboard.

```mermaid
flowchart LR
    subgraph NAV["Dashboard Navigation (Sidebar)"]
        direction TB
        NAV_MGMT["Management"]
        NAV_CHAT["Chat<br/>/dashboard/chat"]
        NAV_SOCIAL["Sosial Media<br/>/dashboard/social-media"]
        NAV_CAMP["Campaign<br/>/dashboard/campaign"]
        NAV_CONTACT["Contact<br/>/dashboard/contact"]
        NAV_TICKET["Tickets<br/>/dashboard/ticket"]
        NAV_SETTINGS["Settings ▸<br/>/dashboard/settings"]
    end

    NAV_MGMT --> NAV_CHAT
    NAV_MGMT --> NAV_SOCIAL
    NAV_MGMT --> NAV_CAMP
    NAV_MGMT --> NAV_CONTACT
    NAV_MGMT --> NAV_TICKET
    NAV_MGMT --> NAV_SETTINGS

    NAV_SETTINGS --> SET_TAG["Tags<br/>[admin, owner]"]
    NAV_SETTINGS --> SET_USER["Users<br/>[admin, owner]"]
    NAV_SETTINGS --> SET_CH["Channels<br/>[admin, owner]"]
    NAV_SETTINGS --> SET_WS["Workspaces<br/>[owner only]"]
    NAV_SETTINGS --> SET_ACC["My Account<br/>[all roles]"]
    NAV_SETTINGS --> SET_OH["Office Hour & Auto Response<br/>[admin, owner]"]
    NAV_SETTINGS --> SET_QR["Quick Reply<br/>[admin, owner]"]
    NAV_SETTINGS --> SET_API["API Keys<br/>[admin, owner]"]
    NAV_SETTINGS --> SET_RC["Category Resolve<br/>[admin, owner]"]

    style NAV fill:#F5F5F5,stroke:#9E9E9E
    style NAV_SETTINGS fill:#E8EAF6,stroke:#3F51B5
```

---

## 1.4 High-Level Data Flow (Aliran Data Keseluruhan)

```mermaid
flowchart LR
    subgraph INPUT["Input Sources"]
        USER_ACTION["User Actions<br/>(Click, Type, Submit)"]
        WEBHOOK_IN["Channel Webhooks<br/>(WA, IG, TG)"]
    end

    subgraph PROCESSING["Processing Layer"]
        FE_REACT["React App<br/>State Management (SWR)"]
        BE_HONO["Hono Server<br/>Route → Service → Repository"]
        MQ["RabbitMQ<br/>Work Queue"]
    end

    subgraph STORAGE["Storage Layer"]
        PG["PostgreSQL<br/>30+ Tables"]
        FILES["File Storage<br/>Uploads"]
        CACHE["SWR Cache<br/>Client-side"]
    end

    subgraph OUTPUT["Output Channels"]
        UI["UI Rendering<br/>React Components"]
        PUSH_OUT["Pusher + Socket.IO<br/>Real-time Events"]
        PLATFORM_OUT["Platform APIs<br/>Send Messages"]
        EMAIL_OUT["Email<br/>Nodemailer"]
    end

    USER_ACTION --> FE_REACT
    WEBHOOK_IN --> BE_HONO
    WEBHOOK_IN --> MQ
    MQ --> BE_HONO

    FE_REACT -->|"HTTP Request"| BE_HONO
    BE_HONO --> PG
    BE_HONO --> FILES
    FE_REACT --> CACHE

    BE_HONO --> PUSH_OUT
    BE_HONO --> PLATFORM_OUT
    BE_HONO --> EMAIL_OUT
    PUSH_OUT --> FE_REACT
    FE_REACT --> UI

    style INPUT fill:#E8F5E9,stroke:#4CAF50
    style PROCESSING fill:#E3F2FD,stroke:#2196F3
    style STORAGE fill:#FFF3E0,stroke:#FF9800
    style OUTPUT fill:#F3E5F5,stroke:#9C27B0
```

---

## 1.5 Multi-Channel Message Flow

```mermaid
flowchart TD
    subgraph INCOMING["Pesan Masuk"]
        direction LR
        C1["WhatsApp Customer"]
        C2["Instagram User"]
        C3["Telegram User"]
    end

    subgraph WEBHOOKS["Webhook Processing"]
        WH_WA["/api/webhook/whatsapp"]
        WH_IG["/api/webhook/instagram"]
        WH_TG["/api/webhook/telegram"]
    end

    subgraph QUEUE["Message Queue"]
        RABBIT["RabbitMQ<br/>omnichannel_work_queue"]
    end

    subgraph BACKEND["Backend Processing"]
        PARSE["Parse & Normalize Message"]
        FIND_CONTACT["Find or Create Contact"]
        FIND_CONV["Find or Create Conversation"]
        SAVE_MSG["Save to conversation_messages"]
        CHECK_OH{"Within<br/>Office Hours?"}
        AUTO_RESP["Send Auto Response<br/>(if configured)"]
        NOTIFY["Pusher + Socket.IO<br/>Notify Agents"]
    end

    subgraph AGENT_UI["Agent Interface"]
        FE_RECEIVE["Real-time Update<br/>via Pusher/Socket.IO"]
        SWR_UPDATE["SWR Revalidation<br/>Update Conversation List"]
        SHOW_MSG["Display New Message<br/>in Chat UI"]
    end

    C1 -->|"Message"| WH_WA
    C2 -->|"DM/Comment"| WH_IG
    C3 -->|"Message"| WH_TG

    WH_WA -->|"Publish"| RABBIT
    WH_IG -->|"Direct"| PARSE
    WH_TG -->|"Direct"| PARSE
    RABBIT -->|"Consume"| PARSE

    PARSE --> FIND_CONTACT --> FIND_CONV --> SAVE_MSG
    SAVE_MSG --> CHECK_OH
    CHECK_OH -->|"No"| AUTO_RESP
    CHECK_OH -->|"Yes"| NOTIFY
    AUTO_RESP --> NOTIFY

    NOTIFY --> FE_RECEIVE --> SWR_UPDATE --> SHOW_MSG

    style INCOMING fill:#E8F5E9,stroke:#4CAF50
    style WEBHOOKS fill:#FFF3E0,stroke:#FF9800
    style QUEUE fill:#FCE4EC,stroke:#E91E63
    style BACKEND fill:#E3F2FD,stroke:#2196F3
    style AGENT_UI fill:#F3E5F5,stroke:#9C27B0
```
