# sandriiy/salesforce-google-drive-library architecture

> Architecture diagram of the GitHub repository sandriiy/salesforce-google-drive-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sandriiy/salesforce-google-drive-library
- Repository: https://github.com/sandriiy/salesforce-google-drive-library

## Overview

##### Project type and purpose
- This is a Salesforce‐hosted Apex library (unlocked package) that wraps Google Drive REST API v3.
- Its sole purpose is to provide a strongly-typed, builder‐pattern driven interface within Apex to perform Drive operations (upload, download, clone, search, permission management), plus supporting unit tests via HTTP callout mocks.

##### File structure
- Top-level:
- config/ – Scratch org definition
- google-drive/ – the entire Apex package
- jest.config.js, package.json – local JavaScript testing config (for HTTP mock generation tools)
- sfdx-project.json – Salesforce DX project descriptor
- google-drive/classes:
- auth/GoogleAuthorizationCodeFlow, GoogleCredential – OAuth2 flow, credential storage
- builders/*Builder.cls – Builder pattern classes to construct each REST call
- factories/*Factory.cls – Factory classes to instantiate high-level operations
- entities/*Entity.cls – Domain wrappers for Drive responses (files, drives, permissions)
- interfaces/ – Abstraction of authorizer and file creator for DI and testability
- GoogleDrive.cls – Facade entry point exposing .files(), .drives(), .permissions().
- GoogleDriveHttpMockGenerator.cls – Generates HTTP mocks for unit tests
- GoogleDriveTest.cls – Apex test suite
- Configuration and metadata files (.cls-meta.xml, sfdx, .forceignore, .husky, .prettierrc, etc.)

##### README for additional insights
- The README confirms:
- Programmatic Apex access to Drive
- Usage examples invoking GoogleDrive.files().upload().execute() style
- Highlights v3 API, custom wrappers (GoogleFileEntity, SearchResult), mock‐based testing
- Deployment via direct metadata or unlocked package

a. Main components
- Salesforce Org
- Apex Runtime
- HTTP Callout Framework
- Named Credential (or Remote Site Settings)
- Apex Library (google-drive package)
- GoogleDrive Facade
- Builder Layer
- Factory Layer
- Entity Layer
- Interface abstractions
- HTTP Mock Generator (test harness)
- External Systems
- Google OAuth 2.0 Authorization Server
- Google Drive REST API v3

b. Relationships & data flows
1. Developer code / client code calls the GoogleDrive facade in Apex.
2. GoogleDrive delegates to Factory to instantiate a specific operation (e.g., FilesBuilder).
3. Builder assembles URL, query params, headers (including OAuth token from Credential).
4. Apex HTTP Callout is issued to Google API endpoint.
5. Google Authorization Server issues/refreshes access tokens.
6. Google Drive API returns JSON payload.
7. Response is parsed into Entity objects.
8. For tests, HTTP Callouts are intercepted by GoogleDriveHttpMockGenerator.

c. Architectural patterns & design principles
- Facade Pattern: GoogleDrive entry point hides internal complexity.
- Builder Pattern: Each request type has its own Builder class to incrementally set parameters.
- Factory Pattern: Factories instantiate Builders preconfigured for specific use cases.
- Dependency Inversion: Interfaces (GoogleAuthorizer, GoogleFileCreator) allow swapping implementations or mocks.
- Layered Architecture: Separation between request construction, authorization, HTTP transport, response mapping, and testing.
- Testability: HTTP Mock Generator and Apex Test classes ensure high coverage without real API calls.

d. Key technologies & frameworks
- Salesforce Apex language & runtime
- Salesforce DX (sfdx-project.json)
- HTTP Callout framework in Apex
- Google OAuth 2.0 / Named Credentials
- Google Drive REST API v3
- Jest (for local mock generation tooling)
- Unlocked Package deployment model

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Environment
    subgraph "Salesforce Org" 
        direction TB
        ApexRuntime["Apex Runtime"]:::apex
        HTTPCalloutFW["HTTP Callout Framework"]:::apex
        NamedCred["Named Credential / Remote Site"]:::apex
    end

    %% Apex Library Core
    subgraph "Apex Library (google-drive)" 
        direction TB
        GoogleDriveFacade["GoogleDrive Facade"]:::apex
        subgraph "Factory Layer"
            direction TB
            GoogleRetrieveFactory["GoogleRetrieveFileFactory"]:::apex
            GooglePermissionFactory["GooglePermissionFileFactory"]:::apex
        end
        subgraph "Builder Layer"
            direction TB
            GoogleRequestBuilder["GoogleRequestBuilder"]:::apex
            GoogleDownloadBuilder["GoogleDownloadFileBuilder"]:::apex
            GoogleMultipartBuilder["GoogleMultipartFileBuilder"]:::apex
            GoogleSearchBuilder["GoogleDriveSearchBuilder"]:::apex
            GoogleOtherBuilders["Other *Builder.cls"]:::apex
        end
        subgraph "Entity Layer"
            direction TB
            FileEntity["GoogleFileEntity"]:::apex
            DriveEntity["GoogleDriveEntity"]:::apex
            PermEntity["GooglePermissionEntity"]:::apex
            FileSearchResult["GoogleFileSearchResult"]:::apex
            DriveSearchResult["GoogleDriveSearchResult"]:::apex
            PermSearchResult["GooglePermissionSearchResult"]:::apex
            BigFileEntity["GoogleBigFileEntity"]:::apex
        end
        subgraph "Interface Abstractions"
            direction TB
            AuthorizerIF["GoogleAuthorizer"]:::apex
            FileCreatorIF["GoogleFileCreator"]:::apex
        end
        subgraph "OAuth2 Flow Components"
            direction TB
            AuthCodeFlow["GoogleAuthorizationCodeFlow"]:::apex
            Credential["GoogleCredential"]:::apex
        end
        Constants["GoogleConstants.cls"]:::apex
    end

    %% Test Harness
    subgraph "Test Harness" 
        direction TB
        HTTPMockGen["GoogleDriveHttpMockGenerator"]:::test
        TestSuite["GoogleDriveTest"]:::test
    end

    %% External Systems
    subgraph "External Services"
        direction TB
        OAuthServer["Google OAuth2 Authorization Server"]:::external
        DriveAPI["Google Drive REST API v3"]:::external
    end

    %% Data Flows
    Client["Client Code / Dev Calls"]:::apex
    Client -->|"calls .files(), .drives(), .permissions()"| GoogleDriveFacade
    GoogleDriveFacade -->|"use Factory"| GoogleRetrieveFactory
    GoogleDriveFacade --> GooglePermissionFactory
    GoogleRetrieveFactory -->|"instantiate Builder"| GoogleRequestBuilder
    GooglePermissionFactory --> GoogleSearchBuilder
    GoogleRequestBuilder -->|"build & send HTTP Request"| HTTPCalloutFW
    GoogleDownloadBuilder --> HTTPCalloutFW
    GoogleMultipartBuilder --> HTTPCalloutFW
    GoogleSearchBuilder --> HTTPCalloutFW
    HTTPCalloutFW -->|"token exchange"| OAuthServer
    HTTPCalloutFW -->|"HTTP Request"| DriveAPI
    DriveAPI -->|"JSON Payload"| HTTPCalloutFW
    HTTPCalloutFW -->|"parse to Entities"| FileEntity
    HTTPCalloutFW --> DriveEntity
    HTTPCalloutFW --> PermEntity
    FileEntity --> Client
    %% Test intercept
    HTTPCalloutFW -.->|"intercept callouts"| HTTPMockGen
    HTTPMockGen -->|"mock JSON Payload"| HTTPCalloutFW
    HTTPMockGen --> TestSuite

    %% Click Events
    click GoogleDriveFacade "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/GoogleDrive.cls"
    click GoogleRequestBuilder "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/builders/GoogleRequestBuilder.cls"
    click GoogleDownloadBuilder "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/builders/GoogleDownloadFileBuilder.cls"
    click GoogleMultipartBuilder "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/builders/GoogleMultipartFileBuilder.cls"
    click GoogleSearchBuilder "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/builders/GoogleDriveSearchBuilder.cls"
    click GoogleOtherBuilders "https://github.com/sandriiy/salesforce-google-drive-library/tree/production/google-drive/classes/builders/"
    click GoogleRetrieveFactory "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/factories/GoogleRetrieveFileFactory.cls"
    click GooglePermissionFactory "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/factories/GooglePermissionFileFactory.cls"
    click FileEntity "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/entities/GoogleFileEntity.cls"
    click DriveEntity "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/entities/GoogleDriveEntity.cls"
    click PermEntity "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/entities/GooglePermissionEntity.cls"
    click FileSearchResult "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/entities/GoogleFileSearchResult.cls"
    click DriveSearchResult "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/entities/GoogleDriveSearchResult.cls"
    click PermSearchResult "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/entities/GooglePermissionSearchResult.cls"
    click BigFileEntity "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/entities/GoogleBigFileEntity.cls"
    click AuthorizerIF "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/interfaces/GoogleAuthorizer.cls"
    click FileCreatorIF "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/interfaces/GoogleFileCreator.cls"
    click AuthCodeFlow "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/auth/GoogleAuthorizationCodeFlow.cls"
    click Credential "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/auth/GoogleCredential.cls"
    click HTTPMockGen "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/GoogleDriveHttpMockGenerator.cls"
    click TestSuite "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/classes/GoogleDriveTest.cls"
    click Constants "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/google-drive/GoogleConstants.cls"
    click sfdx "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/sfdx-project.json"
    click ScratchOrg "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/config/project-scratch-def.json"
    click JestConfig "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/jest.config.js"
    click PackageJSON "https://github.com/sandriiy/salesforce-google-drive-library/blob/production/package.json"

    %% Styles
    classDef apex fill:#cce5ff,stroke:#004085,color:#004085
    classDef external fill:#d4edda,stroke:#155724,color:#155724
    classDef test fill:#fff3cd,stroke:#856404,color:#856404
    classDef config fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
