Unclassified

IntegrateWise Technical Documentation

Platform Architecture & Developer Reference

Version: 1.0
Last Updated: January 2026
Status: Internal + Developer Reference

Table of Contents

  1. System Overview
  2. Architecture Layers
  3. Data Model & Schema
  4. Connectors (Loaders)
  5. Routing & Permissions (Hubs)
  6. Automation Engine
  7. AI Integration
  8. Output Generation (Render)
  9. API Reference
  10. Webhooks
  11. Security & Compliance
  12. Infrastructure
  13. Deployment

1. System Overview

1.1 What IntegrateWise Does

IntegrateWise is a unified workspace platform that:

  • Connects to external business tools via APIs
  • Normalizes data into a consistent schema
  • Routes data to appropriate teams/functions
  • Provides AI-powered automation suggestions
  • Generates documents and reports from unified data

1.2 Core Principles

PrincipleImplementation
Normalize OnceAll data transformed to standard schema at ingestion
Render AnywhereSame data outputs to any format (docs, slides, emails)
User ControlAI suggests, user approves — nothing auto-runs without consent
Tool AgnosticWorks with any tool that has an API

1.3 High-Level Architecture

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ PRESENTATION │
│ React Frontend + Mobile (React Native) │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ API GATEWAY │
│ Cloudflare Workers + KV Cache │
└─────────────────────────────────────────────────────────────────────────────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ RENDER │ │ AUTOMATION │ │ BRAIN │
│ ENGINE │ │ ENGINE │ │ (AI MEM) │
│ (Output) │ │ (n8n/CF) │ │ (Vector) │
└─────────────┘ └─────────────┘ └─────────────┘
│ │ │
└──────────────────┼──────────────────┘
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ROUTING LAYER (HUBS) │
│ Permission checks, audit logging, data routing │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DATA LAYER (SPINE) │
│ Supabase PostgreSQL + Zod Schemas │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ CONNECTOR LAYER │
│ OAuth handlers, API clients, sync jobs │
└─────────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│ EXTERNAL TOOLS │
│ Slack, HubSpot, Gmail, Notion, Salesforce, etc. │
└─────────────────────────────────────────────────────────────────────────────────┘
```

2. Architecture Layers

2.1 Layer Summary

LayerNamePurposeTechnology
7PresentationUser interface, dashboardsReact, React Native
6Render EngineOutput generationCloudflare Workers
5AutomationAI suggestions, workflowsn8n Cloud, Workers
4BrainAI memory, conversation storageSupabase pgvector
3ConnectorsExternal tool integrationNode.js, OAuth 2.0
2HubsRouting, permissions, auditPostgreSQL + RLS
1SpineCore data storageSupabase PostgreSQL
0ExternalThird-party toolsVarious APIs

3. Data Model & Schema

3.1 Core Entities (12 Zod Contracts)

All data is normalized to these core entities:

Account

```typescript
id: z.string().uuid(),
external_id: z.string(),
source: z.enum(['hubspot', 'salesforce', 'manual', 'import']),
name: z.string().min(1).max(255),
domain: z.string().url().optional(),
industry: z.string().optional(),
size: z.enum(['startup', 'smb', 'mid-market', 'enterprise']).optional(),
mrr: z.number().min(0).optional(),
arr: z.number().min(0).optional(),
currency: z.string().length(3).default('USD'),
status: z.enum(['prospect', 'active', 'churned', 'paused']),
health_score: z.number().min(0).max(100).optional(),
tags: z.array(z.string()).default([]),
custom_fields: z.record(z.unknown()).default({}),
created_at: z.string().datetime(),
updated_at: z.string().datetime(),
});
```

Contact

```typescript
id: z.string().uuid(),
external_id: z.string(),
source: z.enum(['hubspot', 'salesforce', 'gmail', 'manual']),
email: z.string().email(),
first_name: z.string().optional(),
last_name: z.string().optional(),
full_name: z.string().optional(),
phone: z.string().optional(),
title: z.string().optional(),
department: z.string().optional(),
role_type: z.enum(['champion', 'decision_maker', 'influencer', 'user', 'unknown']).optional(),
account_id: z.string().uuid().optional(),
owner_id: z.string().uuid().optional(),
engagement_score: z.number().min(0).max(100).optional(),
tags: z.array(z.string()).default([]),
created_at: z.string().datetime(),
updated_at: z.string().datetime(),
});
```

Deal

```typescript
id: z.string().uuid(),
external_id: z.string(),
source: z.enum(['hubspot', 'salesforce', 'manual']),
name: z.string().min(1).max(255),
amount: z.number().min(0),
currency: z.string().length(3).default('USD'),
stage: z.string(),
probability: z.number().min(0).max(100).optional(),
close_date: z.string().datetime().optional(),
account_id: z.string().uuid().optional(),
contact_ids: z.array(z.string().uuid()).default([]),
owner_id: z.string().uuid().optional(),
deal_type: z.enum(['new', 'renewal', 'upsell', 'expansion']).optional(),
created_at: z.string().datetime(),
updated_at: z.string().datetime(),
});
```

All 12 Entities

EntityPurposeKey Fields
AccountCompanies/organizationsname, domain, mrr, health_score
ContactPeople at accountsemail, title, role_type, engagement
DealSales opportunitiesamount, stage, probability
TaskAction itemstitle, status, due_date, assignee
EventMeetings, callsstart_time, end_time, attendees
AlertNotificationsseverity, category, status
NoteComments, logscontent, note_type, visibility
MetricKPIs, measurementsvalue, period, trend
ActivityLogAudit trailaction, entity, actor
HealthScoreAccount healthscore, components, risk_factors
EngagementScoreContact engagementscore, level, activity_counts
UserInternal usersemail, role, team_ids

4. Connectors (Loaders)

4.1 Available Connectors

Production Ready

ConnectorData TypesAuthSync
SlackMessages, channels, usersOAuth 2.0Real-time
HubSpotContacts, companies, dealsOAuth 2.015 min
GmailEmails, threads, labelsOAuth 2.05 min
NotionPages, databasesOAuth 2.015 min
Google SheetsRows, columnsOAuth 2.0On-demand

Coming Soon

ConnectorTarget Release
SalesforceQ1 2026
ZendeskQ1 2026
IntercomQ1 2026
GitHubQ2 2026
JiraQ2 2026
StripeQ1 2026

4.2 Connector Implementation

```typescript
export abstract class BaseConnector {
abstract getName(): string;
abstract getAuthUrl(): string;
abstract handleCallback(code: string): Promise<ConnectionCredentials>;
abstract refreshToken(): Promise<ConnectionCredentials>;
abstract sync(options: SyncOptions): Promise<SyncResult>;
abstract validateConnection(): Promise<boolean>;
}
```

5. Routing & Permissions (Hubs)

5.1 Hub Definitions

HubDescriptionData Types
SalesPipeline, leads, opportunitiesaccounts, contacts, deals
MarketingCampaigns, content, analyticscontacts, campaigns, metrics
Customer SuccessHealth, renewals, engagementaccounts, health_scores, activities
SupportTickets, issues, resolutionstickets, contacts, accounts
FinanceBilling, invoices, revenueaccounts, invoices, payments
ProductFeature requests, bugs, feedbackfeedback, tickets, accounts
HRTeam info, hiring, onboardingusers, teams
TechIncidents, deployments, codeincidents, deploys, repos
LegalContracts, compliance, approvalscontracts, approvals
OperationsProcesses, workflows, efficiencyworkflows, metrics

5.2 Permission Levels

RolePermissionsAccess
Adminread, write, delete, adminEverything
Managerread, write, deleteTeam + cross-team
Memberread, writeOwn team
ViewerreadDashboards only

5.3 Routing Rules

```typescript
// Example routing rules
const rules = [
{
name: 'HubSpot deals to Sales',
condition: { type: 'source', value: 'hubspot' },
data_types: ['deals'],
target_hub: 'sales',
},
{
name: 'Support keywords to Support hub',
condition: { type: 'keyword', value: ['refund', 'cancel', 'issue'] },
data_types: ['emails', 'messages'],
target_hub: 'support',
},
{
name: 'High-value deals to Sales + Leadership',
condition: { type: 'amount_threshold', value: 50000 },
data_types: ['deals'],
target_hub: ['sales', 'leadership'],
},
];
```

6. Automation Engine

6.1 Automation Structure

```typescript
interface Automation {
id: string;
name: string;
trigger: AutomationTrigger;
conditions: AutomationCondition[];
actions: AutomationAction[];
approval_mode: 'suggest_only' | 'auto_run_notify' | 'auto_run_silent';
enabled: boolean;
}
```

6.2 Trigger Types

TriggerDescriptionExample
record_createdNew record addedNew lead from form
record_updatedRecord changedDeal stage moved
field_changedSpecific field changedStatus → Churned
scheduleCron-basedDaily at 9 AM
webhookExternal triggerStripe payment
time_elapsedNo activity for X days7 days no response

6.3 Action Types

ActionDescription
update_fieldChange a field value
create_taskCreate a task
send_notificationSend app/email notification
create_alertCreate an alert
assign_toAssign to user
calculate_scoreRecalculate health/engagement
call_webhookPOST to external URL

6.4 Approval Modes

ModeBehavior
suggest_onlyCreates suggestion, user approves
auto_run_notifyRuns automatically, notifies user
auto_run_silentRuns automatically, no notification

7. AI Integration

7.1 Supported AI Services

ServiceUse CaseModel
OpenAIDefault completionsgpt-4-turbo
AnthropicAlternative completionsclaude-3-opus
BYOMCustom modelsUser-provided

7.2 AI Features

FeatureDescription
CompletionsText generation
EmbeddingsVector search
SummarizationCondense text
ClassificationCategorize content
Entity ExtractionExtract names, dates, etc.

7.3 Brain (Vector Memory)

```typescript
export class BrainService {
async store(conversation: Conversation): Promise<void>;
async search(query: string, options: SearchOptions): Promise<Memory[]>;
async getRelated(memoryId: string, limit: number): Promise<Memory[]>;
}
```

7.4 BYOM (Bring Your Own Model)

```typescript
const customModel = new BYOMService({
endpoint: 'https://my-model.company.com/v1/completions',
apiKey: process.env.CUSTOM_MODEL_API_KEY,
});
aiRouter.setCustomService('custom', customModel);
```

8. Output Generation (Render)

8.1 Supported Formats

FormatExtensionUse Case
Document.docxReports, proposals
Slides.pptxPresentations
PDF.pdfFinal documents
EmailHTML/TextOutreach
CSV.csvData export
JSON.jsonAPI responses

8.2 Template System

```typescript
// Placeholders
{{account.name}}
{{health_score.score}}
{{formatDate(created_at, 'MMMM D, YYYY')}}
{{formatCurrency(amount, 'USD')}}
```

8.3 Built-in Templates

TemplateFormatData Sources
Weekly Status ReportDOCXaccounts, deals, activities
Customer Health ReportDOCXaccount, health_score, tickets
QBR DeckPPTXaccount, metrics, deals
Pipeline ReportPDFdeals, metrics
Check-in EmailEmailaccount, activities

9. API Reference

9.1 Authentication

```http
Authorization: Bearer <api_key>
```

9.2 Base URL

```
Production: https://api.integratewise.com/v1
```

9.3 Endpoints Summary

ResourceListGetCreateUpdateDelete
Accounts✅✅✅✅✅
Contacts✅✅✅✅✅
Deals✅✅✅✅✅
Tasks✅✅✅✅✅
Notes✅✅✅✅✅
Automations✅✅✅✅✅
Suggestions✅✅---
Health Scores✅✅---
Webhooks✅✅✅✅✅

9.4 Response Format

```json
{
"success": true,
"data": { ... },
"meta": {
"page": 1,
"limit": 20,
"total": 150
}
}
```

9.5 Error Codes

CodeHTTPDescription
UNAUTHORIZED401Invalid API key
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
VALIDATION_ERROR400Invalid data
RATE_LIMITED429Too many requests
INTERNAL_ERROR500Server error

10. Webhooks

10.1 Webhook Events

EventDescription
account.createdNew account
account.updatedAccount changed
deal.stage_changedDeal moved
deal.wonDeal closed won
deal.lostDeal closed lost
health.changedHealth score changed
alert.createdNew alert
automation.triggeredAutomation ran

10.2 Webhook Payload

```json
{
"id": "evt_abc123",
"type": "deal.won",
"created_at": "2026-01-07T10:30:00Z",
"data": {
"deal": { "id": "deal_xyz", "name": "Acme Corp", "amount": 50000 },
"account": { "id": "acc_123", "name": "Acme Corp" }
}
}
```

11. Security & Compliance

11.1 Data Security

MeasureImplementation
Encryption at RestAES-256
Encryption in TransitTLS 1.3
Key ManagementAWS KMS
Data IsolationRow-level security

11.2 Authentication

FeatureImplementation
User AuthSupabase Auth
API AuthAPI keys with scopes
SessionJWT, 24h expiry
MFATOTP-based 2FA

11.3 Compliance

StandardStatus
GDPRCompliant
SOC 2In progress
HIPAARoadmap

12. Infrastructure

12.1 Stack

ComponentTechnologyProvider
FrontendReact + ViteCloudflare Pages
APICloudflare WorkersCloudflare
DatabasePostgreSQLSupabase
CacheKV StoreCloudflare KV
QueueQueuesCloudflare Queues
Automationn8nn8n Cloud
AIOpenAI + AnthropicDirect API
StorageR2Cloudflare R2

12.2 Monthly Costs

ServiceMonthly Cost
Cloudflare Pages$5
Cloudflare Workers$5
Cloudflare R2~$5
Supabase Pro$25
n8n Cloud$20
OpenAI API~$50
Total~$110/month

13. Rate Limits

EndpointLimitWindow
Read operations10001 min
Write operations1001 min
Bulk operations101 min
Search1001 min
Render201 min

Glossary

TermDefinition
SpineCore data layer with normalized schemas
HubRouting layer for data access
LoaderConnector for external tools
BrainAI memory with vector search
RenderOutput generation engine
ContractZod schema for entities
BYOMBring Your Own Model

IntegrateWise Technical Documentation
Version 1.0 — January 2026

For questions: engineering@integratewise.com