# clockify/addon-examples architecture

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

- Interactive diagram: https://gitdiagram.com/clockify/addon-examples
- Repository: https://github.com/clockify/addon-examples

## Overview

##### Project type and purpose
- This is a monorepo of “addon” examples for the CAKE.com Marketplace integration with Clockify.
- Each top-level directory (hello-world-go, hello-world-java, iframe-example, pumble-notifications-java, ui-example, weather-example-serverless) is a standalone sample addon illustrating different languages, frameworks, and hosting models.

##### File structure
- Source code (Go, Java, Node.js)
- Manifest files (manifest.json or manifest-v0.1.json) describing the addon interface for CAKE/Clockify
- Static/UI assets in a `public` or `static` folder
- Docker/Docker Compose configs for containerized deployment
- README with setup instructions
- Patterns: Each addon is a small web service (HTTP server or serverless function) exposing two key endpoints:
a. A “manifest” API for the Clockify Marketplace to discover metadata and configuration UI
b. One or more “core” endpoints (UI templates, webhook handlers, business logic)
- Deployment scripts (Dockerfile, compose) & optional local dev proxies (Caddyfile, dev Dockerfile) enable consistent setup across examples.

##### Key insights from the README
- All examples share the same goal: demonstrate how to build a CAKE/Clockify addon.
- No single “system” that ties them together at runtime—they are independent micro-apps.

##### Elements
- Marketplace → GET /manifest
- Marketplace UI ↔ addon UI endpoints
- Clockify → POST webhooks
- Addon → Clockify REST API calls
- Addon → External API calls
- Frontend/UI (light blue)
- Backend/webhook handlers (green)
- Serverless functions (orange)
- External services (gray)

##### Detail is key
- Don’t attempt to merge all examples into one big block—treat each as a separate micro-app.
- Interface contracts (manifest, UI, webhook) for each service.
- Container boundaries or cloud boundaries if relevant (Docker vs. serverless).

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Systems
    CAKE["CAKE.com Marketplace"]:::frontend
    Clockify["Clockify Platform"]:::backend
    Pumble["Pumble Notifications Service"]:::external

    %% Addon Examples Boundary
    subgraph "Addon Examples"
        direction TB

        %% hello-world-go
        subgraph "hello-world-go (Go HTTP Server)" 
            direction TB
            HWG_Service["Service\nhello-world-go"]:::backend
            HWG_Manifest["GET /manifest\n(public/manifest.json)"]:::frontend
            HWG_UI["UI Endpoint\n/templates/ui.html"]:::frontend
            HWG_Webhook["Webhook Handler\n(main.go)"]:::backend
        end

        %% hello-world-java
        subgraph "hello-world-java (Java Spring App)"
            direction TB
            HWJ_Service["Service\nhello-world-java"]:::backend
            HWJ_Manifest["GET /manifest\n(manifest.json)"]:::frontend
            HWJ_UI["UI Endpoint\n(src/resources/ui.html)"]:::frontend
            HWJ_Webhook["Webhook Handler\n(Server.java)"]:::backend
        end

        %% iframe-example
        subgraph "iframe-example (Node.js Express)"
            direction TB
            IFE_Service["Service\niframe-example"]:::backend
            IFE_Manifest["GET /manifest\n(src/endpoints/manifest.js)"]:::frontend
            IFE_UI["UI Endpoint\n(static/sidebar.html)"]:::frontend
            IFE_Webhook["Webhook Handler\n(src/endpoints/index.js)"]:::backend
        end

        %% pumble-notifications-java
        subgraph "pumble-notifications-java (Java Spring App)"
            direction TB
            PNB_Service["Service\npumble-notifications-java"]:::backend
            PNB_Manifest["GET /manifest\n(manifest-v0.1.json)"]:::frontend
            PNB_UI["UI Endpoint\n(n/a)"]:::frontend
            PNB_Webhook["Webhook Handler\n(WebhookHandler.java)"]:::backend
        end

        %% ui-example
        subgraph "ui-example (Node.js Express)"
            direction TB
            UIX_Service["Service\nui-example"]:::backend
            UIX_Manifest["GET /manifest\n(src/manifest-v0.1.json)"]:::frontend
            UIX_UI["UI Endpoint\n(static/index.html)"]:::frontend
            UIX_Webhook["Webhook Handler\n(routes.js)"]:::backend
        end

        %% weather-example-serverless
        subgraph "weather-example-serverless (Serverless Function)"
            direction TB
            WES_Function["Function\nweather-example-serverless"]:::serverless
            WES_Manifest["GET /manifest\n(manifest.json)"]:::frontend
            WES_UI["UI Page\n(index.html)"]:::frontend
        end
    end

    %% Interactions: Manifest Discovery
    CAKE -->|GET /manifest| HWG_Manifest
    CAKE -->|GET /manifest| HWJ_Manifest
    CAKE -->|GET /manifest| IFE_Manifest
    CAKE -->|GET /manifest| PNB_Manifest
    CAKE -->|GET /manifest| UIX_Manifest
    CAKE -->|GET /manifest| WES_Manifest

    %% UI Embedding
    CAKE -->|iframe UI| HWG_UI
    CAKE -->|iframe UI| HWJ_UI
    CAKE -->|iframe UI| IFE_UI
    CAKE -->|iframe UI| PNB_UI
    CAKE -->|iframe UI| UIX_UI
    CAKE -->|iframe UI| WES_UI

    %% Webhook Invocation by Clockify
    Clockify -->|POST webhooks| HWG_Webhook
    Clockify -->|POST webhooks| HWJ_Webhook
    Clockify -->|POST webhooks| IFE_Webhook
    Clockify -->|POST webhooks| PNB_Webhook
    Clockify -->|POST webhooks| UIX_Webhook

    %% Addon Calls
    HWG_Webhook -->|REST API| Clockify
    HWJ_Webhook -->|REST API| Clockify
    IFE_Webhook -->|REST API| Clockify
    PNB_Webhook -->|REST API| Clockify
    UIX_Webhook -->|REST API| Clockify
    WES_Function -->|REST API| Clockify

    %% External Service Call
    PNB_Webhook -->|POST Notify| Pumble

    %% Click Events
    click HWG_Service "https://github.com/clockify/addon-examples/tree/main/hello-world-go/"
    click HWG_Manifest "https://github.com/clockify/addon-examples/blob/main/hello-world-go/public/manifest.json"
    click HWG_UI "https://github.com/clockify/addon-examples/blob/main/hello-world-go/templates/ui.html"
    click HWG_Webhook "https://github.com/clockify/addon-examples/blob/main/hello-world-go/main.go"

    click HWJ_Service "https://github.com/clockify/addon-examples/tree/main/hello-world-java/"
    click HWJ_Service "https://github.com/clockify/addon-examples/blob/main/hello-world-java/pom.xml"
    click HWJ_Service "https://github.com/clockify/addon-examples/tree/main/hello-world-java/Dockerfile"
    click HWJ_Service "https://github.com/clockify/addon-examples/blob/main/hello-world-java/docker-compose.yml"
    click HWJ_Manifest "https://github.com/clockify/addon-examples/blob/main/hello-world-java/src/main/resources/ui.html"
    click HWJ_Webhook "https://github.com/clockify/addon-examples/blob/main/hello-world-java/src/main/java/com/cake/clockify/helloworld/Server.java"
    click HWJ_Webhook "https://github.com/clockify/addon-examples/blob/main/hello-world-java/src/main/java/com/cake/clockify/helloworld/HelloWorldAddon.java"

    click IFE_Service "https://github.com/clockify/addon-examples/tree/main/iframe-example/"
    click IFE_Service "https://github.com/clockify/addon-examples/tree/main/iframe-example/Caddyfile"
    click IFE_Service "https://github.com/clockify/addon-examples/tree/main/iframe-example/Dockerfile"
    click IFE_Service "https://github.com/clockify/addon-examples/blob/main/iframe-example/Dockerfile.dev"
    click IFE_Service "https://github.com/clockify/addon-examples/blob/main/iframe-example/docker-compose.yml"
    click IFE_Manifest "https://github.com/clockify/addon-examples/blob/main/iframe-example/src/manifest-v0.1.json"
    click IFE_Manifest "https://github.com/clockify/addon-examples/blob/main/iframe-example/src/endpoints/manifest.js"
    click IFE_Webhook "https://github.com/clockify/addon-examples/blob/main/iframe-example/src/endpoints/index.js"
    click IFE_UI "https://github.com/clockify/addon-examples/blob/main/iframe-example/static/sidebar.html"

    click PNB_Service "https://github.com/clockify/addon-examples/tree/main/pumble-notifications-java/"
    click PNB_Service "https://github.com/clockify/addon-examples/tree/main/pumble-notifications-java/Dockerfile"
    click PNB_Service "https://github.com/clockify/addon-examples/blob/main/pumble-notifications-java/docker-compose.yml"
    click PNB_Service "https://github.com/clockify/addon-examples/blob/main/pumble-notifications-java/pom.xml"
    click PNB_Webhook "https://github.com/clockify/addon-examples/blob/main/pumble-notifications-java/src/main/java/com/cake/clockify/pumblenotifications/handler/WebhookHandler.java"
    click PNB_Service "https://github.com/clockify/addon-examples/blob/main/pumble-notifications-java/src/main/java/com/cake/clockify/pumblenotifications/NotificationsAddon.java"
    click PNB_Service "https://github.com/clockify/addon-examples/blob/main/pumble-notifications-java/src/main/java/com/cake/clockify/pumblenotifications/model/Installation.java"

    click UIX_Service "https://github.com/clockify/addon-examples/tree/main/ui-example/"
    click UIX_Service "https://github.com/clockify/addon-examples/tree/main/ui-example/Dockerfile"
    click UIX_Service "https://github.com/clockify/addon-examples/blob/main/ui-example/docker-compose.yml"
    click UIX_Service "https://github.com/clockify/addon-examples/blob/main/ui-example/package.json"
    click UIX_Manifest "https://github.com/clockify/addon-examples/blob/main/ui-example/src/manifest-v0.1.json"
    click UIX_UI "https://github.com/clockify/addon-examples/blob/main/ui-example/static/index.html"
    click UIX_Webhook "https://github.com/clockify/addon-examples/blob/main/ui-example/src/routes.js"

    click WES_Function "https://github.com/clockify/addon-examples/tree/main/weather-example-serverless/"
    click WES_Manifest "https://github.com/clockify/addon-examples/blob/main/weather-example-serverless/manifest.json"
    click WES_UI "https://github.com/clockify/addon-examples/blob/main/weather-example-serverless/index.html"

    %% Styles
    classDef frontend fill:#D6EAFE,stroke:#333,stroke-width:1px
    classDef backend fill:#E2F7E1,stroke:#333,stroke-width:1px
    classDef serverless fill:#FFE7B6,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
