# sctg-development/turgeand-messaging architecture

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

- Interactive diagram: https://gitdiagram.com/sctg-development/turgeand-messaging
- Repository: https://github.com/sctg-development/turgeand-messaging

## Overview

##### Project type and purpose
- This is a serverless, event-driven microservice built as a Cloudflare Worker.
- Its primary purpose is to receive SMS webhooks from Twilio, persist them in Cloudflare KV storage, and expose a secured API to retrieve stored messages.

##### File structure
- Top-level scripts and configs:
- package.json, tsconfig.json, vitest.config.mts, .github/workflows/vitest.yml (build, test, CI)
- gen_api_password.sh, setlicense.mjs, scripts to encrypt/decrypt sensitive data under `_sensitive_datas`
- src/index.ts – The Worker’s entry point, implementing HTTP handlers for `/twilio/incoming` and `/twilio/read`.
- test/… – Local unit and integration tests (Vitest, shell wrapper).
- worker-configuration.d.ts – Type bindings for KV namespaces and environment variables.

##### README for additional insights
- Endpoints:
- POST /twilio/incoming – parses Twilio’s form-encoded webhook, writes to KV with key `INCOMING:{to}:{MessageSid}`
- GET  /twilio/read?to={number} – Basic Auth, reads all keys matching `INCOMING:{to}:*`, returns JSON array
- KV namespace: “TWILIO_KV” for both messages and user password hashes (`USER:{username}`)
- Authentication: bcrypt-based password hashes stored in KV, validated in the Worker
- Development and deployment use Wrangler; CI runs Vitest on GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph "External Systems"
        direction TB
        Twilio["Twilio SMS API"]:::external
        Client["Client/Administrator"]:::external
    end

    %% Cloudflare Edge Compute
    subgraph "Cloudflare Edge"
        direction TB
        Incoming["Worker: POST /twilio/incoming"]:::compute
        Read["Worker: GET /twilio/read"]:::compute
        Config["Env & KV Bindings\n(worker-configuration.d.ts)"]:::compute
    end

    %% Persistent Storage
    KV["Cloudflare KV\n(SMS Messages & User Hashes)"]:::storage

    %% Development & Deployment Tools
    subgraph "Dev & Deploy Tools"
        direction TB
        CI["GitHub Actions CI"]:::dev
        subgraph "Tests"
            direction TB
            IndexSpec["test/index.spec.ts"]:::dev
            TestShell["test/test.sh"]:::dev
            EnvD["test/env.d.ts"]:::dev
            VitestConfig["vitest.config.mts"]:::dev
        end
        subgraph "Offline Scripts"
            direction TB
            GenPwd["gen_api_password.sh"]:::dev
            Store["_sensitive_datas/store_sensitive_datas"]:::dev
            Restore["_sensitive_datas/restore_sensitive_datas"]:::dev
            Archive["_sensitive_datas/_sensitive_datas.tar.xz.enc"]:::dev
            License["setlicense.mjs"]:::dev
        end
        subgraph "Project Config"
            direction TB
            Package["package.json"]:::dev
            TSConfig["tsconfig.json"]:::dev
            Lock["package-lock.json"]:::dev
            Editor[".editorconfig"]:::dev
            Prettier[".prettierrc"]:::dev
            Gitignore[".gitignore"]:::dev
        end
    end

    %% Data Flows
    Twilio -->|POST webhook| Incoming
    Incoming -->|write SMS| KV
    Client -->|GET messages + BasicAuth| Read
    Read -->|read hash| KV
    KV -->|return messages| Read
    Read -->|respond JSON| Client

    CI -->|runs tests| IndexSpec
    CI -->|runs tests| TestShell
    CI -->|runs tests| EnvD
    CI -->|runs tests| VitestConfig
    IndexSpec -->|executes against| Incoming
    TestShell -->|executes against| Incoming

    GenPwd -->|produces hash| KV
    Store -->|store encrypted data| Archive
    Restore -->|restore encrypted data| KV

    %% Click Events
    click Incoming "https://github.com/sctg-development/turgeand-messaging/blob/main/src/index.ts"
    click Read "https://github.com/sctg-development/turgeand-messaging/blob/main/src/index.ts"
    click Config "https://github.com/sctg-development/turgeand-messaging/blob/main/worker-configuration.d.ts"
    click CI "https://github.com/sctg-development/turgeand-messaging/blob/main/.github/workflows/vitest.yml"
    click IndexSpec "https://github.com/sctg-development/turgeand-messaging/blob/main/test/index.spec.ts"
    click TestShell "https://github.com/sctg-development/turgeand-messaging/blob/main/test/test.sh"
    click EnvD "https://github.com/sctg-development/turgeand-messaging/blob/main/test/env.d.ts"
    click VitestConfig "https://github.com/sctg-development/turgeand-messaging/blob/main/vitest.config.mts"
    click GenPwd "https://github.com/sctg-development/turgeand-messaging/blob/main/gen_api_password.sh"
    click Store "https://github.com/sctg-development/turgeand-messaging/tree/main/_sensitive_datas/store_sensitive_datas"
    click Restore "https://github.com/sctg-development/turgeand-messaging/tree/main/_sensitive_datas/restore_sensitive_datas"
    click Archive "https://github.com/sctg-development/turgeand-messaging/blob/main/_sensitive_datas/_sensitive_datas.tar.xz.enc"
    click License "https://github.com/sctg-development/turgeand-messaging/blob/main/setlicense.mjs"
    click Package "https://github.com/sctg-development/turgeand-messaging/blob/main/package.json"
    click TSConfig "https://github.com/sctg-development/turgeand-messaging/blob/main/tsconfig.json"
    click Lock "https://github.com/sctg-development/turgeand-messaging/blob/main/package-lock.json"
    click Editor "https://github.com/sctg-development/turgeand-messaging/blob/main/.editorconfig"
    click Prettier "https://github.com/sctg-development/turgeand-messaging/blob/main/.prettierrc"
    click Gitignore "https://github.com/sctg-development/turgeand-messaging/blob/main/.gitignore"

    %% Styles
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef compute fill:#e0f7ff,stroke:#333,stroke-width:1px
    classDef storage fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef dev fill:#e8f5e9,stroke:#333,stroke-width:1px
```
