# sucaslilva/integracaohubspot architecture

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

- Interactive diagram: https://gitdiagram.com/sucaslilva/integracaohubspot
- Repository: https://github.com/sucaslilva/integracaohubspot

## Overview

##### Project Type and Purpose
- This is a **backend-only REST API** built with **Spring Boot** (Java/Maven).
- Its sole purpose is to integrate with HubSpot CRM: perform OAuth2 authentication, create/list contacts, and receive HubSpot webhooks.

##### File Structure
- Top-level folders:
- hubSpot/ (Maven project root)
- src/main/java/br/com/sucaslilva/hubSpot/{controller, service, model}
- src/main/resources/application.properties
- src/test/java/… (unit tests)
- Pattern: a classic 3-layered architecture (Controller → Service → External API), no internal database or persistence layer.
- Configuration: application.properties holds environment-injected OAuth client ID/secret, redirect URIs, etc.

##### Core Components
a. Clients (Postman, Web or Mobile Front-end)
b. Spring Boot REST API (hubSpot application)
- Controllers:
- AutenticacaoController (OAuth2 handshake)
- ContatoController (create/list contacts)
- WebhookController (receive HubSpot webhook callbacks)
- Services:
- TokenService (manage OAuth tokens)
- ContatoService (map API calls to HubSpot contacts endpoints)
- WebhookService (process incoming webhook events)
- Configuration Module (application.properties + environment variables)
c. External Service: HubSpot CRM REST API
d. Optional: Developer Tools (Postman collection for testing)

##### Relationships and Data Flows
- **OAuth2 Flow**
1. Client calls AutenticacaoController → forwards user to HubSpot’s auth endpoint
2. HubSpot redirects back with auth code → AutenticacaoController exchanges code via TokenService → stores access/refresh tokens in memory (or cache).
- **Contact Management**
1. Client calls ContatoController (create/list) → ContatoService adds Authorization header with access token → calls HubSpot Contacts API → returns contact data back to client.
- **Webhook Handling**
1. HubSpot sends HTTP POST to WebhookController endpoint → WebhookService validates signature and processes the JSON payload → triggers any business logic (e.g., logging or notifying another system).

##### Architectural Patterns and Principles
- **Layered (MVC-inspired)**: Controllers orchestrate request/response; Services handle business logic/integration.
- **External Integration**: All persistent data lives in HubSpot; this API acts as a stateless proxy/adapter.
- **Configuration-Driven**: OAuth credentials and endpoints are injected via application.properties and environment variables.
- **Statelessness**: Each HTTP request is self-contained with its own authentication token.

##### Technologies and Frameworks to Annotate
- Java 17, Spring Boot (Web, Security/OAuth2)
- Maven (pom.xml)
- HubSpot REST API (OAuth2, Contacts endpoints, Webhooks)
- Postman (testing/collection)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Client Layer"
        Client["Client (Postman / Front-end)"]:::client
    end

    %% Entry Point
    subgraph "Application"
        App["HubSpotApplication"]:::config
    end

    %% Controllers Layer
    subgraph "Controllers" 
        AuthCtrl["AutenticacaoController"]:::controller
        ContactCtrl["ContatoController"]:::controller
        WebhookCtrl["WebhookController"]:::controller
    end

    %% Services Layer
    subgraph "Services"
        TokenSvc["TokenService"]:::service
        ContactSvc["ContatoService"]:::service
        WebhookSvc["WebhookService"]:::service
    end

    %% Models and Config
    subgraph "Configuration / Models"
        ConfigProps["application.properties"]:::config
        WebhookModel["WebhookDTO"]:::model
        Pom["pom.xml"]:::config
    end

    %% External Service
    subgraph "External"
        HubSpotAPI["HubSpot CRM REST API"]:::external
    end

    %% Flows
    Client -->|"Starts App"| App
    Client -->|"GET /oauth/... POST /contacts/..."| AuthCtrl
    Client -->|"GET /oauth/... POST /contacts/..."| ContactCtrl

    AuthCtrl -->|"exchange code"| TokenSvc
    ContactCtrl -->|"use token header"| ContactSvc

    TokenSvc -->|"GET /oauth/v1/token"| HubSpotAPI
    ContactSvc -->|"POST/GET /contacts/v1/contact"| HubSpotAPI

    HubSpotAPI -->|"webhook POST"| WebhookCtrl
    WebhookCtrl -->|"validate & process"| WebhookSvc
    WebhookSvc -->|"map payload"| WebhookModel

    %% Configuration injection
    ConfigProps --> TokenSvc
    ConfigProps --> ContactSvc
    ConfigProps --> WebhookSvc
    Pom --> App

    %% Click Events
    click Client "https://github.com/sucaslilva/integracaohubspot/blob/main/Integracao-HubSpot.postman_collection.json"
    click App "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/HubSpotApplication.java"
    click AuthCtrl "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/controller/AutenticacaoController.java"
    click ContactCtrl "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/controller/ContatoController.java"
    click WebhookCtrl "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/controller/WebhookController.java"
    click TokenSvc "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/service/TokenService.java"
    click ContactSvc "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/service/ContatoService.java"
    click WebhookSvc "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/service/WebhookService.java"
    click ConfigProps "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/resources/application.properties"
    click Pom "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/pom.xml"
    click WebhookModel "https://github.com/sucaslilva/integracaohubspot/blob/main/hubSpot/src/main/java/br/com/sucaslilva/hubSpot/model/WebhookDTO.java"

    %% Styles
    classDef controller fill:#a2c4fc,stroke:#0366d6,color:#000;
    classDef service fill:#c6efce,stroke:#28a745,color:#000;
    classDef config fill:#d9d9d9,stroke:#6c757d,color:#000;
    classDef external fill:#f8d7da,stroke:#dc3545,color:#000;
    classDef client fill:#fff3cd,stroke:#ffc107,color:#000;
    classDef model fill:#e2e3e5,stroke:#6c757d,color:#000;
```
