hubspot-architecture-variants

# HubSpot Architecture Variants ## Overview Three validated architecture patterns for HubSpot CRM integrations at different scales, from embedded client to dedicated API gateway. ## Prerequisites - Understanding of team size and daily API call volume - Knowledge of deployment infrastructure - Clear sync requirements (real-time vs batch) ## Instructions ### Variant A: Embedded Client (Simple) **Best for:** MVPs, small teams, < 10K contacts, < 50K API calls/day ``` your-app/ ├── src/ │ ├── hubspot/ │ │ ├── client.ts # @hubspot/api-client singleton │ │ └── contacts.ts # Direct CRM operations │ ├── routes/ │ │ └── api.ts # API routes that call HubSpot directly │ └── index.ts ``` ```typescript // Direct integration in route handlers import * as hubspot from '@hubspot/api-client'; const client = new hubspot.Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN!, numberOfApiCallRetries: 3, }); app.get('/api/contacts', async (req, res) => { const page = await client.crm.contacts.basicApi.getPage( 20, req.query.after as string, ['email', 'firstname', 'lastname'] ); res.json(page); }); app.post('/api/contacts', async (req, res) => { const contact = await client.crm.contacts.basicApi.create({ properties: req.body, associations: [], }); res.status(201).json(contact); }); ``` **Pros:** Fast to build, simple to understand, one deployment **Cons:** No fault isolation, HubSpot latency in user request path --- #...