Skip to content
This repository was archived by the owner on Oct 21, 2025. It is now read-only.
BranchesTags

Repository files navigation

Video Demo

Watch the Demo

VectorShift Integration Assignment

A middleware solution that facilitates OAuth2 authentication with third-party services and retrieves data from them. Users can connect their accounts to services like Airtable, Notion, and HubSpot through the web interface, and then load data from these services for further use.

Features

  • Secure OAuth2 Implementation: Complete OAuth2 flows with PKCE for enhanced security (Airtable) and standard OAuth2 (Notion, HubSpot)
  • Multiple Service Integrations: Pre-built integrations with Airtable, Notion, and HubSpot
  • Temporary Credential Storage: Secure storage of OAuth credentials with automatic cleanup using Redis
  • Standardized Data Model: Consistent IntegrationItem data model across all services
  • Modular Architecture: Clean separation of concerns with clear backend and frontend structure
  • Responsive UI: Modern React-based interface with Material-UI components
  • Comprehensive Error Handling: Robust error handling throughout the application

Folder Structure

Backend

backend/
├── main.py                  # FastAPI application entry point
├── redis_client.py          # Redis client for temporary storage
├── requirements.txt         # Python dependencies
└── integrations/            # Third-party service integrations
    ├── airtable.py          # Airtable integration implementation
    ├── notion.py            # Notion integration implementation
    ├── hubspot.py           # HubSpot integration implementation
    └── integration_item.py  # Standardized data model

Frontend

frontend/
├── src/
│   ├── App.js               # Main application component
│   ├── index.js             # Entry point for the React app
│   ├── index.css            # Global CSS styles
│   ├── integration-form.js  # Main form for selecting integrations
│   ├── data-form.js         # Component for loading/displaying data
│   └── integrations/        # Integration-specific components
│       ├── airtable.js      # Airtable connection UI/logic
│       ├── notion.js        # Notion connection UI/logic
│       ├── hubspot.js       # HubSpot connection UI/logic
│       └── slack.js         # Slack integration (placeholder)
├── package.json             # npm dependencies and scripts
└── public/                  # Static assets

Note: A slack.js placeholder file exists in the integrations/ folder, but Slack integration is not part of the current assessment scope. Only Airtable, Notion, and HubSpot are implemented/required.

Setup

Prerequisites

  1. Python 3.8+ for backend
  2. Node.js 14+ for frontend
  3. Redis server for temporary storage of OAuth states and credentials
  4. Third-party API credentials for Airtable, Notion, and HubSpot integrations

Backend Setup

1. Installing Python Dependencies

Navigate to the backend directory and install the required Python packages:

cd backend
pip install -r requirements.txt

Key dependencies include:

  • FastAPI and Uvicorn for the web framework
  • Redis for temporary storage
  • Httpx for asynchronous HTTP requests
  • Cryptography for security
  • Pydantic for data validation

2. Redis Setup

  1. Install Redis server on your system:

    • Windows: Download from Redis for Windows
    • macOS: brew install redis
    • Linux: sudo apt-get install redis-server

  2. Start Redis server:

    redis-server

  3. The backend connects to Redis at localhost:6379 by default. You can customize this with the REDIS_HOST environment variable.

3. Environment Variables

The backend requires the following environment variables:

  • REDIS_HOST (optional): Redis server host (default: localhost)

For third-party integrations, you'll need to update the hardcoded values in:

4. Running the FastAPI Server

From the backend directory, run:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

The backend will be available at http://localhost:8000

Frontend Setup

1. Installing npm Dependencies

Navigate to the frontend directory and install dependencies:

cd frontend
npm install

Key dependencies include:

  • React and ReactDOM for the UI framework
  • Material UI (@mui/material) for components
  • Axios for HTTP requests

2. Environment Variables

The frontend does not require any environment variables. All API endpoints are hardcoded to connect to http://localhost:8000.

3. Running the React Development Server

From the frontend directory, run:

npm start

The frontend will be available at http://localhost:3000

Third-Party API Credentials

Airtable

  1. Go to Airtable Developers
  2. Create a new application
  3. Get the Client ID and Client Secret
  4. Update backend/integrations/airtable.py with your credentials
  5. Set the redirect URI to http://localhost:8000/integrations/airtable/oauth2callback

Notion

  1. Go to Notion Integrations
  2. Create a new integration
  3. Get the Client ID and Client Secret
  4. Update backend/integrations/notion.py with your credentials
  5. Set the redirect URI to http://localhost:8000/integrations/notion/oauth2callback

HubSpot

  1. Go to HubSpot Developer Portal
  2. Create a new app
  3. Get the Client ID and Client Secret
  4. Update backend/integrations/hubspot.py with your credentials
  5. Set the redirect URI to http://localhost:8000/integrations/hubspot/oauth2callback

Architecture & Code Organization

Backend Architecture

The backend is built with FastAPI, a modern, fast (high-performance) web framework for building APIs with Python 3.7+ based on standard Python type hints.

Main Application (backend/main.py)

  • Entry point for the FastAPI application
  • Configures CORS middleware to allow communication with the frontend
  • Defines all API endpoints for the integrations

Redis Client (backend/redis_client.py)

  • Provides a simple interface for storing and retrieving temporary data
  • Used for storing OAuth states and credentials during the authentication flow
  • Credentials are automatically expired after 10 minutes for security

Integration Modules (backend/integrations/)

Each integration (Airtable, Notion, HubSpot) has its own module with:

  • OAuth flow implementation
  • Data fetching functions
  • Credential handling

Frontend Architecture

The frontend is built with React, a JavaScript library for building user interfaces, and Material-UI for components.

Main Application (frontend/src/App.js)

  • Entry point for the React application
  • Renders the main IntegrationForm component

Integration Form (frontend/src/integration-form.js)

  • Main form for selecting and connecting to integrations
  • Dynamically loads the appropriate integration component based on user selection
  • Handles user input for user ID and organization ID

Data Form (frontend/src/data-form.js)

  • Component for loading and displaying data from connected integrations
  • Sends credentials to the backend and displays the returned data

Integration Components (frontend/src/integrations/)

Each integration (Airtable, Notion, HubSpot) has its own component with:

  • UI for connecting to the service
  • Logic for handling the OAuth flow
  • State management for connection status

Integrations

Airtable Integration

The Airtable integration implements OAuth 2.0 with PKCE (Proof Key for Code Exchange) for enhanced security:

  1. Authorization Request: Generates a random state parameter and code verifier/challenge for PKCE
  2. Callback Handling: Validates state and exchanges authorization code for access tokens
  3. Data Fetching: Retrieves bases and tables from Airtable API
  4. Credential Handling: Stores credentials in Redis with 10-minute expiration

Notion Integration

The Notion integration implements standard OAuth 2.0:

  1. Authorization Request: Generates a state parameter for CSRF protection
  2. Callback Handling: Validates state and exchanges authorization code for access tokens
  3. Data Fetching: Uses Notion's search API to fetch pages/databases
  4. Credential Handling: Stores credentials in Redis with 10-minute expiration

HubSpot Integration

The HubSpot integration implements standard OAuth 2.0:

  1. Authorization Request: Generates a state parameter for CSRF protection
  2. Callback Handling: Validates state and exchanges authorization code for access tokens
  3. Data Fetching: Retrieves contacts, companies, and deals from HubSpot API
  4. Credential Handling: Stores credentials in Redis with 10-minute expiration

Slack (Placeholder):

A placeholder file (slack.js) exists in the frontend integrations folder. This was included in the repository template but was not part of the technical assessment requirements.

Usage

Testing the Integration

  1. Start Redis server
  2. Start the backend server
  3. Start the frontend development server
  4. Open http://localhost:3000 in your browser
  5. Connect to Airtable, Notion, or HubSpot using the UI

Connection Flow

  1. User selects integration and clicks "Connect"
  2. Frontend requests authorization URL from backend
  3. Backend generates URL and stores state in Redis
  4. Frontend opens popup with authorization URL
  5. User authenticates with third-party service
  6. Service redirects to backend callback
  7. Backend validates, exchanges code for tokens
  8. Backend stores credentials in Redis
  9. Frontend retrieves credentials after popup closure

Data Loading

  1. User clicks "Load Data" in DataForm
  2. Frontend sends credentials to backend
  3. Backend fetches data from third-party service
  4. Backend returns standardized IntegrationItem objects
  5. Frontend displays data

HubSpot Integration Testing

To test the HubSpot integration:

  1. Ensure you have HubSpot API credentials (Client ID and Client Secret)
  2. Update the credentials in backend/integrations/hubspot.py
  3. Start all required services (Redis, backend, frontend)
  4. Open the application in your browser
  5. Select "HubSpot" from the integration type dropdown
  6. Enter your User ID and Organization ID
  7. Click "Connect to HubSpot"
  8. Authenticate with your HubSpot account in the popup window
  9. After successful authentication, the button will change to "HubSpot Connected"
  10. Click "Load Data" to retrieve contacts, companies, and deals from HubSpot
  11. The retrieved data will be displayed in the text field

For debugging purposes, the IntegrationItem objects retrieved from HubSpot are printed to the console in the backend. You can view these by checking the backend server logs.

Contributing

We welcome contributions to the VectorShift Integration Platform! Here's how you can help:

Development Setup

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

Code Structure Guidelines

  • Follow the existing patterns for new integrations
  • Maintain consistent error handling
  • Use the standardized IntegrationItem data model
  • Keep frontend components modular and reusable

Adding New Integrations

  1. Create backend integration file in backend/integrations/
  2. Implement OAuth flow functions
  3. Create data fetching functions
  4. Add routes to backend/main.py
  5. Create frontend component in frontend/src/integrations/
  6. Add integration to mapping in frontend/src/integration-form.js
  7. Add endpoint mapping in frontend/src/data-form.js

Enhancement Suggestions

  1. Error Handling Improvements:

    • Add specific exception handling for network errors
    • Implement more descriptive error messages
    • Add logging for debugging OAuth flow issues

  2. Token Refresh Mechanisms:

    • Implement automatic token refresh before API calls
    • Store refresh tokens securely in Redis
    • Add proper error handling for refresh token failures

  3. UI Enhancements:

    • Create dedicated data visualization components
    • Implement tabbed interface for different object types
    • Add search and filtering capabilities

  4. New Integration Possibilities:

    • Salesforce, Pipedrive, Zoho CRM
    • Slack, Microsoft Teams, Zoom
    • Mailchimp, Marketo, HubSpot Marketing
    • Asana, Trello, Monday.com
    • Shopify, WooCommerce, Magento
    • Google Analytics, Tableau, Power BI

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages