# Architecture Overview

AIP is a layered Rust workspace. The filesystem mirrors the runtime boundary so
core semantics, transport mechanics, compatibility profiles, product connectors,
and daemon boot code do not collapse into one crate.

```text
Native or compatibility client
  -> transport/profile ingress
    -> authenticated gateway
      -> policy and native runtime
        -> lifecycle stores and handlers
          -> connector or local capability implementation
      -> operational read model, events, receipts, and callbacks
```

## Layers

1. `aip-core` defines typed ids, principals, sessions, capabilities, actions,
   events, channel messages, audit payloads, receipts, settlements, and the
   native envelope.
2. `aip-schema`, `aip-crypto`, and `aip-auth` provide validation,
   cryptographic primitives, and authorization policy building blocks.
3. `aip-discovery` and `aip-runtime` manage manifests, sessions, actions,
   approvals, transactions, delegation, idempotency, callbacks, event streams,
   operational queries, and lifecycle stores.
4. `aip-transport-*` crates define HTTP, NATS, SSE, and WebSocket bindings.
5. `aip-profile-*` crates translate MCP, A2A-style agent cards, and signed
   webhooks into AIP semantics.
6. `aip-connector` defines the frozen connector boundary, while
   `aip-connector-*` crates translate product systems such as Dify, CrewAI,
   Chatwoot, Cal.diy, and Hermes Agent.
7. `aip-gateway` and `aipd` compose embedded and daemon runtimes. `aipctl` is an
   external operator and conformance client over supported transports.
8. `aip-storage-postgres` implements the reference multi-process durable
   backend; local file storage remains a single-host option.

## Design Rules

- `aip-core` has no async runtime, network, product, crypto, or mandatory schema
  tooling dependency.
- Product DTOs never enter `aip-core`.
- Transports move envelopes; they do not decide product semantics.
- Profiles map protocols; they do not call product APIs.
- Connectors translate products; they do not define global policy.
- Gateway composes; runtime executes lifecycle behavior.

The [Dependency Graph](dependency-graph.md) shows crate direction. The
[Gateway](gateway.md), [Runtime](runtime.md), and
[Security Model](security-model.md) documents describe the principal execution
and trust boundaries in more detail.