How fellipessanha/pluggy_ai_ex works
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: http.ex HTTP · connect.ex Connect · pluggy.ex Pluggy · session.ex Session
Components 23
Core client
Authentication, session, transport, and shared response shaping.
- Pluggy · Top-level public entrypoint for the library.
lib/pluggy.ex - Auth · Client authentication and token-facing API.
lib/pluggy/auth.ex - Client · Builds and carries authenticated API client state.
lib/pluggy/client.ex - Session · Convenience wrapper for connect-flow state and item access.
lib/pluggy/session.ex - HTTP · REST transport boundary for Pluggy requests.
lib/pluggy/http.ex - Error · Normalized client and API failure representation.
lib/pluggy/error.ex - Unwrap · Extracts nested and paginated payloads into idiomatic values.
lib/pluggy/unwrap.ex - Key Transform · 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 · Institution discovery and validation operations.
lib/pluggy/connectors.ex - Items · Bank connection lifecycle and item management.
lib/pluggy/items.ex - Accounts · Account and statement retrieval.
lib/pluggy/accounts.ex - Transactions · Transaction listing and updates.
lib/pluggy/transactions.ex - Investments · Investment data and related transactions.
lib/pluggy/investments.ex - Identity · KYC and personal identity data access.
lib/pluggy/identity.ex - Loans · Loan data access.
lib/pluggy/loans.ex
Connect UI
Optional widget integrations for embedding the Pluggy connection flow.
External systems
Remote services and client-side bridge used by the library.
- Pluggy API · Remote Open Finance REST API.
- Connect Widget · External bank-connection UI provided by Pluggy.
- JS Hook · Client-side JavaScript bridge for the embedded widget.
priv/static/pluggy_connect_hook.js - Livebook · Optional host for the Kino integration.
- Phoenix · Optional host for the LiveView integration.
Connections 32
- 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.