# Integration Architecture

One picture and inventory of how Clones connect to your systems, data and each other, with scopes, owners, data flows and change control.

## What this is for

By Month 4, Clones are working across CRM, ERP, HR systems, ticketing and the data warehouse, and starting to hand work to each other. Without one shared picture, nobody can answer simple questions: what can this Clone touch, which skill writes to the ERP, what breaks if we upgrade the helpdesk? This document is that picture. It covers every connection, custom skill, data flow and handoff, plus the non-Clone AI and automation tools on the roadmap, so the platform stays governed instead of becoming a tangle.

## When to use it

Draft it when Department rollout 3 begins or the first cross-department workflow is designed, whichever is first. Update it before any new connection, custom skill or handoff goes live. Review it quarterly with IT and InfoSec. It becomes part of the handoff documentation at Month 12.

## Who's involved

- **Implementation Engineer** owns it.
- **IT lead** validates systems, environments and owners.
- **InfoSec lead** approves scopes and data flows.
- **Skill Engineering** documents custom skills.
- **CoE lead** takes ownership by Month 12.

## How to fill it in

1. Start from the Systems & Workflow Map and the Connections & Permissions Plan. Do not re-interview; extend.
2. Draw the context diagram (section 1): people and channels, Clones, skills, systems, and other AI or automation tools.
3. Fill in the connection inventory (section 2), one row per connection.
4. Document custom skills (section 3) with versions and tests.
5. Map data flows (section 4) including classification and where data rests.
6. Document Clone-to-Clone handoffs (section 5).
7. List adjacent AI and automation tools (section 6) so they are governed alongside Clones.
8. Record change control and failure handling (sections 7–8).

## The template

### 1. Context diagram

Show, left to right: **channels** (Slack, Teams, email, phone, SMS, Clone Team Studio) → **Clones** (grouped by department) → **skills** (Marketplace and custom) → **systems** (by owner) → **data stores**. Mark Commander-orchestrated workflows and every point where a person approves.

```
[Slack / Teams / Email / Phone]
        │
 ┌──────┴────────┐
 │ Support Clone │──skill: Helpdesk (v2.3, pinned)──▶ [Helpdesk]
 │               │──handoff──▶ [Billing Clone] ──skill: ERP AR (custom v1.1)──▶ [ERP]
 └───────────────┘                    │
                              approval: AR Manager
```

### 2. Connection inventory

| # | Clone | System | Connection type | Scope / permissions | Read / write | Data classification | Approved by | Approval date | System owner | Review due |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | _Support Triage Clone_ | _Helpdesk_ | _Service account_ | _Tickets: read, tag, assign; no delete_ | _Read + write_ | _Confidential (customer PII)_ | _InfoSec lead_ | _Day 41_ | _Support Ops_ | _Day 131_ |
| 2 | | | | | | | | | | |

### 3. Custom skills

| Skill | Built in | Purpose | Systems touched | Version in production | Pinned? | Test pack | Owner | Last change |
|---|---|---|---|---|---|---|---|---|
| _ERP AR Posting_ | _SkillForge_ | _Create AR entries from approved billing requests_ | _ERP_ | _v1.1_ | _Yes_ | _12 scenarios, all pass_ | _Skill Engineer → CoE builder_ | _Day 118_ |

### 4. Data flows

| Flow | From | To | Data | Classification | Where it rests | Retention | Encrypted in transit | Notes |
|---|---|---|---|---|---|---|---|---|
| _Ticket summary to billing_ | _Helpdesk_ | _Billing Clone_ | _Customer name, invoice no., issue_ | _Confidential_ | _Clone conversation history_ | _Per org retention setting_ | _Yes_ | _No card data in scope_ |

### 5. Clone-to-Clone handoffs

| Handoff | From Clone | To Clone | Trigger | Payload | Human checkpoint | Autonomy level | Failure handling |
|---|---|---|---|---|---|---|---|
| _Billing dispute_ | _Support Triage Clone_ | _Billing Clone_ | _Ticket tagged "billing"_ | _Ticket summary + invoice no._ | _AR Manager approves credit_ | _3_ | _Returns to Support queue with reason_ |

### 6. Adjacent AI and automation

| Tool | Use | Owner | Data access | Governed by | Relationship to Clones |
|---|---|---|---|---|---|
| _n8n_ | _Scheduled data sync ERP → warehouse_ | _IT_ | _ERP read_ | _AI Use Policy + IT change control_ | _Feeds data the Finance Clone reads_ |
| _Enterprise chat assistant_ | | | | | |

### 7. Change control

- [ ] Production skills are version-pinned
- [ ] Upgrades are tested against the skill's test pack before rollout
- [ ] New connections follow the Connections & Permissions Plan approval route
- [ ] System upgrades (helpdesk, ERP, etc.) trigger a re-test of dependent skills
- [ ] Changes are logged with date, version, approver and rollback version

| Date | Change | Component | Approved by | Tested | Rollback version |
|---|---|---|---|---|---|
| | | | | | |

### 8. Failure modes

| Failure | Detection | Impact | Response | Owner |
|---|---|---|---|---|
| _Expired connection credential_ | _Clone Health alert; skill errors_ | _Clone cannot read tickets_ | _Reconnect via approved account; notify Champion_ | _Implementation Engineer_ |
| _Upstream API change_ | | | | |
| _Rate limit reached_ | | | | |

## Good looks like

- One row per connection, with a named approver and a review date. Nothing in production is undocumented.
- Write access is the exception and always has a reason, a limit and a person in the loop until promotion.
- Service accounts, not personal tokens, for anything shared.
- Non-Clone AI tools are listed. Shadow AI is a governance gap even when it is not ours.
- The diagram matches reality. A stale architecture doc is worse than none.
- Common mistake: documenting the target state. Document what is live, and mark planned items clearly.

## How Clone helps

The **Solutions Architect Clone** drafts the inventory from the Systems & Workflow Map and the approved connections, generates the context diagram, and flags drift when a connection or skill version changes without an update. The **GRC Clone** checks every row against the Connections & Permissions Plan. The portal keeps the document versioned and links each row to its approval record.

## Sign-off

| Role | Name | Date | Decision |
|---|---|---|---|
| IT lead | | | Approved |
| InfoSec lead | | | Approved |
| Implementation Engineer | | | Issued (version ____) |

## Related

- [Systems & Workflow Map](/playbook/templates/systems-workflow-map)
- [Connections & Permissions Plan](/playbook/templates/connections-permissions-plan)
- [Clone Runbook](/playbook/templates/clone-runbook)
- [Slack channel history and custom skills](https://support.clone.org/articles/slack-channel-history-and-custom-skills)
- [Custom Skills & Integrations](https://clone.org/solutions/custom-skills-integrations)

---
From the Clone Solutions Playbook: https://solutions.clone.org/playbook/templates/integration-architecture
