# pixaranimationstudios/chook architecture

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

- Interactive diagram: https://gitdiagram.com/pixaranimationstudios/chook
- Repository: https://github.com/pixaranimationstudios/chook

## Overview

##### Project Type & Purpose
- Chook is a Ruby-based framework and gem that sets up a webhook handling server for Jamf Pro. It not only provides a sinatra-based HTTP(S) server to accept and process Jamf webhook POST requests (in JSON) but also supplies a modular framework for writing both internal (Ruby) and external (any language) event handlers.
- Its purpose is to abstract Jamf Pro webhook events into Ruby objects (events and subjects), manage event handling, and provide an admin interface for configuration and log viewing.

##### File Structure
- Top-level files such as README.md, LICENSE.txt, and CHANGES.md indicate standard gem packaging.
- The bin directory contains the chook-server executable used to launch the sinatra-based server.
- The data directory holds:
- A sample configuration file (e.g., chook.conf.example),
- A plist for LaunchDaemon,
- Sample event handler files (both executable and Ruby scripts),
- Sample JSON payloads for each event type.
- The lib directory contains the core Ruby source code:
- The main module definition (chook.rb),
- Submodules for configuration, event handling (e.g., event.rb, handled_event.rb),
- The server-specific code under lib/chook/server, including routes, authentication, logging, static public resources, and view templates.
- Namespaced classes for events and subjects indicating a clear separation of concerns in event processing.
- The presence of numerous subdirectories under lib/chook/ (e.g., event, server, subject) suggests the project adopts modular, layered design, possibly with patterns such as MVC and event-driven architecture.

##### Key Components
a. The HTTP(S) Server Component:
- Sinatra-based web server (launched via chook-server in the bin directory) with endpoints:
- /handle_webhook_event for processing incoming Jamf JSON POSTs.
- / (the admin interface) for monitoring logs, viewing handlers, and configuration.
- SSL configuration branch (noting use_ssl and relevant certificate/key configuration).
b. Core Framework & Event Handling:
- Chook Ruby module and its submodules (lib/chook) that encapsulate:
- Event parsing (Chook::Event and its subclasses)
- Event handling logic (internal handlers defined in Ruby, external handlers as executable files)
- The abstraction of Jamf Pro webhook events into Event and Subject objects.
- Separation between “HandledEvents” (for production use) and “TestEvents” (for simulation).
c. Configuration & Logging:
- A component for Server Configuration (with a node indicating /etc/chook.conf or falling back on defaults found in data/chook.conf.example).
d. Event Handler Directories:
- Differentiate internal handlers (non-executable Ruby files that register with Chook.event_handler) and external handlers (executable files that process raw JSON input).

##### Relations and Interactions
- Jamf Pro Server → (HTTP POST with JSON) → Chook’s /handle_webhook_event endpoint.
- Web Server → (JSON parsing via Chook::Event.parse_event) → Core framework (event and subject object creation).
- Core event handling → (invocation of internal Ruby blocks or external executable calls) → Custom handlers.
- Handlers → Logging component (either directly using event.logger or via an external logging endpoint).
- The Admin Interface → (HTTP GET/POST) → Server management functions (log streaming, handler reloading, config viewing).
- Separation of concerns: communication (networking), event processing, and administration.

##### Architectural Patterns & Technologies to Emphasize
- Event-Driven Architecture: The flow from receiving a webhook to processing via dynamically loaded handlers.
- Modular Design: The use of discrete namespaces (e.g., Chook::HandledEvents, Chook::TestEvents, Chook::Subjects) in the framework.
- MVC-like Aspects: While not a full MVC application, the sinatra server plays a role in managing web interactions (routes, views) and separating presentation (views in haml under lib/chook/server/views) from logic.
- Technologies in Use:
- Ruby and associated gems (sinatra, thin, eventmachine)
- For external handlers: the capability to work with any language (often using shell scripts and JSON tools like jq).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Jamf Pro Webhook Source"]:::external

    subgraph "HTTP Server Layer"
        B["chook-server Executable"]:::server
        C["Handle Webhook Route (/handle_webhook_event)"]:::server
        D["Admin Route (/)"]:::server
    end

    subgraph "Core Framework & Event Handling"
        E["Chook Core"]:::core
        F["Event Parsing"]:::core
        G["Internal Event Handling"]:::core
        H["Handled Events"]:::core
        I["Event & Subject Abstraction"]:::core
    end

    subgraph "External Handlers"
        J["External Handlers (Sample Handlers)"]:::handler
    end

    subgraph "Configuration & Logging"
        K["Configuration Manager"]:::config
        K2["Config Example"]:::config
        L["Server Logging"]:::config
        L2["Event Logger"]:::config
    end

    subgraph "Admin Interface"
        M["Admin Interface (View)"]:::admin
        N["Admin Additional Views"]:::admin
    end

    %% Connections
    A --> B
    B --> C
    B --> D
    K --> B
    E --> F
    C --> F
    F --> G
    F --> I
    G --> H
    G --> J
    G --> L
    G --> L2
    D --> M
    K --> M
    L --> M
    L2 --> M
    M --> N
    K2 --> K

    %% Click Events
    click B "https://github.com/pixaranimationstudios/chook/tree/master/bin/chook-server"
    click C "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/server/routes/handle_webhook_event.rb"
    click D "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/server/routes/home.rb"
    click E "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook.rb"
    click F "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/event.rb"
    click G "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/event_handling.rb"
    click H "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/handled_events.rb"
    click I "https://github.com/pixaranimationstudios/chook/tree/master/lib/chook/subject"
    click J "https://github.com/pixaranimationstudios/chook/tree/master/data/sample_handlers"
    click K "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/configuration.rb"
    click K2 "https://github.com/pixaranimationstudios/chook/blob/master/data/chook.conf.example"
    click L "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/server/log.rb"
    click L2 "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/event/handled_event_logger.rb"
    click M "https://github.com/pixaranimationstudios/chook/blob/master/lib/chook/server/views/admin.haml"
    click N "https://github.com/pixaranimationstudios/chook/tree/master/lib/chook/server/views"

    %% Styles
    classDef external fill:#fceabb,stroke:#e8a600,stroke-width:2px;
    classDef server fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef core fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef handler fill:#ffccbc,stroke:#d84315,stroke-width:2px;
    classDef config fill:#d1c4e9,stroke:#512da8,stroke-width:2px;
    classDef admin fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
```
