# ARCA Validation App — System Documentation

Prepared by UO Solutions

## 1. Purpose of this document

This document explains, in both plain and technical terms, how the ARCA Validation application works inside HubSpot.

## 2. What this application does

In simple terms: a staff member working inside HubSpot enters a person's CUIT/CUIL. The application checks that number against ARCA (the national tax registry) and against HubSpot's own contact database, then helps the staff member either confirm the existing contact record or create a new one — all without leaving HubSpot.

The entire experience lives inside a single screen embedded in the HubSpot CRM. Nothing is installed on anyone's computer, and no separate website or login is involved.

## 3. How the system is built

The application is a **HubSpot private app**. "Private" means it was built for, and only exists inside, this one HubSpot account — it is not published or shared with anyone outside the organization.

It has three moving parts, all of which live inside HubSpot's own infrastructure:

1. **The Page (what the user sees).** A screen embedded directly in the HubSpot CRM interface. It is only reachable by opening HubSpot and navigating to it — there is no separate public web address for it.
2. **Serverless Functions (the logic).** Small pieces of backend code that run the actual work: validating a CUIT, searching for a contact, creating a contact, updating a contact. These are marked as **private functions**, which is a specific technical setting meaning they can only be triggered from inside this same HubSpot app session — they do not have a public internet address at all.
3. **The HubSpot CRM API.** The official interface HubSpot provides for reading and writing contact records. This is how the app actually creates or updates a contact — by asking HubSpot to do it, using credentials scoped to this one account.

Everything described above — the screen, the logic, and the database of contacts — belongs to and runs inside HubSpot. The only step that reaches outside of HubSpot is the CUIT check against ARCA, described in Section 5.

## 4. Architecture at a glance

```mermaid
flowchart TB
    subgraph HS["Inside the HubSpot account"]
        User["Staff member,\nlogged into HubSpot"]
        Page["App Page\n(the screen inside the CRM)"]
        Funcs["Private Serverless Functions\n(validate CUIT / search / create / update)"]
        CRM["HubSpot CRM API\n(contact records)"]

        User -->|"opens the page inside HubSpot"| Page
        Page -->|"calls, using the internal\nHubSpot app session"| Funcs
        Funcs -->|"reads and writes contacts"| CRM
    end

    ARCA["ARCA validation service\n(external, ARCA)"]
    Funcs -->|"one outbound check:\nis this CUIT valid?"| ARCA

    style HS fill:#eef4ff,stroke:#5577cc,stroke-width:1px
```

Everything inside the shaded box happens on HubSpot's own infrastructure. The single arrow leaving the box is the CUIT validation check, described below.

## 5. How the data travels

This is the core of what makes the design safe: contact data is created, read, and updated entirely through HubSpot's own systems. It is not copied to, or processed by, any server that UO Solutions or anyone else operates.

Step by step, for a typical use:

1. A staff member, already logged into HubSpot, opens the app page from inside the CRM.
2. They type in a CUIT/CUIL. The page asks a private function to check it.
3. That function makes one outbound request to the ARCA validation service to confirm the identity data associated with that CUIT (name, registered contact details). This is the one point where a request leaves HubSpot's environment, and it only sends the CUIT number being looked up.
4. In parallel, another private function asks the **HubSpot CRM API** — not an external database — whether a contact with that CUIT already exists in this account.
5. Depending on the result, the staff member reviews or fills in contact details on screen, then submits.
6. Submitting calls a private function that writes the contact (create or update) directly through the **HubSpot CRM API**.

```mermaid
sequenceDiagram
    participant U as Staff member (in HubSpot)
    participant P as App Page
    participant F as Private Functions
    participant H as HubSpot CRM API
    participant A as ARCA (external)

    U->>P: Enter CUIT and submit
    P->>F: Validate CUIT
    F->>A: Check CUIT (outbound, CUIT only)
    A-->>F: Identity data
    F->>H: Search for existing contact
    H-->>F: Contact found / not found
    F-->>P: Show result to staff member
    U->>P: Confirm and submit contact details
    P->>F: Create or update contact
    F->>H: Write contact record
    H-->>F: Confirmation
    F-->>P: Success
```

Aside from the single CUIT check against ARCA, every arrow in this diagram stays inside HubSpot's own network. The contact record itself — names, emails, phone numbers — is only ever written to and read from HubSpot's own CRM database.

## 6. Hubspot App - Details

- **No infrastructure to secure or maintain.** There is no separate server with its own operating system, dependencies, to mantain.
- **No independent copy of the data.** There is no second database holding a copy of contact information. The data has one home: HubSpot.
- **Smaller attack surface.** The private serverless functions have no public internet address at all — they can only be called from inside an authenticated HubSpot session for this account. There is nothing on the open internet for an outside attacker to find and target.
- **Access control is inherited from HubSpot.** Because the app has no separate login system of its own, it only relays on Hubspot´s authentication.

## 7. Goverment and access to the data

 The only people who can open this app, and the only people who can see or change the data it works with, are people who are already logged into this specific HubSpot account and have been granted permission there.

- The app page only exists inside the HubSpot CRM interface. There is no separate website address a person could visit from outside HubSpot to reach it. If someone is not logged into HubSpot, the page simply does not exist for them.
- The functions that actually do the work — validating a CUIT, searching contacts, creating or updating a contact — are configured as **private functions**. This means HubSpot does not expose them as reachable internet addresses at all. They can only be invoked from inside an active, authenticated session of this app, by this account.
- Every write to a contact record (create or update) is performed using credentials tied to this HubSpot account's private app installation, which HubSpot itself issues and manages.
- HubSpot's own account permission system (the same one used across the rest of the CRM) decides who is allowed to view or edit contact records. This app does not bypass or duplicate that system — it uses it.