How amrutjadhav/cardchecker works
Project Overview
• CardChecker is a Node.js application that listens to Trello webhook events when a new card is created or updated. It validates the card against a set of predefined rules (e.g., title word count, presence of description, due date checks, etc.) and, when issues are detected, it sends notifications to one or more messaging platforms (Slack, Teams, or Flock).
• The project is structured in a modular way with clear separation between controllers, validation rules, job processors, publishers, and utility functions.
Main Architectural Components
a. External Integrations:
• Trello: Source of webhook events. Trello sends card creation/updates to the CardChecker’s webhook endpoint.
• Messaging Platforms: Slack, Teams, and Flock—CardChecker pushes notifications to these channels if a card does not adhere to the configured standards.
b. Core Application Layers:
• Web Server / Entry Point: (index.js) The main entry point which likely initializes the server, routes, and middleware.
• Controllers Layer (app/controllers):
• Configuration Controller (configuration_controller.js): Handles API endpoints for subscribing Trello webhooks and configuration changes.
• Event Controller (event_controller.js): Receives and processes events from Trello.
• Handlers and Jobs:
• Handlers (app/handlers, e.g., card.js): Likely responsible for processing business logic around cards (parsing, normalization).
• Jobs (app/jobs, e.g., trello_checker.js): Potential background tasks, such as regularly checking card statuses or processing webhook events asynchronously.
• Models & Rules:
• Models (app/models/card.js): Representing the data structure for a Trello card.
• Rules (app/rules/card.js): Contains the logic for each card validation rule.
• Publishers (app/publishers):
• Code for each publisher (flock.js, slack.js, teams.js): Manages integration with respective messaging platforms to send notifications.
• Utilities (app/utilities):
• Utility functions (e.g., app/utilities/common.js and card.js): For common operations like parsing, formatting, or shared helper methods related to cards.
• Message Templates:
• A dedicated file (app/message_template.js) for constructing the content of notifications.
• Configuration:
• A default pipeline configuration file under config (config/default_pipeline_config.yml) that defines the behavior of the card checking rules.
• Additional configuration management (e.g., pipeline_config_validator.js) ensuring any provided pipeline_config overlays are valid.
• Logger configuration (config/logger.js) likely for standardized logging.
Relationships & Data Flow
• A Trello webhook event triggers an API call handled by the Event Controller.
• The controller calls upon the handler and model logic to extract and standardize the card data.
• The Rules layer validates the card against each predefined rule (using configurations from the pipeline YAML) to decide whether the card meets the standards.
• If a card does not pass validation, the Publishers are invoked to send notification messages to the appropriate external messaging service.
• The Configuration Controller provides endpoints to register new webhooks and update any pipeline configurations dynamically.
• Jobs (like trello_checker.js) might be scheduled or triggered asynchronously to perform additional checks or updates, ensuring that card validations are continuously enforced.
Architectural Patterns and Design Principles
• Modular Separation: The clear separation into controllers, handlers, models, rules, and publishers reflects a well-organized modular design.
• MVC-like Structure: Even if not a full MVC framework, the separation of concerns (e.g., controllers handling API endpoints and models representing core data) is evident.
• Extensibility: Publishers and rule modules are isolated, which allows for straightforward additions or modifications when integrating new messaging services or card rules.
• Configuration Overriding: The use of a default pipeline configuration that can be overridden by a user-specified configuration file (pipeline_config.json) encourages flexibility.