{"slug":"documentation/INTEGRATEWISE_TECHNICAL_DOCS","title":"IntegrateWise Technical Documentation","section":"documentation","sectionLabel":"Documentation","status":"unclassified","type":"document","path":"documentation/INTEGRATEWISE_TECHNICAL_DOCS.mdx","bytes":22812,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n## Platform Architecture & Developer Reference\n\n**Version:** 1.0  \n**Last Updated:** January 2026  \n**Status:** Internal + Developer Reference\n\n---\n\n# Table of Contents\n\n1. System Overview\n2. Architecture Layers\n3. Data Model & Schema\n4. Connectors (Loaders)\n5. Routing & Permissions (Hubs)\n6. Automation Engine\n7. AI Integration\n8. Output Generation (Render)\n9. API Reference\n10. Webhooks\n11. Security & Compliance\n12. Infrastructure\n13. Deployment\n\n---\n\n# 1. System Overview\n\n## 1.1 What IntegrateWise Does\n\nIntegrateWise is a unified workspace platform that:\n\n- Connects to external business tools via APIs\n- Normalizes data into a consistent schema\n- Routes data to appropriate teams/functions\n- Provides AI-powered automation suggestions\n- Generates documents and reports from unified data\n\n## 1.2 Core Principles\n\n| Principle           | Implementation                                                 |\n| ------------------- | -------------------------------------------------------------- |\n| **Normalize Once**  | All data transformed to standard schema at ingestion           |\n| **Render Anywhere** | Same data outputs to any format (docs, slides, emails)         |\n| **User Control**    | AI suggests, user approves — nothing auto-runs without consent |\n| **Tool Agnostic**   | Works with any tool that has an API                            |\n\n## 1.3 High-Level Architecture\n\n\\`\\`\\`\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ PRESENTATION │\n│ React Frontend + Mobile (React Native) │\n└─────────────────────────────────────────────────────────────────────────────────┘\n│\n▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ API GATEWAY │\n│ Cloudflare Workers + KV Cache │\n└─────────────────────────────────────────────────────────────────────────────────┘\n│\n┌──────────────────┼──────────────────┐\n▼ ▼ ▼\n┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n│ RENDER │ │ AUTOMATION │ │ BRAIN │\n│ ENGINE │ │ ENGINE │ │ (AI MEM) │\n│ (Output) │ │ (n8n/CF) │ │ (Vector) │\n└─────────────┘ └─────────────┘ └─────────────┘\n│ │ │\n└──────────────────┼──────────────────┘\n▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ ROUTING LAYER (HUBS) │\n│ Permission checks, audit logging, data routing │\n└─────────────────────────────────────────────────────────────────────────────────┘\n│\n▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ DATA LAYER (SPINE) │\n│ Supabase PostgreSQL + Zod Schemas │\n└─────────────────────────────────────────────────────────────────────────────────┘\n│\n▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ CONNECTOR LAYER │\n│ OAuth handlers, API clients, sync jobs │\n└─────────────────────────────────────────────────────────────────────────────────┘\n│\n▼\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│ EXTERNAL TOOLS │\n│ Slack, HubSpot, Gmail, Notion, Salesforce, etc. │\n└─────────────────────────────────────────────────────────────────────────────────┘\n\\`\\`\\`\n\n---\n\n# 2. Architecture Layers\n\n## 2.1 Layer Summary\n\n| Layer | Name          | Purpose                         | Technology          |\n| ----- | ------------- | ------------------------------- | ------------------- |\n| **7** | Presentation  | User interface, dashboards      | React, React Native |\n| **6** | Render Engine | Output generation               | Cloudflare Workers  |\n| **5** | Automation    | AI suggestions, workflows       | n8n Cloud, Workers  |\n| **4** | Brain         | AI memory, conversation storage | Supabase pgvector   |\n| **3** | Connectors    | External tool integration       | Node.js, OAuth 2.0  |\n| **2** | Hubs          | Routing, permissions, audit     | PostgreSQL + RLS    |\n| **1** | Spine         | Core data storage               | Supabase PostgreSQL |\n| **0** | External      | Third-party tools               | Various APIs        |\n\n---\n\n# 3. Data Model & Schema\n\n## 3.1 Core Entities (12 Zod Contracts)\n\nAll data is normalized to these core entities:\n\n### Account\n\n\\`\\`\\`typescript\nid: z.string().uuid(),\nexternal_id: z.string(),\nsource: z.enum(['hubspot', 'salesforce', 'manual', 'import']),\nname: z.string().min(1).max(255),\ndomain: z.string().url().optional(),\nindustry: z.string().optional(),\nsize: z.enum(['startup', 'smb', 'mid-market', 'enterprise']).optional(),\nmrr: z.number().min(0).optional(),\narr: z.number().min(0).optional(),\ncurrency: z.string().length(3).default('USD'),\nstatus: z.enum(['prospect', 'active', 'churned', 'paused']),\nhealth_score: z.number().min(0).max(100).optional(),\ntags: z.array(z.string()).default([]),\ncustom_fields: z.record(z.unknown()).default({}),\ncreated_at: z.string().datetime(),\nupdated_at: z.string().datetime(),\n});\n\\`\\`\\`\n\n### Contact\n\n\\`\\`\\`typescript\nid: z.string().uuid(),\nexternal_id: z.string(),\nsource: z.enum(['hubspot', 'salesforce', 'gmail', 'manual']),\nemail: z.string().email(),\nfirst_name: z.string().optional(),\nlast_name: z.string().optional(),\nfull_name: z.string().optional(),\nphone: z.string().optional(),\ntitle: z.string().optional(),\ndepartment: z.string().optional(),\nrole_type: z.enum(['champion', 'decision_maker', 'influencer', 'user', 'unknown']).optional(),\naccount_id: z.string().uuid().optional(),\nowner_id: z.string().uuid().optional(),\nengagement_score: z.number().min(0).max(100).optional(),\ntags: z.array(z.string()).default([]),\ncreated_at: z.string().datetime(),\nupdated_at: z.string().datetime(),\n});\n\\`\\`\\`\n\n### Deal\n\n\\`\\`\\`typescript\nid: z.string().uuid(),\nexternal_id: z.string(),\nsource: z.enum(['hubspot', 'salesforce', 'manual']),\nname: z.string().min(1).max(255),\namount: z.number().min(0),\ncurrency: z.string().length(3).default('USD'),\nstage: z.string(),\nprobability: z.number().min(0).max(100).optional(),\nclose_date: z.string().datetime().optional(),\naccount_id: z.string().uuid().optional(),\ncontact_ids: z.array(z.string().uuid()).default([]),\nowner_id: z.string().uuid().optional(),\ndeal_type: z.enum(['new', 'renewal', 'upsell', 'expansion']).optional(),\ncreated_at: z.string().datetime(),\nupdated_at: z.string().datetime(),\n});\n\\`\\`\\`\n\n### All 12 Entities\n\n| Entity              | Purpose                 | Key Fields                          |\n| ------------------- | ----------------------- | ----------------------------------- |\n| **Account**         | Companies/organizations | name, domain, mrr, health_score     |\n| **Contact**         | People at accounts      | email, title, role_type, engagement |\n| **Deal**            | Sales opportunities     | amount, stage, probability          |\n| **Task**            | Action items            | title, status, due_date, assignee   |\n| **Event**           | Meetings, calls         | start_time, end_time, attendees     |\n| **Alert**           | Notifications           | severity, category, status          |\n| **Note**            | Comments, logs          | content, note_type, visibility      |\n| **Metric**          | KPIs, measurements      | value, period, trend                |\n| **ActivityLog**     | Audit trail             | action, entity, actor               |\n| **HealthScore**     | Account health          | score, components, risk_factors     |\n| **EngagementScore** | Contact engagement      | score, level, activity_counts       |\n| **User**            | Internal users          | email, role, team_ids               |\n\n---\n\n# 4. Connectors (Loaders)\n\n## 4.1 Available Connectors\n\n### Production Ready\n\n| Connector         | Data Types                 | Auth      | Sync      |\n| ----------------- | -------------------------- | --------- | --------- |\n| **Slack**         | Messages, channels, users  | OAuth 2.0 | Real-time |\n| **HubSpot**       | Contacts, companies, deals | OAuth 2.0 | 15 min    |\n| **Gmail**         | Emails, threads, labels    | OAuth 2.0 | 5 min     |\n| **Notion**        | Pages, databases           | OAuth 2.0 | 15 min    |\n| **Google Sheets** | Rows, columns              | OAuth 2.0 | On-demand |\n\n### Coming Soon\n\n| Connector      | Target Release |\n| -------------- | -------------- |\n| **Salesforce** | Q1 2026        |\n| **Zendesk**    | Q1 2026        |\n| **Intercom**   | Q1 2026        |\n| **GitHub**     | Q2 2026        |\n| **Jira**       | Q2 2026        |\n| **Stripe**     | Q1 2026        |\n\n## 4.2 Connector Implementation\n\n\\`\\`\\`typescript\nexport abstract class BaseConnector {\nabstract getName(): string;\nabstract getAuthUrl(): string;\nabstract handleCallback(code: string): Promise<ConnectionCredentials>;\nabstract refreshToken(): Promise<ConnectionCredentials>;\nabstract sync(options: SyncOptions): Promise<SyncResult>;\nabstract validateConnection(): Promise<boolean>;\n}\n\\`\\`\\`\n\n---\n\n# 5. Routing & Permissions (Hubs)\n\n## 5.1 Hub Definitions\n\n| Hub                  | Description                      | Data Types                          |\n| -------------------- | -------------------------------- | ----------------------------------- |\n| **Sales**            | Pipeline, leads, opportunities   | accounts, contacts, deals           |\n| **Marketing**        | Campaigns, content, analytics    | contacts, campaigns, metrics        |\n| **Customer Success** | Health, renewals, engagement     | accounts, health_scores, activities |\n| **Support**          | Tickets, issues, resolutions     | tickets, contacts, accounts         |\n| **Finance**          | Billing, invoices, revenue       | accounts, invoices, payments        |\n| **Product**          | Feature requests, bugs, feedback | feedback, tickets, accounts         |\n| **HR**               | Team info, hiring, onboarding    | users, teams                        |\n| **Tech**             | Incidents, deployments, code     | incidents, deploys, repos           |\n| **Legal**            | Contracts, compliance, approvals | contracts, approvals                |\n| **Operations**       | Processes, workflows, efficiency | workflows, metrics                  |\n\n## 5.2 Permission Levels\n\n| Role        | Permissions                | Access            |\n| ----------- | -------------------------- | ----------------- |\n| **Admin**   | read, write, delete, admin | Everything        |\n| **Manager** | read, write, delete        | Team + cross-team |\n| **Member**  | read, write                | Own team          |\n| **Viewer**  | read                       | Dashboards only   |\n\n## 5.3 Routing Rules\n\n\\`\\`\\`typescript\n// Example routing rules\nconst rules = [\n{\nname: 'HubSpot deals to Sales',\ncondition: { type: 'source', value: 'hubspot' },\ndata_types: ['deals'],\ntarget_hub: 'sales',\n},\n{\nname: 'Support keywords to Support hub',\ncondition: { type: 'keyword', value: ['refund', 'cancel', 'issue'] },\ndata_types: ['emails', 'messages'],\ntarget_hub: 'support',\n},\n{\nname: 'High-value deals to Sales + Leadership',\ncondition: { type: 'amount_threshold', value: 50000 },\ndata_types: ['deals'],\ntarget_hub: ['sales', 'leadership'],\n},\n];\n\\`\\`\\`\n\n---\n\n# 6. Automation Engine\n\n## 6.1 Automation Structure\n\n\\`\\`\\`typescript\ninterface Automation {\nid: string;\nname: string;\ntrigger: AutomationTrigger;\nconditions: AutomationCondition[];\nactions: AutomationAction[];\napproval_mode: 'suggest_only' | 'auto_run_notify' | 'auto_run_silent';\nenabled: boolean;\n}\n\\`\\`\\`\n\n## 6.2 Trigger Types\n\n| Trigger            | Description            | Example            |\n| ------------------ | ---------------------- | ------------------ |\n| **record_created** | New record added       | New lead from form |\n| **record_updated** | Record changed         | Deal stage moved   |\n| **field_changed**  | Specific field changed | Status → Churned   |\n| **schedule**       | Cron-based             | Daily at 9 AM      |\n| **webhook**        | External trigger       | Stripe payment     |\n| **time_elapsed**   | No activity for X days | 7 days no response |\n\n## 6.3 Action Types\n\n| Action                | Description                   |\n| --------------------- | ----------------------------- |\n| **update_field**      | Change a field value          |\n| **create_task**       | Create a task                 |\n| **send_notification** | Send app/email notification   |\n| **create_alert**      | Create an alert               |\n| **assign_to**         | Assign to user                |\n| **calculate_score**   | Recalculate health/engagement |\n| **call_webhook**      | POST to external URL          |\n\n## 6.4 Approval Modes\n\n| Mode                | Behavior                            |\n| ------------------- | ----------------------------------- |\n| **suggest_only**    | Creates suggestion, user approves   |\n| **auto_run_notify** | Runs automatically, notifies user   |\n| **auto_run_silent** | Runs automatically, no notification |\n\n---\n\n# 7. AI Integration\n\n## 7.1 Supported AI Services\n\n| Service       | Use Case                | Model         |\n| ------------- | ----------------------- | ------------- |\n| **OpenAI**    | Default completions     | gpt-4-turbo   |\n| **Anthropic** | Alternative completions | claude-3-opus |\n| **BYOM**      | Custom models           | User-provided |\n\n## 7.2 AI Features\n\n| Feature               | Description                |\n| --------------------- | -------------------------- |\n| **Completions**       | Text generation            |\n| **Embeddings**        | Vector search              |\n| **Summarization**     | Condense text              |\n| **Classification**    | Categorize content         |\n| **Entity Extraction** | Extract names, dates, etc. |\n\n## 7.3 Brain (Vector Memory)\n\n\\`\\`\\`typescript\nexport class BrainService {\nasync store(conversation: Conversation): Promise<void>;\nasync search(query: string, options: SearchOptions): Promise<Memory[]>;\nasync getRelated(memoryId: string, limit: number): Promise<Memory[]>;\n}\n\\`\\`\\`\n\n## 7.4 BYOM (Bring Your Own Model)\n\n\\`\\`\\`typescript\nconst customModel = new BYOMService({\nendpoint: 'https://my-model.company.com/v1/completions',\napiKey: process.env.CUSTOM_MODEL_API_KEY,\n});\naiRouter.setCustomService('custom', customModel);\n\\`\\`\\`\n\n---\n\n# 8. Output Generation (Render)\n\n## 8.1 Supported Formats\n\n| Format       | Extension | Use Case           |\n| ------------ | --------- | ------------------ |\n| **Document** | .docx     | Reports, proposals |\n| **Slides**   | .pptx     | Presentations      |\n| **PDF**      | .pdf      | Final documents    |\n| **Email**    | HTML/Text | Outreach           |\n| **CSV**      | .csv      | Data export        |\n| **JSON**     | .json     | API responses      |\n\n## 8.2 Template System\n\n\\`\\`\\`typescript\n// Placeholders\n{{account.name}}\n{{health_score.score}}\n{{formatDate(created_at, 'MMMM D, YYYY')}}\n{{formatCurrency(amount, 'USD')}}\n\\`\\`\\`\n\n## 8.3 Built-in Templates\n\n| Template               | Format | Data Sources                   |\n| ---------------------- | ------ | ------------------------------ |\n| Weekly Status Report   | DOCX   | accounts, deals, activities    |\n| Customer Health Report | DOCX   | account, health_score, tickets |\n| QBR Deck               | PPTX   | account, metrics, deals        |\n| Pipeline Report        | PDF    | deals, metrics                 |\n| Check-in Email         | Email  | account, activities            |\n\n---\n\n# 9. API Reference\n\n## 9.1 Authentication\n\n\\`\\`\\`http\nAuthorization: Bearer <api_key>\n\\`\\`\\`\n\n## 9.2 Base URL\n\n\\`\\`\\`\nProduction: https://api.integratewise.com/v1\n\\`\\`\\`\n\n## 9.3 Endpoints Summary\n\n| Resource      | List | Get | Create | Update | Delete |\n| ------------- | ---- | --- | ------ | ------ | ------ |\n| Accounts      | ✅   | ✅  | ✅     | ✅     | ✅     |\n| Contacts      | ✅   | ✅  | ✅     | ✅     | ✅     |\n| Deals         | ✅   | ✅  | ✅     | ✅     | ✅     |\n| Tasks         | ✅   | ✅  | ✅     | ✅     | ✅     |\n| Notes         | ✅   | ✅  | ✅     | ✅     | ✅     |\n| Automations   | ✅   | ✅  | ✅     | ✅     | ✅     |\n| Suggestions   | ✅   | ✅  | -      | -      | -      |\n| Health Scores | ✅   | ✅  | -      | -      | -      |\n| Webhooks      | ✅   | ✅  | ✅     | ✅     | ✅     |\n\n## 9.4 Response Format\n\n\\`\\`\\`json\n{\n\"success\": true,\n\"data\": { ... },\n\"meta\": {\n\"page\": 1,\n\"limit\": 20,\n\"total\": 150\n}\n}\n\\`\\`\\`\n\n## 9.5 Error Codes\n\n| Code             | HTTP | Description              |\n| ---------------- | ---- | ------------------------ |\n| UNAUTHORIZED     | 401  | Invalid API key          |\n| FORBIDDEN        | 403  | Insufficient permissions |\n| NOT_FOUND        | 404  | Resource not found       |\n| VALIDATION_ERROR | 400  | Invalid data             |\n| RATE_LIMITED     | 429  | Too many requests        |\n| INTERNAL_ERROR   | 500  | Server error             |\n\n---\n\n# 10. Webhooks\n\n## 10.1 Webhook Events\n\n| Event                | Description          |\n| -------------------- | -------------------- |\n| account.created      | New account          |\n| account.updated      | Account changed      |\n| deal.stage_changed   | Deal moved           |\n| deal.won             | Deal closed won      |\n| deal.lost            | Deal closed lost     |\n| health.changed       | Health score changed |\n| alert.created        | New alert            |\n| automation.triggered | Automation ran       |\n\n## 10.2 Webhook Payload\n\n\\`\\`\\`json\n{\n\"id\": \"evt_abc123\",\n\"type\": \"deal.won\",\n\"created_at\": \"2026-01-07T10:30:00Z\",\n\"data\": {\n\"deal\": { \"id\": \"deal_xyz\", \"name\": \"Acme Corp\", \"amount\": 50000 },\n\"account\": { \"id\": \"acc_123\", \"name\": \"Acme Corp\" }\n}\n}\n\\`\\`\\`\n\n---\n\n# 11. Security & Compliance\n\n## 11.1 Data Security\n\n| Measure                   | Implementation     |\n| ------------------------- | ------------------ |\n| **Encryption at Rest**    | AES-256            |\n| **Encryption in Transit** | TLS 1.3            |\n| **Key Management**        | AWS KMS            |\n| **Data Isolation**        | Row-level security |\n\n## 11.2 Authentication\n\n| Feature       | Implementation       |\n| ------------- | -------------------- |\n| **User Auth** | Supabase Auth        |\n| **API Auth**  | API keys with scopes |\n| **Session**   | JWT, 24h expiry      |\n| **MFA**       | TOTP-based 2FA       |\n\n## 11.3 Compliance\n\n| Standard  | Status      |\n| --------- | ----------- |\n| **GDPR**  | Compliant   |\n| **SOC 2** | In progress |\n| **HIPAA** | Roadmap     |\n\n---\n\n# 12. Infrastructure\n\n## 12.1 Stack\n\n| Component  | Technology         | Provider          |\n| ---------- | ------------------ | ----------------- |\n| Frontend   | React + Vite       | Cloudflare Pages  |\n| API        | Cloudflare Workers | Cloudflare        |\n| Database   | PostgreSQL         | Supabase          |\n| Cache      | KV Store           | Cloudflare KV     |\n| Queue      | Queues             | Cloudflare Queues |\n| Automation | n8n                | n8n Cloud         |\n| AI         | OpenAI + Anthropic | Direct API        |\n| Storage    | R2                 | Cloudflare R2     |\n\n## 12.2 Monthly Costs\n\n| Service            | Monthly Cost    |\n| ------------------ | --------------- |\n| Cloudflare Pages   | $5              |\n| Cloudflare Workers | $5              |\n| Cloudflare R2      | ~$5             |\n| Supabase Pro       | $25             |\n| n8n Cloud          | $20             |\n| OpenAI API         | ~$50            |\n| **Total**          | **~$110/month** |\n\n---\n\n# 13. Rate Limits\n\n| Endpoint         | Limit | Window |\n| ---------------- | ----- | ------ |\n| Read operations  | 1000  | 1 min  |\n| Write operations | 100   | 1 min  |\n| Bulk operations  | 10    | 1 min  |\n| Search           | 100   | 1 min  |\n| Render           | 20    | 1 min  |\n\n---\n\n# Glossary\n\n| Term         | Definition                              |\n| ------------ | --------------------------------------- |\n| **Spine**    | Core data layer with normalized schemas |\n| **Hub**      | Routing layer for data access           |\n| **Loader**   | Connector for external tools            |\n| **Brain**    | AI memory with vector search            |\n| **Render**   | Output generation engine                |\n| **Contract** | Zod schema for entities                 |\n| **BYOM**     | Bring Your Own Model                    |\n\n---\n\n**IntegrateWise Technical Documentation**  \n_Version 1.0 — January 2026_\n\nFor questions: engineering@integratewise.com\n"}