Monday Connector - Requirements Specification 1. Overview Objective Create a dedicated integration service named vision-monday-connector to act as the integration hub between Velon and Monday.com. The current Monday.com integration logic exists inside Velon and must be migrated into the vision-monday-connector service. The file that handles the service is provided. The target architecture follows a Hub and Spoke Integration Pattern where: * Velon acts as the business application. * vision-monday-connector acts as the integration layer. * Monday.com acts as the external platform. Velon must never communicate directly with Monday.com APIs after this migration. All Monday.com communication must flow through vision-monday-connector. ⸻ 2. Architecture Current State Velon contains: * Monday authentication logic * Webhook processing logic Target State +---------+ | Velon | +---------+ | | REST API v +--------------------------+ | vision-monday-connector | | transform data | | from velon table | | structure into | | monday.com type | +--------------------------+ | | GraphQL API v +-------------+ | Monday.com | +-------------+ For inbound webhook events: +-------------+ | Monday.com | +-------------+ | v +--------------------------+ | vision-monday-connector | | transform data | | into velon tables | | structure format | +--------------------------+ | v +---------+ | Velon | +---------+ ⸻ 3. Design Principles The implementation must follow: SOLID Principles * Single Responsibility Principle * Open Closed Principle * Dependency Inversion Principle Laravel Best Practices * Controllers should remain thin * Business logic should be placed in Services * External API communication should be isolated * Dependency Injection must be used * Interfaces must be introduced where appropriate Architectural Requirements Use a layered architecture: Controllers | Services | Clients / Adapters | External APIs Recommended structure: app/ ├── Http/ │ └── Controllers/ ├── Services/ ├── Contracts/ ├── Clients/ │ └── Monday/ ├── DTOs/ ├── Exceptions/ ├── Transformers/ ├── Webhooks/ ⸻ 4. Authentication Requirements Goal Velon must establish and maintain authentication with Monday.com through vision-monday-connector. Requirements vision-monday-connector must: * Accept Monday access tokens from Velon. * Validate tokens before use. * Use tokens for all GraphQL requests. * Detect expired or invalid tokens. Error Handling If the token is: Expired Return: { "success": false, "error_code": "MONDAY_TOKEN_EXPIRED", "message": "Monday access token has expired." } HTTP Status: 401 Unauthorized Invalid Return: { "success": false, "error_code": "MONDAY_TOKEN_INVALID", "message": "Invalid Monday access token." } HTTP Status: 401 Unauthorized Velon will be responsible for prompting the user to reconnect their Monday account. ⸻ 5. Outbound Operations Outbound operations originate from Velon and are executed by vision-monday-connector against Monday.com. ⸻ 5.1 Create Pricing Calculator Board Item Velon Request POST /api/velon/pc-board/items vision-monday-connector Responsibility * Transform payload to match Monday.com format. * Execute GraphQL mutation. * Return created item information. Response { "success": true, "item_id": "123456" } ⸻ 5.2 Update Pricing Calculator Board Item Velon Request PUT /api/velon/pc-board/items/{itemId} vision-monday-connector Responsibility * Transform payload to match Monday.com format * Build GraphQL mutation. * Execute update. * Return operation result. Response { "success": true } ⸻ 5.3 Add Pricing Calculator Board Line item (Subitem of Board Item) Velon Request POST /api/velon/pc-board/items/line-items vision-monday-connector Responsibility * Transform payload to match Monday.com format * Build GraphQL mutation. * Execute update. * Return operation result. Response { "success": true } ⸻ 6. Inbound Webhook Operations Objective Monday.com webhooks must never call Velon directly. All webhook traffic must first enter vision-monday-connector. ⸻ Flow Monday.com | v vision-monday-connector | (optional transformation) | v Velon ⸻ Supported Operation Update Pricing Calculator Board Item Webhook event generated by Monday.com when a Pricing Calculator board item changes. ⸻ vision-monday-connector Responsibilities Receive Webhook Endpoint example: POST /api/webhooks/monday/pc-board-item-updated Validate Webhook * Validate payload structure. * Validate challenge requests if required by Monday.com. * Validate authenticity if supported. Transform Data Connector may: * Rename fields * Flatten structures * Convert Monday-specific payloads into Velon DTOs Forward Event Forward transformed payload to Velon webhook endpoint. Example: POST /api/webhooks/monday/pc-board-item-updated on Velon. ⸻ 6.1 Monday - Create Pricing Calculator Board Item Monday Request POST /api/webhooks/monday/pc-board/items vision-monday-connector Responsibility * Transform payload to match Velon format. * Call API on Velon and send transformed payload * Return response to Monday. Response { "success": true, "item_id": "123456" } 6.1.1 Get Customer Data from Monday vision-monday-connector Responsibility * Retrieve customer-related board data from incoming Monday request. * Extract Lead/Customer data by calling APIs into Monday.com * Map response into a normalized structure. * Return customer information to Velon. Response { "success": true, "data": [] } ⸻ 6.2 Monday - Update Pricing Calculator Board Item POST /api/webhooks/monday/pc-board/items vision-monday-connector Responsibility * Transform payload to match Velon format. * Call API on Velon and send transformed payload. * Return response to Monday. Response { "success": true, "item_id": "123456" } ⸻ Error Handling Failures forwarding to Velon must: * Be logged. * Return meaningful diagnostics. * Support future retry capability. ⸻ 7. Migration Requirements Existing Code Discovery Claude must: 1. Analyze the existing Velon codebase. The code file containing the Monday.com integration so far is attached. 2. Identify all Monday.com related functionality. 3. Produce an inventory of: * Controllers * Services * GraphQL Queries * GraphQL Mutations * DTOs * Models * Webhook Handlers 4. Document dependencies before moving code. ⸻ Migration Rules Move Move all Monday-specific integration logic into vision-monday-connector. Examples: * GraphQL clients * Monday API wrappers * Board retrieval logic * Item creation logic * Item update logic * Webhook processing logic Keep in Velon Keep only: * Business workflows * Domain logic * UI/API endpoints consumed by frontend * Connector client implementation Velon should only know how to call vision-monday-connector. Velon should not know how Monday GraphQL APIs work. ⸻ 8. Error Management Create centralized exception handling. Suggested exceptions: MondayTokenExpiredException MondayTokenInvalidException MondayApiException MondayWebhookException ConnectorCommunicationException All external failures must be: * Logged * Correlated * Traceable ⸻ 9. Logging Requirements Every request to Monday.com must log: * Request identifier * Operation name * Board identifier * Duration * Success/failure status Sensitive data must not be logged. Do not log: * Access tokens * Authorization headers ⸻ 11. Deliverables Claude must produce: Phase 1 Codebase Assessment * Inventory of existing Monday functionality. * Dependency analysis. * Migration plan. Phase 2 vision-monday-connector Implementation * API endpoints * Services * GraphQL client layer * Authentication handling * Webhook layer * Error handling Phase 3 Velon Refactor * Remove direct Monday.com dependencies. * Introduce connector client. * Update workflows to use vision-monday-connector. Phase 4 Testing Create tests for: * Token validation * Board retrieval * Item creation * Item update * Customer retrieval * Webhook forwarding * Error handling * Connector communication failures All new functionality must be independently testable and follow existing project development standards.