Report 5.3.1 — Tooling & Approach Rationale

This document explains why the chosen stack and design approach were selected for the AISystems FireFlies CRM automation backend.

Language & Framework Choices

Java + Spring Boot enables a deterministic, testable, and programmable service layer that goes far beyond configuring point-and-click automation platforms such as Make or Zapier.

Business logic control: Java lets us encode retries, error handling, and observability directly in code instead of relying on opaque connectors.
Dependency injection & configuration: Spring Boot’s configuration properties, environment wiring, and lifecycle hooks support enterprise-readiness (API keys, data sources, CORS) without custom scripting in each automation task.
Performance & scaling: Running on the JVM supports multi-threaded HTTP clients, connection pooling, and background runners (e.g., HubSpotTaskServiceRunner) that no no-code tool can match.

Spring Web, RestTemplate/HttpHeaders, and simple POJOs make API clients explicit, versionable, and safe; we can add unit tests, logging, and security once, rather than duplicating workflows across GUI connectors.

LLM Integration

OpenAI (gpt-4o-mini) was selected for its strong comprehension of natural language transcripts and ability to emit structured JSON responses.

RestTemplate retains simplicity for direct HTTP interactions with the OpenAI REST API.
Execution metadata (timestamps + durations) is recorded in the service for observability.
ActionItemExtractorService sits between the controller and OpenAIService to keep prompt logic encapsulated.

CRM Integration

HubSpot’s CRM API supports deals/tasks via /crm/v3/objects/deals. The project uses:

Bearer token auth with HUBSPOT_API_KEY.
Custom DTOs to capture response bodies and deletion statuses.
A dedicated tool (HubSpotDeleteDealsMain) for bulk deletion support outside the normal HTTP flow.

Why this approach?

Direct REST calls avoid extra SDK dependencies while keeping control over pagination, retries, and logging for sensitive operations.

Observability & Documentation

PlantUML diagrams across plantuml/behavior and plantuml/structure document the architecture, enabling quick onboarding.

Generated HTML docs sit beside every UML file to provide context and highlight how each diagram relates to the stack.

Deployment & Testing Considerations

Spring profiles and configuration beans (WebConfig, SwaggerUiConfig, AISystemsDataSourceConfig) keep infra setup flexible.
Local testing uses Swagger or manual HTTP clients; sensitive operations like deal deletion are marked as high risk.