# fellipessanha/pluggy_ai_ex architecture

> Architecture diagram of the GitHub repository fellipessanha/pluggy_ai_ex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fellipessanha/pluggy_ai_ex
- Repository: https://github.com/fellipessanha/pluggy_ai_ex

## Overview

1. **What this repo is**
   - `pluggy_ai_ex` is an Elixir client library for the Pluggy open-finance REST API.
   - Its main job is to hide raw HTTP and normalize Pluggy’s responses into idiomatic Elixir values and control flow.

2. **Main architectural boundary**
   - Everything under `lib/pluggy/*.ex` is the public API surface.
   - The external system is the Pluggy platform itself: API endpoints for authentication, connectors, items, accounts, transactions, investments, identity, and loans.
   - A second external boundary is the Pluggy Connect widget, which is exposed through optional UI integrations.

3. **Core request flow**
   - Typical usage starts with `Pluggy.Client` creating/authenticating a client from a client ID/secret.
   - That client is then carried through `Pluggy.Session`, which bundles client state, a connect token, and an item connection.
   - Resource modules (`Accounts`, `Transactions`, `Investments`, etc.) use that session/client context to call the API.

4. **Authentication and session management**
   - `Pluggy.Auth` and `Pluggy.Client` are the auth-facing layer.
   - `Pluggy.Session` is intentionally stateless and acts as a convenience wrapper for moving through the Connect flow: create token, receive item data, then query data with that item.
   - `Pluggy.Item`-style state is the pivot for post-connection data access.

5. **Resource modules**
   - The repo is organized by domain, not by transport:
     - `Connectors` for institution discovery/validation
     - `Items` for managing bank connections
     - `Accounts` for account and statement retrieval
     - `Transactions` for transaction listing and updates
     - `Investments` for investments and related transactions
     - `Identity` for KYC/personal identity data
     - `Loans` for loan data
   - Each of these modules is a thin domain wrapper over the same underlying HTTP/API layer.

6. **HTTP and API normalization layer**
   - `Pluggy.HTTP` is the transport boundary for the REST calls.
   - `Pluggy.Error` centralizes API/client failure representation.
   - `Pluggy.KeyTransform` and `Pluggy.Unwrap` are response-shaping helpers: they convert Pluggy payloads into snake_case atom-key maps and unwrap nested or paginated API responses.
   - `Pluggy.HTTP.Cursor` represents cursor-based pagination as an opaque value for incremental iteration.

7. **Connect widget subsystem**
   - `Pluggy.Connect` is the feature boundary for the bank-connection UI flow.
   - `Pluggy.Connect.Kino` wraps the widget for Livebook via `Kino.JS.Live`.
   - `Pluggy.Connect.Live` wraps it for Phoenix LiveView via `Phoenix.Component`.
   - The README makes clear these integrations are optional and compile only when the relevant dependencies are present, so the core API client stays lean.

8. **Static asset and JS integration**
   - `priv/static/pluggy_connect_hook.js` is the browser-side hook used by the connect UI wrappers.
   - This implies the widget integration spans Elixir server-side code plus a small client-side JavaScript bridge.

9. **Developer experience and distribution**
   - `demo/pluggy_demo.livemd` is the primary example entry point for hands-on usage.
   - `design-docs/` captures architecture and implementation context, suggesting the repo was designed with a clear separation between API client, response handling, and UI embedding.
   - `.github/workflows/ci.yml` plus formatting/pre-commit config show the project is packaged as a library with CI and code-quality enforcement.

10. **Testing structure**
   - Tests mirror the public modules one-for-one under `test/pluggy/*_test.exs`.
   - `test/support/mock_plug.ex` and fixtures indicate HTTP behavior is tested with mocked API interactions rather than live Pluggy calls.
   - This reinforces that the core architecture is a pure client wrapper with a narrow transport boundary.

11. **How to draw the architecture**
   - Draw Pluggy API and Connect widget as external services on the right.
   - Put `Pluggy.HTTP` in the middle as the transport layer.
   - Above it, place the domain modules (`Accounts`, `Transactions`, `Items`, etc.) and auth/session modules.
   - Separate the Connect UI adapters (`Kino`, `Live`) from the core client, with the JS asset beneath them.
   - Show `Unwrap`, `KeyTransform`, and `Error` as shared cross-cutting utilities feeding all resource modules.

Main entry points: [`lib/pluggy/http.ex`](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/http.ex) (HTTP), [`lib/pluggy/connect.ex`](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connect.ex) (Connect), [`lib/pluggy.ex`](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy.ex) (Pluggy), [`lib/pluggy/session.ex`](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/session.ex) (Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core client"]
  node_pluggy["Pluggy<br/>facade<br/>[pluggy.ex]"]
  node_auth["Auth<br/>[auth.ex]"]
  node_client["Client<br/>[client.ex]"]
  node_session["Session<br/>[session.ex]"]
  node_http["HTTP<br/>transport<br/>[http.ex]"]
  node_error["Error<br/>[error.ex]"]
  node_unwrap["Unwrap<br/>response shaping<br/>[unwrap.ex]"]
  node_key_transform["Key Transform<br/>response shaping<br/>[key_transform.ex]"]
end

subgraph group_resources["API domains"]
  node_connectors["Connectors<br/>domain<br/>[connectors.ex]"]
  node_items["Items<br/>domain<br/>[items.ex]"]
  node_accounts["Accounts<br/>domain<br/>[accounts.ex]"]
  node_transactions["Transactions<br/>domain<br/>[transactions.ex]"]
  node_investments["Investments<br/>domain<br/>[investments.ex]"]
  node_identity["Identity<br/>domain<br/>[identity.ex]"]
  node_loans["Loans<br/>domain<br/>[loans.ex]"]
end

subgraph group_connect["Connect UI"]
  node_connect_api["Connect<br/>ui boundary<br/>[connect.ex]"]
  node_kino["Kino<br/>adapter<br/>[kino.ex]"]
  node_live["LiveView<br/>adapter<br/>[live.ex]"]
end

subgraph group_external["External systems"]
  node_pluggy_api[("Pluggy API<br/>external service")]
  node_widget["Connect Widget<br/>external service"]
  node_js_hook["JS Hook<br/>browser bridge"]
  node_livebook["Livebook<br/>host runtime"]
  node_phoenix["Phoenix<br/>host runtime"]
end

node_pluggy -->|"public API"| node_auth
node_pluggy -->|"public API"| node_client
node_pluggy -->|"public API"| node_session
node_pluggy -->|"public API"| node_connect_api
node_auth -->|"builds"| node_client
node_client -->|"uses"| node_http
node_session -->|"carries"| node_client
node_session -->|"flows through"| node_items
node_http -->|"calls"| node_pluggy_api
node_http -->|"maps failures"| node_error
node_http -->|"unwraps"| node_unwrap
node_http -->|"normalizes"| node_key_transform
node_connectors -->|"calls"| node_http
node_items -->|"calls"| node_http
node_accounts -->|"calls"| node_http
node_transactions -->|"calls"| node_http
node_investments -->|"calls"| node_http
node_identity -->|"calls"| node_http
node_loans -->|"calls"| node_http
node_connect_api -->|"embeds"| node_widget
node_connect_api -->|"loads"| node_js_hook
node_kino -->|"wraps"| node_connect_api
node_live -->|"wraps"| node_connect_api
node_kino -->|"runs in"| node_livebook
node_live -->|"runs in"| node_phoenix
node_connect_api -->|"connect flow"| node_session
node_unwrap -->|"feeds"| node_accounts
node_unwrap -->|"feeds"| node_transactions
node_key_transform -->|"feeds"| node_accounts
node_key_transform -->|"feeds"| node_items
node_error -->|"feeds"| node_auth
node_error -->|"feeds"| node_http

click node_pluggy "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy.ex"
click node_auth "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/auth.ex"
click node_client "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/client.ex"
click node_session "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/session.ex"
click node_http "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/http.ex"
click node_error "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/error.ex"
click node_unwrap "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/unwrap.ex"
click node_key_transform "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/key_transform.ex"
click node_connectors "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connectors.ex"
click node_items "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/items.ex"
click node_accounts "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/accounts.ex"
click node_transactions "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/transactions.ex"
click node_investments "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/investments.ex"
click node_identity "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/identity.ex"
click node_loans "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/loans.ex"
click node_connect_api "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connect.ex"
click node_kino "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connect/kino.ex"
click node_live "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connect/live.ex"
click node_js_hook "https://github.com/fellipessanha/pluggy_ai_ex/blob/main/priv/static/pluggy_connect_hook.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pluggy,node_auth,node_client,node_session,node_http,node_error,node_unwrap,node_key_transform toneBlue
class node_connectors,node_items,node_accounts,node_transactions,node_investments,node_identity,node_loans toneAmber
class node_connect_api,node_kino,node_live toneMint
class node_pluggy_api,node_widget,node_js_hook,node_livebook,node_phoenix toneRose
```

## Components

### Core client

Authentication, session, transport, and shared response shaping.

- [Pluggy](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy.ex): facade · Top-level public entrypoint for the library. · `lib/pluggy.ex`
- [Auth](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/auth.ex): auth · Client authentication and token-facing API. · `lib/pluggy/auth.ex`
- [Client](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/client.ex): client · Builds and carries authenticated API client state. · `lib/pluggy/client.ex`
- [Session](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/session.ex): session · Convenience wrapper for connect-flow state and item access. · `lib/pluggy/session.ex`
- [HTTP](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/http.ex): transport · REST transport boundary for Pluggy requests. · `lib/pluggy/http.ex`
- [Error](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/error.ex): errors · Normalized client and API failure representation. · `lib/pluggy/error.ex`
- [Unwrap](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/unwrap.ex): response shaping · Extracts nested and paginated payloads into idiomatic values. · `lib/pluggy/unwrap.ex`
- [Key Transform](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/key_transform.ex): response shaping · Converts Pluggy payload keys into snake_case atom-key maps. · `lib/pluggy/key_transform.ex`

### API domains

Thin domain wrappers over the Pluggy REST API.

- [Connectors](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connectors.ex): domain · Institution discovery and validation operations. · `lib/pluggy/connectors.ex`
- [Items](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/items.ex): domain · Bank connection lifecycle and item management. · `lib/pluggy/items.ex`
- [Accounts](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/accounts.ex): domain · Account and statement retrieval. · `lib/pluggy/accounts.ex`
- [Transactions](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/transactions.ex): domain · Transaction listing and updates. · `lib/pluggy/transactions.ex`
- [Investments](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/investments.ex): domain · Investment data and related transactions. · `lib/pluggy/investments.ex`
- [Identity](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/identity.ex): domain · KYC and personal identity data access. · `lib/pluggy/identity.ex`
- [Loans](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/loans.ex): domain · Loan data access. · `lib/pluggy/loans.ex`

### Connect UI

Optional widget integrations for embedding the Pluggy connection flow.

- [Connect](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connect.ex): ui boundary · Feature boundary for the bank-connection widget flow. · `lib/pluggy/connect.ex`
- [Kino](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connect/kino.ex): adapter · Livebook wrapper for the connect widget. · `lib/pluggy/connect/kino.ex`
- [LiveView](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/lib/pluggy/connect/live.ex): adapter · Phoenix LiveView wrapper for the connect widget. · `lib/pluggy/connect/live.ex`

### External systems

Remote services and client-side bridge used by the library.

- **Pluggy API**: external service · Remote Open Finance REST API.
- **Connect Widget**: external service · External bank-connection UI provided by Pluggy.
- [JS Hook](https://github.com/fellipessanha/pluggy_ai_ex/blob/main/priv/static/pluggy_connect_hook.js): browser bridge · Client-side JavaScript bridge for the embedded widget. · `priv/static/pluggy_connect_hook.js`
- **Livebook**: host runtime · Optional host for the Kino integration.
- **Phoenix**: host runtime · Optional host for the LiveView integration.

## Connections

- Pluggy → Auth: public API · Top-level entrypoint exposes auth-facing functions.
- Pluggy → Client: public API · Top-level entrypoint exposes client functions.
- Pluggy → Session: public API · Top-level entrypoint exposes session helpers.
- Pluggy → Connect: public API · Top-level entrypoint exposes connect helpers.
- Auth → Client: builds · Authentication creates authenticated client state.
- Client → HTTP: uses · Client delegates remote calls through the HTTP layer.
- Session → Client: carries · Session bundles and forwards client state.
- Session → Items: flows through · Session pivots on item state after connect.
- HTTP → Pluggy API: calls · HTTP transport talks to the Pluggy API.
- HTTP → Error: maps failures · Transport normalizes errors into repository error values.
- HTTP → Unwrap: unwraps · Transport helpers flatten nested or paginated responses.
- HTTP → Key Transform: normalizes · Transport helpers convert API keys into idiomatic maps.
- Connectors → HTTP: calls · Domain wrapper delegates REST requests to transport.
- Items → HTTP: calls · Domain wrapper delegates REST requests to transport.
- Accounts → HTTP: calls · Domain wrapper delegates REST requests to transport.
- Transactions → HTTP: calls · Domain wrapper delegates REST requests to transport.
- Investments → HTTP: calls · Domain wrapper delegates REST requests to transport.
- Identity → HTTP: calls · Domain wrapper delegates REST requests to transport.
- Loans → HTTP: calls · Domain wrapper delegates REST requests to transport.
- Connect → Connect Widget: embeds · Connect feature boundary wraps the external widget.
- Connect → JS Hook: loads · Widget integration relies on the browser hook asset.
- Kino → Connect: wraps · Livebook adapter wraps the connect feature boundary.
- LiveView → Connect: wraps · LiveView adapter wraps the connect feature boundary.
- Kino → Livebook: runs in · Kino integration is hosted in Livebook.
- LiveView → Phoenix: runs in · LiveView integration is hosted in Phoenix.
- Connect → Session: connect flow · Connect flow produces session and item state used for later API access.
- Unwrap → Accounts: feeds · Shared shaping helpers support resource responses.
- Unwrap → Transactions: feeds · Shared shaping helpers support resource responses.
- Key Transform → Accounts: feeds · Shared shaping helpers support resource responses.
- Key Transform → Items: feeds · Shared shaping helpers support resource responses.
- Error → Auth: feeds · Shared failure model is used across auth-facing code.
- Error → HTTP: feeds · Shared failure model is used across transport code.
