# copilotkit/demo-banking architecture

> Architecture diagram of the GitHub repository copilotkit/demo-banking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/copilotkit/demo-banking
- Repository: https://github.com/copilotkit/demo-banking

## Overview

##### Main Components
- Frontend UI and Pages:
- The Next.js app structure under the “src/app” directory contains entry points (e.g., page.tsx, layout.tsx) and feature-specific pages (e.g., /cards, /team, /sql) that represent the various user interfaces.
- The “components” directory houses reusable UI components, including both functional elements (dialogs, buttons, inputs, etc.) and feature-specific ones (e.g., credit card details, transactions list).
- The application-wide contexts for authorization and co-pilot behavior are implemented in components like “copilot-context.tsx” and “auth-context.tsx” along with hooks (e.g., use-toast).

- Backend API Endpoints:
- Under “src/app/api”, you have different API routes grouped by version (“v1”) and functionality (cards, policies, transactions, users, and copilotkit). These endpoints serve data and process actions (like changing a card’s PIN or approving transactions), interfacing with the hardcoded data in “data.ts”.
- The routing tree (e.g., nested directories for card details and actions) indicates a RESTful API design with parameterized routes (e.g., /cards/[id]) that facilitate granular data operations.

- External Integrations and Configuration:
- The README emphasizes that the app integrates with OpenAI (via an API key) to enable generative UI features and chat-driven capabilities. Mark the integration point towards OpenAI’s API.
- The project configuration files (next.config.mjs, tailwind.config.ts, tsconfig.json) and dependency files (package.json, pnpm-lock.yaml, package-lock.json) reflect a modern frontend stack that combines Next.js, Tailwind CSS, and TypeScript.

##### Relationships and Data Flow
- Frontend Interaction with Backend:
- How the UI pages (e.g., /cards, /team, /sql) connect with the corresponding API endpoints (e.g., /api/v1/cards, /api/v1/users, /api/v1/transactions) via HTTP requests.
- Context Providers and Hooks:
- That the “copilot-context” component sits at an application level, wrapping UI components and providing functionalities (authorization, action triggering) via custom hooks (useCopilotAction, useCopilotReadable).
- OpenAI Integration:

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- The clear separation between API endpoints (back-end logic) and UI pages/components (front-end rendering) demonstrates a decoupled architecture.
- RESTful Routing:
- The API structure uses RESTful endpoints with nested parameters (e.g., /cards/[id], /transactions/[id]), implying focus on modularity and scalability.
- Context-based State Management:
- The use of wrappers and context providers (via “copilot-context.tsx” and “auth-context.tsx”) indicates dependency injection for handling global state like user roles, authorization, and generative actions.

##### Technologies, Frameworks, and Libraries
- Next.js and React underpin the UI layer.
- Tailwind CSS for styling (see tailwind.config.ts and global CSS files).
- TypeScript for improved type safety (note tsconfig.json and next-env.d.ts).
- ESLint configuration ensures consistency (configurations via .eslintrc.json).
- OpenAI as an external service for generative functionalities.

##### Final Steps
- Draft a high-level overview first, then add details such as nested API routes and internal component interactions.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Section
    subgraph "Frontend"
        %% Pages Subgraph
        subgraph "Pages"
            mainPage["Main Page"]
            layoutPage["Layout Page"]
            cardsPage["Cards Page"]
            teamPage["Team Page"]
            sqlPage["SQL Generator Page"]
        end
        %% UI Components Subgraph
        subgraph "UI Components"
            generalUI["General UI Components"]
            subgraph "Feature-specific Components"
                creditCardDetails["Credit Card Details"]
                codeSnippet["Code Snippet"]
                transactionsList["Transactions List"]
                addCardDropdown["Add Card Dropdown"]
                addOrEditMember["Add/Edit Member Dialog"]
                changePin["Change PIN Dialog"]
                removeMember["Remove Member Dialog"]
            end
        end
        %% Contexts & Hooks Subgraph
        subgraph "Contexts & Hooks"
            authContext["Authorization Context"]
            copilotContext["Copilot Context"]
            useToast["use-toast Hook"]
        end
    end

    %% Backend Section
    subgraph "Backend"
        subgraph "API Endpoints"
            cardsAPIList["Cards API (List)"]
            cardDetailAPI["Card Detail API"]
            cardPolicyAPI["Card Policy API"]
            policiesAPI["Policies API"]
            transactionsAPIList["Transactions API (List)"]
            transactionDetailAPI["Transaction Detail API"]
            usersAPIList["Users API (List)"]
            userDetailAPI["User Detail API"]
            copilotKitAPI["CopilotKit API"]
        end
        dataSource["Data Source (data.ts)"]
    end

    %% External Integrations and Configurations
    subgraph "External & Configurations"
        openai["OpenAI Integration"]
        subgraph "Configurations"
            configNext["next.config.mjs"]
            tailwind["tailwind.config.ts"]
            tsConfig["tsconfig.json"]
            pkg["package.json"]
            pnpmLock["pnpm-lock.yaml"]
            packageLock["package-lock.json"]
        end
    end

    %% Connections between Frontend Pages and Backend APIs
    cardsPage -->|"HTTP_GET/POST"| cardsAPIList
    teamPage  -->|"HTTP_GET/POST"| usersAPIList
    sqlPage   -->|"HTTP_GET/POST"| transactionsAPIList

    %% Connections from Main Pages to Contexts
    mainPage -->|"provides"| authContext
    mainPage -->|"provides"| copilotContext

    %% Interaction from Feature-specific Components to Copilot Context
    creditCardDetails -->|"triggers"| copilotContext

    %% Copilot Context calls External OpenAI Integration
    copilotContext -->|"GenerativeCall"| openai

    %% API Endpoints use Data Source
    cardsAPIList -->|"reads_from"| dataSource
    cardDetailAPI -->|"reads_from"| dataSource
    cardPolicyAPI -->|"reads_from"| dataSource
    policiesAPI   -->|"reads_from"| dataSource
    transactionsAPIList -->|"reads_from"| dataSource
    transactionDetailAPI -->|"reads_from"| dataSource
    usersAPIList  -->|"reads_from"| dataSource
    userDetailAPI -->|"reads_from"| dataSource

    %% Styling Classes
    class mainPage,layoutPage,cardsPage,teamPage,sqlPage,generalUI,creditCardDetails,codeSnippet,transactionsList,addCardDropdown,addOrEditMember,changePin,removeMember,authContext,copilotContext,useToast frontendStyle
    class cardsAPIList,cardDetailAPI,cardPolicyAPI,policiesAPI,transactionsAPIList,transactionDetailAPI,usersAPIList,userDetailAPI,copilotKitAPI,dataSource backendStyle
    class openai,configNext,tailwind,tsConfig,pkg,pnpmLock,packageLock configStyle

%% Click Events for Frontend Pages
click mainPage "https://github.com/copilotkit/demo-banking/blob/main/src/app/page.tsx"
click layoutPage "https://github.com/copilotkit/demo-banking/blob/main/src/app/layout.tsx"
click cardsPage "https://github.com/copilotkit/demo-banking/blob/main/src/app/cards/page.tsx"
click teamPage "https://github.com/copilotkit/demo-banking/blob/main/src/app/team/page.tsx"
click sqlPage "https://github.com/copilotkit/demo-banking/blob/main/src/app/sql/page.tsx"

%% Click Events for Reusable UI Components
click generalUI "https://github.com/copilotkit/demo-banking/tree/main/src/components/ui"
click creditCardDetails "https://github.com/copilotkit/demo-banking/blob/main/src/components/credit-card-details.tsx"
click codeSnippet "https://github.com/copilotkit/demo-banking/blob/main/src/components/code-snippet.tsx"
click transactionsList "https://github.com/copilotkit/demo-banking/blob/main/src/components/transactions-list.tsx"
click addCardDropdown "https://github.com/copilotkit/demo-banking/blob/main/src/components/add-card-dropdown.tsx"
click addOrEditMember "https://github.com/copilotkit/demo-banking/blob/main/src/components/add-or-edit-member-dialog.tsx"
click changePin "https://github.com/copilotkit/demo-banking/blob/main/src/components/change-pin-dialog.tsx"
click removeMember "https://github.com/copilotkit/demo-banking/blob/main/src/components/remove-member-dialog.tsx"

%% Click Events for Context Providers & Hooks
click authContext "https://github.com/copilotkit/demo-banking/blob/main/src/components/auth-context.tsx"
click copilotContext "https://github.com/copilotkit/demo-banking/blob/main/src/components/copilot-context.tsx"
click useToast "https://github.com/copilotkit/demo-banking/blob/main/src/hooks/use-toast.ts"

%% Click Events for Backend API Endpoints
click cardsAPIList "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/cards/route.ts"
click cardDetailAPI "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/cards/[id]/route.ts"
click cardPolicyAPI "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/cards/[id]/policy/route.ts"
click policiesAPI "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/policies/route.ts"
click transactionsAPIList "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/transactions/route.ts"
click transactionDetailAPI "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/transactions/[id]/route.ts"
click usersAPIList "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/users/route.ts"
click userDetailAPI "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/users/[id]/route.ts"
click copilotKitAPI "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/copilotkit/route.ts"
click dataSource "https://github.com/copilotkit/demo-banking/blob/main/src/app/api/v1/data.ts"

%% Click Events for Configuration Files
click configNext "https://github.com/copilotkit/demo-banking/blob/main/next.config.mjs"
click tailwind "https://github.com/copilotkit/demo-banking/blob/main/tailwind.config.ts"
click tsConfig "https://github.com/copilotkit/demo-banking/blob/main/tsconfig.json"
click pkg "https://github.com/copilotkit/demo-banking/blob/main/package.json"
click pnpmLock "https://github.com/copilotkit/demo-banking/blob/main/pnpm-lock.yaml"
click packageLock "https://github.com/copilotkit/demo-banking/blob/main/package-lock.json"

%% Class Definitions for Colors
classDef frontendStyle fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
classDef backendStyle fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
classDef configStyle fill:#FFE082,stroke:#FF6F00,stroke-width:2px;
```
