# plaid/tutorial-resources architecture

> Architecture diagram of the GitHub repository plaid/tutorial-resources, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/plaid/tutorial-resources
- Repository: https://github.com/plaid/tutorial-resources

## Overview

##### Project Type and Purpose
- This repository is not a single full-stack application but rather a collection of standalone sample projects designed to teach different aspects of working with the Plaid API (Auth, Transactions, Webhooks, OAuth handling, and an iOS client).
- The overall purpose is educational – guiding developers through incremental improvements in integrating with Plaid. This means each sample is self-contained, but many share similar client-server patterns.

##### Analyzing the File Structure
- Notice that the top-level directories (auth, ios-swift, transactions, vanilla-js-oauth, webhooks) represent the different tutorial samples.
- In the web and Node-based samples (auth, transactions, vanilla-js-oauth, webhooks), there are directories like “public” (containing HTML and JavaScript for the client side) and files like server.js (the Node server). In contrast, the ios-swift sample contains an Xcode project (client for iOS) alongside a server directory.
- Presence of configuration files (.env.template, .npmrc, package.json, etc.) that indicate use of environment variables and Node/npm dependencies in many samples.

##### Key Components
a. Main Components:
- Client Applications – Web-based UIs (in the public directories) serving static pages and JavaScript files; iOS native client in the ios-swift sample.
- Server Applications – Node-based servers running server.js files for handling API routes, processing requests (as seen in auth, transactions, vanilla-js-oauth, and webhooks); also a dedicated “server” component in ios-swift.
- Sample Data/Helpers – Directories like “user_files” or “database” (e.g., in transactions) suggest sample or mock data storage.
- Configuration & Environment – .env.template, .npmrc, and package.json files indicate dependency management and environment settings.

b. Relationships/Interactions:
- Clients send requests to their corresponding servers – for instance, a web client in the “public” directory makes HTTP calls to the Node server (server.js) in the same tutorial sample.
- In the ios-swift sample, the iOS client interacts with a backend server to possibly facilitate Plaid integration. Depicting the communication between the mobile app and server is crucial.
- Where applicable, illustrate the flow between different API endpoints (for authentication, transactions, OAuth processing, webhooks) and the subsequent handling (like routing to banks, users, tokens, etc. in the transactions sample).

##### Architectural Patterns & Design Principles
- The pattern here is somewhat modular; each sample follows a clear separation of concerns by having distinct client and server parts.
- In the transactions sample, for example, the server code is organized into routes (banks, tokens, debug, transactions, users). This aligns with a RESTful API style.
- For the iOS application, note the MVC-like separation in Swift (delegates, view controllers, and application lifecycle management).
- The samples also embody a tutorial progression approach, where “start” and “finished” highlight development stages.

##### Elements
- Optionally, include annotations for environment configurations (e.g., references to .env templates) that explain runtime details.

##### Putting It All Together
- Interactions like client → server → external service (Plaid API) and any internal routing/logic flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Repo["Tutorial Resources Repository"]:::repo
    Config["Configuration & Environment"]:::config
    X_Plaid["External Plaid API Service"]:::external

    %% Auth Sample Subgraph
    subgraph "Auth Sample"
        A_Client["Web Client (HTML/JS)"]:::client
        A_Server["Node Server"]:::server
        A_Data["Sample Data (User Files)"]:::data
    end

    %% Transactions Sample Subgraph
    subgraph "Transactions Sample"
        T_Client["Web Client (HTML/JS)"]:::client
        T_Server["Node Server"]:::server
        T_Data["Sample Data (Database & Test Data)"]:::data
    end

    %% Vanilla JS OAuth Sample Subgraph
    subgraph "Vanilla JS OAuth Sample"
        V_Client["Web Client (HTML/JS)"]:::client
        V_Server["Node Server"]:::server
    end

    %% Webhooks Sample Subgraph
    subgraph "Webhooks Sample"
        W_Client["Web Client (HTML/JS)"]:::client
        W_Server["Node Server"]:::server
    end

    %% iOS Sample Subgraph
    subgraph "iOS Sample"
        IOS_Client["iOS Native Client"]:::client
        IOS_Server["iOS Server Component"]:::server
    end

    %% Connections from Repository to Samples and Configuration
    Repo -->|"initializes"| A_Client
    Repo -->|"initializes"| T_Client
    Repo -->|"initializes"| V_Client
    Repo -->|"initializes"| W_Client
    Repo -->|"initializes"| IOS_Client
    Repo -->|"provides"| Config

    %% Auth Sample Connections
    A_Client -->|"sendsRequest"| A_Server
    A_Server -->|"accesses"| A_Data
    A_Server -->|"calls"| X_Plaid
    Config -->|"configures"| A_Server

    %% Transactions Sample Connections
    T_Client -->|"sendsRequest"| T_Server
    T_Server -->|"accesses"| T_Data
    T_Server -->|"calls"| X_Plaid
    Config -->|"configures"| T_Server

    %% Vanilla JS OAuth Sample Connections
    V_Client -->|"sendsRequest"| V_Server
    V_Server -->|"calls"| X_Plaid
    Config -->|"configures"| V_Server

    %% Webhooks Sample Connections
    W_Client -->|"sendsRequest"| W_Server
    W_Server -->|"calls"| X_Plaid
    Config -->|"configures"| W_Server

    %% iOS Sample Connections
    IOS_Client <-->|"communicates"| IOS_Server
    IOS_Server -->|"calls"| X_Plaid
    Config -->|"configures"| IOS_Server

    %% Click Events for Auth Sample Components
    click A_Client "https://github.com/plaid/tutorial-resources/tree/main/auth/finished/public"
    click A_Server "https://github.com/plaid/tutorial-resources/blob/main/auth/finished/server.js"
    click A_Data "https://github.com/plaid/tutorial-resources/tree/main/auth/finished/user_files"

    %% Click Events for Transactions Sample Components
    click T_Client "https://github.com/plaid/tutorial-resources/tree/main/transactions/finished/public"
    click T_Server "https://github.com/plaid/tutorial-resources/blob/main/transactions/finished/server/server.js"
    click T_Data "https://github.com/plaid/tutorial-resources/tree/main/transactions/finished/database"
    click T_Data "https://github.com/plaid/tutorial-resources/blob/main/transactions/finished/testData.js"

    %% Click Events for Vanilla JS OAuth Sample Components
    click V_Client "https://github.com/plaid/tutorial-resources/tree/main/vanilla-js-oauth/finished/public"
    click V_Server "https://github.com/plaid/tutorial-resources/blob/main/vanilla-js-oauth/finished/server.js"

    %% Click Events for Webhooks Sample Components
    click W_Client "https://github.com/plaid/tutorial-resources/tree/main/webhooks/finished/public"
    click W_Server "https://github.com/plaid/tutorial-resources/blob/main/webhooks/finished/server.js"

    %% Click Events for iOS Sample Components
    click IOS_Client "https://github.com/plaid/tutorial-resources/tree/main/ios-swift/finished/client/SamplePlaidClient"
    click IOS_Server "https://github.com/plaid/tutorial-resources/blob/main/ios-swift/finished/server/server.js"

    %% Click Events for Configuration Files
    click Config "https://github.com/plaid/tutorial-resources/blob/main/auth/finished/.env.template"
    click Config "https://github.com/plaid/tutorial-resources/blob/main/transactions/finished/package.json"
    click Config "https://github.com/plaid/tutorial-resources/blob/main/vanilla-js-oauth/finished/.env.example"
    click Config "https://github.com/plaid/tutorial-resources/blob/main/webhooks/finished/.env.template"
    click Config "https://github.com/plaid/tutorial-resources/blob/main/ios-swift/finished/server/.env.template"

    %% Class Definitions
    classDef client fill:#bbf,stroke:#333,stroke-width:2px;
    classDef server fill:#fb6,stroke:#333,stroke-width:2px;
    classDef data fill:#afa,stroke:#333,stroke-width:2px;
    classDef config fill:#ddd,stroke:#333,stroke-width:2px;
    classDef external fill:#f88,stroke:#333,stroke-width:2px;
    classDef repo fill:#ccc,stroke:#333,stroke-width:2px;
```
