How jankolancer/livly works
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.