# gojek/dollhouse architecture

> Architecture diagram of the GitHub repository gojek/dollhouse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gojek/dollhouse
- Repository: https://github.com/gojek/dollhouse

## Overview

##### Overall Project Type and Purpose
- Dollhouse is a hybrid system consisting of an event-driven backend (using Google Cloud Functions) that processes logs exported via Pub/Sub from an organization’s log sink and a bot/dashboard server component that allows team members to query alert details and view visualizations (with placeholders for a Dashboard and Elasticsearch).
- Its primary goal is to alert on security-related events (e.g., firewall changes, IAM modifications, service account events) and provide automated responses through a Slack bot.

##### Main Components
a. Cloud Logging & Log Sink:

b. Pub/Sub Topic:

c. Cloud Function:
– Inside or alongside this block, note that the Cloud Function’s main entry point is “receive_request” and it dispatches messages based on matching conditions using various rule modules (under cloudfunction/rules). Mention that the “deploy_sink.py” script in cloudfunction/deployments helps configure and update the log sink.

d. Notification and Alert Processing:
– Include a note that the Cloud Function formats and dispatches these alerts, possibly invoking individual “rule” modules for various incident types.

e. Bot Component:
– Note that the bot uses modules (stored in bot/commands) to handle different types of queries regarding incidents in the organization.

f. Server-Side Components (WIP):
- “Dashboard” – for visualization and alert monitoring.
- “Elasticsearch” – for alert storage or search (both noted as WIP).
– Connect these components with the Cloud Function and/or Bot as per your envisioned deployment. They can be shown as separate modules that integrate (e.g., feed back data or provide historical search capabilities).

g. External Services:
– You might also mention that authentication elements (service account credentials, tokens such as SLACK_TOKEN and VERIFICATION_TOKEN) play a significant role in securing these interactions.

##### Architectural Patterns and Technologies
- An event-driven architecture: logs are captured → forwarded via Pub/Sub → processed by a Cloud Function → and notifications are sent out.
- Separation of concerns:
– The Cloud Function is solely focused on processing and dispatching events based on rules.
– The Bot handles interactive queries and command parsing.
– Future extensibility with Dashboard and Elasticsearch suggests a microservices-like layout for scaling different aspects of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GCP Event Processing Layer
    subgraph "GCP Event Processing"
        orgLogSink["Organization Log Sink\n(Filters: FirewallInsert, IAMChanges)"]:::gcp
        pubSub["Pub/Sub Topic: dollhouse-topic"]:::gcp
        orgLogSink -->|"ExportsLogs"| pubSub

        %% Cloud Function Cluster
        subgraph "Cloud Function: dollhouse-cf"
            cfMain["Main: receive_request"]:::gcp
            cfRules["Rule Modules"]:::gcp
            cfDeploy["Deploy Sink Script"]:::gcp
            cfMain --> cfRules
            cfMain --> cfDeploy
        end
        pubSub -->|"Triggers"| cfMain
    end

    %% Notification to Slack
    cfMain -->|"SendsAlerts"| slackNotif["Slack Notification"]:::gcp

    %% External Slack Service
    slackNotif -->|"Delivers"| Slack["Slack"]:::external

    %% Bot Interaction Layer
    subgraph "Bot Component"
        botMain["Bot Service"]:::bot
        botCommands["Command Modules"]:::bot
        botMain --> botCommands
    end
    Slack -->|"AppMentions/Commands"| botMain

    %% Server-Side Components (WIP)
    subgraph "Server-Side Components (WIP)"
        Dashboard["Dashboard"]:::wip
        Elasticsearch["Elasticsearch"]:::wip
    end
    botMain -->|"Queries"| Dashboard
    botMain -->|"Queries"| Elasticsearch

    %% Click Events for Cloud Function components
    click cfMain "https://github.com/gojek/dollhouse/blob/master/cloudfunction/main.py"
    click cfRules "https://github.com/gojek/dollhouse/tree/master/cloudfunction/rules/"
    click cfDeploy "https://github.com/gojek/dollhouse/blob/master/cloudfunction/deployments/deploy_sink.py"
    
    %% Click Events for Bot components
    click botMain "https://github.com/gojek/dollhouse/blob/master/bot/main.py"
    click botCommands "https://github.com/gojek/dollhouse/tree/master/bot/commands/"

    %% Styles
    classDef gcp fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px;
    classDef bot fill:#d5e8d4,stroke:#82b366,stroke-width:2px;
    classDef external fill:#f8cecc,stroke:#b85450,stroke-width:2px;
    classDef wip fill:#fff2cc,stroke:#f1c232,stroke-width:2px;
```
