# alexsantosfilho/hubspot_integration architecture

> Architecture diagram of the GitHub repository alexsantosfilho/hubspot_integration, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexsantosfilho/hubspot_integration
- Repository: https://github.com/alexsantosfilho/hubspot_integration

## Overview

##### Project Type and Purpose
- The project is a backend integration API built using Spring Boot.
- Its primary purpose is to integrate with HubSpot: managing OAuth 2.0 authentication, contact creation, processing of webhook events, and serving an interactive API documentation with Swagger.
- Key functionalities include handling authentication redirection, exchanging authorization codes, and performing business logic for contact management and webhook processing.

##### File Structure
- The top-level structure includes Maven configuration files (pom.xml, mvnw, etc.) and a well-organized src directory.
- Under src/main/java, the package structure “com.hubspot.integration” indicates a layered architecture:
- Application Entry: IntegrationApplication.java serves as the Spring Boot starting point.
- Configurations: The “config” package (RestTemplateConfig.java, SecurityConfig.java) defines settings for REST communications and security (e.g., OAuth flow and webhook signature validation).
- Controllers: The “controller” package is split into “api” (for endpoints such as ContactController and OAuthController) and “webhook” (for handling HubSpot webhook callbacks).
- DTOs: The “dto” package categorizes data transfer objects for contacts, OAuth, and webhooks – encapsulating the payload structures.
- Services: The “service” package is split into subpackages for contact, OAuth, and webhook processing. These services contain the business logic and integrate with HubSpot’s external endpoints via RestTemplate.
- Exceptions: Centralized error handling via GlobalExceptionHandler along with OAuthException.
- The structure supports a clean separation between controllers, services, configuration, and error handling.

##### Architectural Insights from the README
- The README specifies that the API handles OAuth authentication, contact management, and webhook processing.
- It lists out technical decisions like layered architecture (controllers → services → external HubSpot API via RestTemplate), use of DTOs, centralized exception handling, and integration with Swagger (OpenAPI documentation).
- It also mentions external dependencies (HubSpot endpoints, external OAuth flows) and core Spring Boot features (security, validation, REST, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Entry
    A["IntegrationApplication (Spring Boot Entry)"]:::entry

    %% Configurations
    subgraph "Configurations"
        RT["RestTemplateConfig"]:::config
        SC["SecurityConfig"]:::config
    end

    %% Controllers
    subgraph "Controllers"
        OauthC["OAuthController"]:::controller
        ContactC["ContactController"]:::controller
        WebhookC["HubSpotWebhookController"]:::controller
    end

    %% Services
    subgraph "Services"
        OauthS["HubspotOAuthService"]:::service
        ContactS["HubSpotContactService"]:::service
        WebhookS["HubSpotWebhookService"]:::service
        SigS["SignatureService"]:::service
    end

    %% Data Transfer Objects (DTOs)
    subgraph "DTOs"
        DT1["Contacts DTOs"]:::dto
        DT2["OAuth DTOs"]:::dto
        DT3["Webhook DTOs"]:::dto
    end

    %% Exception Handling
    subgraph "Exception Handling"
        GlobalE["GlobalExceptionHandler"]:::exception
        OAuthE["OAuthException"]:::exception
    end

    %% External Systems
    subgraph "External Systems"
        Client["Client (Browser/Postman)"]:::external
        HubSpot["HubSpot API"]:::external
        Swagger["Swagger UI"]:::external
    end

    %% Relationships - Client interactions
    Client -->|"OAuthRequest"| OauthC
    Client -->|"ContactRequest"| ContactC
    HubSpot -->|"WebhookCallback"| WebhookC

    %% Application entry point directs to controllers and documentation
    A --> OauthC
    A --> ContactC
    A --> WebhookC
    A --> Swagger

    %% Controllers invoke service methods
    OauthC -->|"HandleOAuth"| OauthS
    ContactC -->|"ProcessContact"| ContactS
    WebhookC -->|"ValidateSignature"| SigS
    SigS -->|"ProcessWebhook"| WebhookS

    %% Services call external HubSpot endpoints
    OauthS -->|"TokenExchange"| HubSpot
    ContactS -->|"CreateContact"| HubSpot
    WebhookS -->|"AcknowledgeWebhook"| HubSpot

    %% Configuration usage by controllers and services
    OauthS -.-> RT
    ContactS -.-> RT
    WebhookS -.-> RT
    OauthC -.-> SC
    ContactC -.-> SC
    WebhookC -.-> SC

    %% Exception handling connections
    OauthC -->|"Error"| GlobalE
    ContactC -->|"Error"| GlobalE
    WebhookC -->|"Error"| GlobalE

    %% Styles
    classDef entry fill:#ffcccc,stroke:#660000,stroke-width:2px;
    classDef config fill:#ccffcc,stroke:#339933,stroke-width:2px;
    classDef controller fill:#cce5ff,stroke:#003399,stroke-width:2px;
    classDef service fill:#e6ccff,stroke:#663399,stroke-width:2px;
    classDef dto fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef exception fill:#ffd699,stroke:#ff6600,stroke-width:2px;
    classDef external fill:#f2f2f2,stroke:#666666,stroke-width:2px,stroke-dasharray: 5 5;

    %% Click Events
    click A "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/IntegrationApplication.java"
    click RT "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/config/RestTemplateConfig.java"
    click SC "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/config/SecurityConfig.java"
    click OauthC "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/controller/api/OAuthController.java"
    click ContactC "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/controller/api/ContactController.java"
    click WebhookC "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/controller/webhook/HubSpotWebhookController.java"
    click DT1 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/contact/ContactRequestDTO.java"
    click DT1 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/contact/ContactResponseDTO.java"
    click DT2 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/oauth/HubspotTokenResponse.java"
    click DT2 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/oauth/OAuthState.java"
    click DT3 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/webhook/HubSpotWebhookEvent.java"
    click DT3 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/webhook/HubSpotWebhookPayload.java"
    click DT3 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/webhook/HubSpotWebhookRequest.java"
    click DT3 "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/dto/webhook/WebhookResponse.java"
    click OauthS "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/service/oauth/HubspotOAuthService.java"
    click ContactS "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/service/contact/HubSpotContactService.java"
    click WebhookS "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/service/webhook/HubSpotWebhookService.java"
    click SigS "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/service/webhook/SignatureService.java"
    click GlobalE "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/exception/GlobalExceptionHandler.java"
    click OAuthE "https://github.com/alexsantosfilho/hubspot_integration/blob/main/src/main/java/com/hubspot/integration/exception/OAuthException.java"
```
