# connorads/lockbot architecture

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

- Interactive diagram: https://gitdiagram.com/connorads/lockbot
- Repository: https://github.com/connorads/lockbot

## Overview

The Lockbot project is an open-source Node.js application designed to coordinate the locking of shared resources via Slack commands and HTTP API endpoints. The project uses a serverless architecture (as indicated by serverless.yml) and is written in TypeScript, with a clear separation of concerns across multiple modules.

##### Main components
- Slack Command Interface: Represented by the modules inside src/handlers/slack (e.g., command-parsers.ts, handle-command.ts, infra.ts). This component handles Slack interactions (lock, unlock, list locks) triggered by slash commands.
- HTTP API: Shown in src/handlers/api with endpoints that allow API clients to view, create, and delete locks. This module includes its own middleware and type definitions, plus API infra.
- API Documentation / Swagger: Encapsulated in src/handlers/swagger. The OpenAPI spec (openapi.json) and a swagger UI (swagger.html) help document and test the HTTP API.
- Token Authorizer: The src/token-authorizer.ts file indicates that requests are authenticated via API tokens using basic authentication.
- Storage Layer: Lock and token storage implementations exist in src/storage (dynamodb-lock-repo, dynamodb-token-repo, as well as in-memory variants) to persist the state for locks and tokens.
- Deployment and CI/CD: The serverless.yml file, along with the GitHub workflows (.github/workflows), ESLint config, Jest config, and Webpack config indicate continuous integration, linting, testing, and bundling prior to serverless deployment.

##### Establish relationships and interactions
- Slack commands arrive at the Slack Command Handler and are processed (using command-parsers and handle-command modules) to either acquire, list, or release locks.
- The API component exposes HTTP endpoints for similar locking operations. Both channels (Slack and HTTP API) ultimately interact with the same underlying storage layer.
- Token authentication is enforced by the Token Authorizer, which uses API tokens specific to a Slack team, channel, and user.
- The Storage Layer (with both DynamoDB and memory implementations) abstracts the persistence mechanism. Choose DynamoDB in production scenarios and the in-memory repository for local or testing environments.
- The Swagger component provides a UI for exploring the API and automatically generating documentation from the OpenAPI spec.
- The serverless configuration ties everything together, deploying the handlers as serverless functions on AWS, which is managed via CI/CD pipelines (defined in GitHub Actions workflows).

##### Architectural patterns and design principles
- Modular Design: The clear separation between Slack, API, and documentation components supports maintainability and scalability.
- Repositories Pattern: The dual implementations for locks and tokens in the storage layer (DynamoDB vs. in-memory) illustrate the use of interchangeable repositories.
- Serverless Architecture: The use of serverless.yml alongside deployment workflows indicates that individual functions (for Slack commands, API requests) are deployed and scaled independently.
- Security: Basic access authentication for API endpoints is managed through a token authorizer.
- Testing and CI/CD: The existence of tests (with Jest) and GitHub workflows for builds, code analysis, and deployments shows a robust development pipeline.

##### Extra Elements to Ensure
- Clear labels for each component (e.g., “Slack Command Handler”, “HTTP API”, “Token Authorizer”, “DynamoDB Storage”, “In-Memory Storage”).

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    Slack_Client["Slack Client"]:::external
    HTTP_Client["HTTP Client"]:::external

    %% Slack Command Interface Subgraph
    subgraph "Slack Command Interface"
        Slack_Command_Parsers["Command Parsers"]:::slack
        Slack_Handle_Command["Handle Command"]:::slack
        Slack_Infra["Infra"]:::slack
        Slack_Index["Index"]:::slack
    end

    %% HTTP API Subgraph
    subgraph "HTTP API"
        API_Index["Index"]:::api
        API_Infra["Infra"]:::api
        API_Middleware["Middleware"]:::api
        API_Types["Types"]:::api
    end

    %% API Documentation / Swagger Subgraph
    subgraph "API Documentation / Swagger"
        Swagger_OpenAPI["OpenAPI Spec"]:::swagger
        Swagger_UI["Swagger UI"]:::swagger
        Swagger_Index["Index"]:::swagger
    end

    %% Token Authorizer
    Token_Authorizer["Token Authorizer"]:::token

    %% Storage Layer Subgraph
    subgraph "Storage Layer"
        DynamoDB_Lock["DynamoDB Lock Repo"]:::storage
        DynamoDB_Token["DynamoDB Token Repo"]:::storage
        InMemory_Lock["In-Memory Lock Repo"]:::storage
        InMemory_Token["In-Memory Token Repo"]:::storage
    end

    %% Deployment and CI/CD Subgraph
    subgraph "Deployment & CI/CD"
        Serverless_Config["Serverless Config"]:::deployment
        GitHub_Build["GitHub Build Workflow"]:::deployment
        GitHub_CodeQL["GitHub CodeQL Analysis"]:::deployment
        GitHub_Deploy["GitHub Deploy Workflow"]:::deployment
    end

    %% Relationships
    Slack_Client -->|"SlackCommand"| Slack_Handle_Command
    HTTP_Client  -->|"HTTPRequest"| API_Index

    %% Slack to Storage
    Slack_Handle_Command -->|"lockActions"| DynamoDB_Lock

    %% HTTP API flows
    API_Index -->|"authCheck"| Token_Authorizer
    API_Index -->|"lockActions"| DynamoDB_Lock
    API_Index -->|"tokenOps"| DynamoDB_Token

    %% Token Authorizer to Storage
    Token_Authorizer -->|"validateToken"| DynamoDB_Token

    %% Swagger to HTTP API
    Swagger_UI -->|"exploreAPI"| API_Index

    %% Deployment flows
    Serverless_Config -->|"deploys"| Slack_Index
    Serverless_Config -->|"deploys"| API_Index
    Serverless_Config -->|"deploys"| Token_Authorizer
    Serverless_Config -->|"deploys"| Swagger_UI

    %% Click Events for Slack Command Interface
    click Slack_Command_Parsers "https://github.com/connorads/lockbot/blob/master/src/handlers/slack/command-parsers.ts"
    click Slack_Handle_Command "https://github.com/connorads/lockbot/blob/master/src/handlers/slack/handle-command.ts"
    click Slack_Infra "https://github.com/connorads/lockbot/blob/master/src/handlers/slack/infra.ts"
    click Slack_Index "https://github.com/connorads/lockbot/blob/master/src/handlers/slack/index.ts"

    %% Click Events for HTTP API
    click API_Index "https://github.com/connorads/lockbot/blob/master/src/handlers/api/index.ts"
    click API_Infra "https://github.com/connorads/lockbot/blob/master/src/handlers/api/infra.ts"
    click API_Middleware "https://github.com/connorads/lockbot/blob/master/src/handlers/api/middleware.ts"
    click API_Types "https://github.com/connorads/lockbot/blob/master/src/handlers/api/types.ts"

    %% Click Events for API Documentation / Swagger
    click Swagger_OpenAPI "https://github.com/connorads/lockbot/blob/master/src/handlers/swagger/openapi.json"
    click Swagger_UI "https://github.com/connorads/lockbot/blob/master/src/handlers/swagger/swagger.html"
    click Swagger_Index "https://github.com/connorads/lockbot/blob/master/src/handlers/swagger/index.ts"

    %% Click Event for Token Authorizer
    click Token_Authorizer "https://github.com/connorads/lockbot/blob/master/src/token-authorizer.ts"

    %% Click Events for Storage Layer
    click DynamoDB_Lock "https://github.com/connorads/lockbot/blob/master/src/storage/dynamodb-lock-repo.ts"
    click DynamoDB_Token "https://github.com/connorads/lockbot/blob/master/src/storage/dynamodb-token-repo.ts"
    click InMemory_Lock "https://github.com/connorads/lockbot/blob/master/src/storage/in-memory-lock-repo.ts"
    click InMemory_Token "https://github.com/connorads/lockbot/blob/master/src/storage/in-memory-token-repo.ts"

    %% Click Events for Deployment and CI/CD
    click Serverless_Config "https://github.com/connorads/lockbot/blob/master/serverless.yml"
    click GitHub_Build "https://github.com/connorads/lockbot/blob/master/.github/workflows/build.yml"
    click GitHub_CodeQL "https://github.com/connorads/lockbot/blob/master/.github/workflows/codeql-analysis.yml"
    click GitHub_Deploy "https://github.com/connorads/lockbot/blob/master/.github/workflows/deploy.yml"

%% Styles
classDef external fill:#F0E68C,stroke:#333,stroke-width:2px;
classDef slack fill:#FAD7A0,stroke:#333,stroke-width:2px;
classDef api fill:#AED6F1,stroke:#333,stroke-width:2px;
classDef swagger fill:#D5F5E3,stroke:#333,stroke-width:2px;
classDef token fill:#D2B4DE,stroke:#333,stroke-width:2px;
classDef storage fill:#ABEBC6,stroke:#333,stroke-width:2px;
classDef deployment fill:#F5B7B1,stroke:#333,stroke-width:2px;
```
