Report 9.2 — System OverviewWritten Guide

This document serves as the detailed answer to item 9.2, consolidating architectural insights, data flows, and operability guidance for the AISystems FireFlies CRM automation backend.

Architecture Summary

The application is a Spring Boot backend that orchestrates OpenAI and HubSpot APIs. Core packages include:

Controllers: expose REST endpoints for OpenAI interactions and HubSpot task/deal operations.
Services: encapsulate business logic: OpenAIService for completions, HubSpotTaskService for CRM operations, and ActionItemExtractorService for parsing transcripts.
Tools/config: standalone runners (HubSpot property tooling/files) and configuration classes (Swagger, Web config, datasource via Hikari).

Key Flows

Transcript generation → OpenAI, returning sample data.
Transcript parsing → action items & HubSpot task creation.
Conditional cleanup flow that deletes all HubSpot deals (paged API calls).

Detailed Component Insights

OpenAITestController

Receives CLI/HTTP prompts, routes them to services, and exposes endpoints for creation, extraction, random transcripts, and metadata reporting.

OpenAIService

Calls gpt-4o-mini chat completions, handles retries, and surfaces execution timestamp/duration for diagnostics.

HubSpotTaskService

Creates deals, batches action items, and offers a deleteAllHubSpotDeals() flow that fetches paginated IDs and deletes each, returning structured report DTOs.

ActionItemExtractorService

Bridges controllers and services, invoking OpenAI completions and converting results into HubSpot-ready payloads.

Behavioral & Deployment Diagrams

Refer to the PlantUML diagrams in the plantuml/ folder for visualization:

Class Diagram for static relationships.
Sequence Diagram for request lifecycle.
Activity Diagram for workflow segments.
Deployment Diagram for runtime nodes.

All UML files have matching HTML docs under plantuml/behavior and plantuml/structure describing their purpose, highlights, and source.

Operations & Usage Guidance

Env variables required

Set OPENAI_API_KEY and HUBSPOT_API_KEY before running.

Swagger UI

Visit /swagger-ui/ once the app is running (custom controller serves the UI).

HubSpot cleanup

The deletion endpoint returns HubSpotDealDeletionReport detailing total found/deleted/failed entries.

Testing & Validation

Run Gradle tests (if available) or manually hit endpoints using HTTP clients. Confirm the generated diagrams match current code for accuracy.

Always validate HubSpot API interactions in a sandbox account, especially the delete-all flow—it cannot be undone.