> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Full Integration Overview

> A map of the four independent pieces a real business-system integration needs — policy, caller, connector, signal verification — and how they fit together. Read this before the individual deep-dive guides.

<Info>
  Repo copy of this guide: `docs/connectors/FULL_INTEGRATION_OVERVIEW.md`, kept
  in sync with this page. This page is a map, not a replacement for the four
  deep-dive guides it links to.
</Info>

**A naming trap worth avoiding first:** this codebase has two different things called
"connector." [`@parmana/connector-sdk`](/integrations/overview) is a generic library with
reference mocks (`SapConnector`, `OracleConnector`, etc.) that never talk to a real system. The
connectors the default server actually registers and runs in production — HubSpot, GitHub,
Paytm, Slack — follow a different, simpler pattern documented in the
[Connector Development Guide](/integrations/connector-development-guide). This page is about
that second, real pattern.

## The four pieces

| # | Piece                                      | Answers                                                       | Exists independently of the others?                                              |
| - | ------------------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| 1 | **A policy** bound to a capability         | Should this request be allowed?                               | Yes — can reject/approve with zero connectors or callers ever wired to it.       |
| 2 | **A caller (agent)** with a scoped API key | Who's allowed to even ask?                                    | Yes — can get real `APPROVED`/`REJECTED` decisions with no connector registered. |
| 3 | **A connector** for the capability         | Who performs the real-world action once approved?             | Yes — testable in isolation with `MockConnector`/hermetic tests.                 |
| 4 | **A `SignalStateVerifier`** (optional)     | Are the caller's claims about real-world state actually true? | Yes — most capabilities don't have one; it's additive hardening.                 |

They're deliberately decoupled — that's exactly why "got `APPROVED`" and "the action actually
happened" are two separate, independently-verifiable claims (see
[Connect an Agent](/guides/connect-an-agent), Step 8).

## Recommended build order

1. **Write the policy first** — [Write Your First Policy](/guides/write-your-first-policy).
   Everything else needs the exact capability string and `signalsSchema` up front.
2. **Onboard a caller and test authorization with no connector yet** —
   [Connect an Agent](/guides/connect-an-agent). A `500` ("no connector registered") at this
   stage is expected — it confirms authorization works before execution is wired.
3. **Build the connector** — [Connector Development Guide](/integrations/connector-development-guide).
4. **Add a `SignalStateVerifier` only if a caller lying about a signal is a real risk** for this
   capability that a policy rule alone can't catch.

## What breaks if you skip a piece

Every row here is a real failure mode this codebase has actually hit and diagnosed, several the
same night integrating a real refund-agent partner.

| You have                                                  | Missing               | What happens                                                                                                                                                |
| --------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Policy + caller key                                       | Connector             | `APPROVED`, then `500` at dispatch — not a bug, see the response reference table.                                                                           |
| Connector + caller key                                    | Policy                | `404 PolicyNotFoundError` — never reaches your connector.                                                                                                   |
| Policy + connector                                        | Caller key / scoping  | `401`, or `403 CAPABILITY_NOT_ALLOWED`, or `403` (principal not permitted).                                                                                 |
| All three                                                 | `SignalStateVerifier` | Works, but a caller's false signal claim is trusted at face value — a named, accepted scope limit, not a hidden bug.                                        |
| Everything, but the deployment's signing config is broken | —                     | An otherwise-correct request fails with an opaque `500` unrelated to the caller — an operator-side problem none of the four pieces can detect from outside. |

## Next

<CardGroup cols={2}>
  <Card title="Write Your First Policy" icon="scroll" href="/guides/write-your-first-policy">
    Author the policy that decides APPROVE/REJECT for your capability.
  </Card>

  <Card title="Connect an Agent" icon="robot" href="/guides/connect-an-agent">
    Onboard a caller with a scoped API key and test authorization end to end.
  </Card>

  <Card title="Connector Development Guide" icon="plug" href="/integrations/connector-development-guide">
    Implement and register the connector that performs the real action.
  </Card>

  <Card title="Credential Isolation" icon="lock" href="/concepts/credential-isolation">
    How a connector receives a credential it never fetches itself.
  </Card>
</CardGroup>