# jankolancer/livly architecture

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

- Interactive diagram: https://gitdiagram.com/jankolancer/livly
- Repository: https://github.com/jankolancer/livly

## Overview

##### Project Type & Purpose
- Livly is a Slack-integrated leave management system. The primary purpose is to allow users to request various types of leave through Slack interactions while notifying approvers in real time.
- The README and file structure reveal that this is a full-stack Node.js application centered on integrating with Slack’s API for event subscriptions, interactive messages, and bot notifications.

##### Analyzing the File Structure
- Top-Level Directories/Files:
- .env.sample, package.json, shrinkwrap.yaml: Indicate environment configuration and dependency management.
- .github folder: Contains workflows (CI/CD details) for automated testing/deployment.
- images: Stores project assets (like the Slack leave request flow GIF).
- src folder: Contains your application code.
- Inside src:
- api.js: Likely contains endpoint definitions or logic for handling Slack events.
- index.js: The main entry point which probably sets up HTTP servers, middleware, and routes.
- database/dbhelperAWS.js: Handles database interactions, particularly with AWS resources.
- payloads.js: Likely defines message payloads for Slack’s Block Kit messages and modals.
- public folder: Hosts static HTML, CSS, and images used for rendering simple web pages (e.g., contact, index, privacy, and tos).
- verifySignature.js: Provides security logic to verify incoming requests from Slack.

##### README Insights
- The README outlines various integrations with Slack such as event subscriptions (e.g., app_home_opened, channel_left, app_uninstalled) and interactive components (like buttons and modals).
- The document describes the required setup for environment variables, Slack app configuration, and endpoints such as “/events”, “/auth”, and “/interactions.” This means that the application is designed to receive and handle Slack webhook events along with user interactions.

a. Main Components to be included:
- Slack Client & Slack API:
- User interactions occur in Slack, triggering events like app_home_opened or chat actions which then call your endpoints.
- API Gateway / HTTP Server:
- Represented by index.js and possibly routing logic found within api.js.
- Security Module:
- verifySignature.js: Verifies that requests are authentically coming from Slack.
- Database Layer:
- The database component (managed by dbhelperAWS.js) which stores leave requests, approval status, tokens, and notifications.
- Public Content Delivery:
- Static content (HTML/CSS from src/public) that offers parts of the leave management interface or information pages.
- Integration & Notifications:
- Components that handle both outgoing notifications to Slack (via chat:write) and incoming events (managed by payloads.js and API endpoints).

b. Relationships & Interactions:
- Slack sends events to your API endpoints (/events, /auth, /interactions) that are set up in index.js.
- The HTTP Server (API layer) validates incoming requests using verifySignature.js, processes these events according to business logic in api.js and payloads.js.
- When a leave request is made, the backend interacts with the database (via database/dbhelperAWS.js) to store and update leave information.
- The system then sends notifications back to Slack (using Block Kit components) and might also update static content for users viewing the app home.
- There is configuration/deployment integration as implied by the .env.sample and .github workflow files.

c. Important Architectural Patterns/Design Principles:
- Separation of Concerns: Different modules handle routing (index.js), Slack payload and event processing (api.js, payloads.js), database interactions, and signature verification.
- Event-Driven Architecture: The system is built around responding to Slack events, reflecting the asynchronous and interactive nature of the application.
- Modularity: Each component (web server, database helper, public assets) is organized into distinct segments to facilitate maintenance and contribute to the open-source project.

d. Relevant Technologies & Frameworks:
- Node.js and likely Express.js for the HTTP server.
- Slack’s Event API and Block Kit for interface elements and notifications.
- Database handling with AWS (as suggested by the dbhelperAWS.js file).
- GitHub Actions for CI/CD, as seen in the .github/workflows folder.

##### Final Recommendations
- That each component is annotated with key details such as the technology stack (e.g., Node.js, Express) and its role in the processing of Slack events and leave management.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    subgraph "External Systems"
        SC["Slack Client"]:::external
        SA["Slack API"]:::external
    end

    %% API Backend
    subgraph "API Backend"
        HS["HTTP Server (index.js & api.js)"]:::internal
        SV["Signature Verification (verifySignature.js)"]:::verification
        PP["Payload Processing (payloads.js)"]:::internal
        DB["Database (dbhelperAWS.js)"]:::db
    end

    %% Static Content Delivery
    subgraph "Static Content"
        PC["Public Content (src/public)"]:::static
    end

    %% CI/CD & Configuration
    subgraph "CI/CD & Configuration"
        CI["CI/CD & Deployment Config"]:::config
    end

    %% Relationships
    SC -->|"sendEvent"| HS
    HS -->|"validate"| SV
    SV -->|"passValidReq"| PP
    PP -->|"storeOrUpdate"| DB
    HS -->|"notify"| SA
    HS -->|"serveStatic"| PC
    CI -->|"deployConfig"| HS

    %% Styling Classes
    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef internal fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef verification fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef db fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef static fill:#ffe6cc,stroke:#333,stroke-width:2px;
    classDef config fill:#d1c4e9,stroke:#333,stroke-width:2px;

    %% Click Events for Components
    click HS "https://github.com/jankolancer/livly/blob/main/src/index.js"
    click HS "https://github.com/jankolancer/livly/blob/main/src/api.js"
    click SV "https://github.com/jankolancer/livly/blob/main/src/verifySignature.js"
    click PP "https://github.com/jankolancer/livly/blob/main/src/payloads.js"
    click DB "https://github.com/jankolancer/livly/blob/main/src/database/dbhelperAWS.js"
    click PC "https://github.com/jankolancer/livly/tree/main/src/public"
    click CI "https://github.com/jankolancer/livly/tree/main/.github/workflows"
    click CI "https://github.com/jankolancer/livly/blob/main/.env.sample"
    click CI "https://github.com/jankolancer/livly/blob/main/package.json"
    click CI "https://github.com/jankolancer/livly/blob/main/shrinkwrap.yaml"
```
