# robertalv/convex-panel architecture

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

- Interactive diagram: https://gitdiagram.com/robertalv/convex-panel
- Repository: https://github.com/robertalv/convex-panel

## Overview

##### Project Type and Purpose
- Project Type: A React component library (with Next.js support) for monitoring and debugging Convex applications.
- Purpose: To display real-time logs, data, and function performance, and to allow in-place data editing via a development panel integrated with a Convex backend.

##### Main Components
- UI Components and Layout:
- ConvexPanel: The central panel component that integrates the functionalities.
- Container, ErrorBoundary: Manage and isolate different portions of the UI.
- Modular UI parts such as components for logs (e.g., LogsContainer, LogRow, LogsTable), data tables (DataTable, DataTableContent), health monitoring (HealthContainer, SchedulerStatus, various charts), function management (FileTree, FunctionsView, FunctionContent), code inspection (MonacoEditor), and settings (SettingsModal).
- Context and Hooks:
- React Context (deploymentContext) for handling state across module components.
- Custom hooks (like useFilters, useNents, useTableData) to manage data fetching and state.
- Dev Tools and Debugging:
- DevTools components (DevToolsContainer, JsonView, network panels) that facilitate deeper analysis and debugging.
- Utility Modules:
- Functions in src/utils (API calls, mocks, function type labels, etc.) that power the business logic.
- External Integration:
- ConvexReactClient: The integration point for connecting to the Convex backend.
- Environment configuration management (via .env and automatic token setup during installation).

##### Relationships and Interactions
- UI Layer Interaction: The ConvexPanel component acts as a container that assembles different modules (logs view, data tables, health monitoring, function panels). It receives props (access token, deploy key/URL, and the Convex client) that drive its interactions.
- Data Flow:
- The ConvexReactClient is instantiated by the hosting application and passed as a prop to ConvexPanel, thereby serving as the bridge to the Convex backend.
- Various components (logs, data, functions) fetch, display, and process data by leveraging shared hooks and API utilities.
- Context Sharing: A context provider (deploymentContext) wraps parts of the component tree so that deep nested components (e.g., in data or devtools directories) can share state and configuration.
- Error Handling: The ErrorBoundary component ensures that failures in one area of the UI do not break the whole panel, and errors can propagate back to the user through designated displays.

##### Highlighting Architectural Patterns and Design Principles
- Component-Based Architecture: The project is modular and split into many focused React components organized by domain (data, functions, logs, health).
- Separation of Concerns: Each directory (like “data”, “devtools”, “logs”, “functions”, “health”) encapsulates a specific domain’s functionality.
- Reusability: Shared hooks, contexts, and utility functions promote a DRY approach.
- Integration with External Services: The setup for automatic token configuration and Convex client instantiation shows a clear design for integrating external authentication and data sources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global configuration
    TR("Token Retrieval (.env)"):::config

    %% Frontend UI Layer
    subgraph "Frontend UI"
        CT("Container"):::ui
        EB("ErrorBoundary"):::ui
        CP("ConvexPanel"):::ui
    end

    %% Connect configuration to UI layer
    TR -->|"configures"| CT
    CT -->|"wraps"| EB
    EB -->|"renders"| CP

    %% Logs Module Subgraph
    subgraph "Logs Module"
        LC("LogsContainer"):::module
        LT("LogsTable"):::module
        LR("LogRow"):::module
    end
    LC -->|"table_component"| LT
    LT -->|"row_component"| LR

    %% Data Module
    DT("DataTable"):::module

    %% Health Monitoring Module
    HC("HealthContainer"):::module

    %% Functions Module Subgraph
    subgraph "Functions Module"
        FT("FileTree"):::module
        FV("FunctionsView"):::module
        FC("FunctionContent"):::module
        DS("DirectorySidebar"):::module
        FI("FileItem"):::module
    end
    FT -->|"view"| FV
    FV -->|"content"| FC
    FV -->|"sidebar"| DS
    DS -->|"file_item"| FI

    %% Code Inspection Module
    ME("MonacoEditor"):::module

    %% Settings Module Subgraph
    subgraph "Settings Module"
        SM("SettingsModal"):::module
        SB("SettingsButton"):::module
    end
    SM -->|"button"| SB

    %% DevTools Module Subgraph
    subgraph "DevTools Module"
        DV("DevToolsContainer"):::module
        JV("JsonView"):::module
    end
    DV -->|"json_view"| JV

    %% External Integration
    CR("ConvexReactClient"):::external

    %% Shared State and Hooks
    subgraph "Shared State"
        DC("Deployment Context"):::hook
        CH("Custom Hooks"):::hook
    end

    %% Utilities
    U("Utility Modules"):::util

    %% Connections from ConvexPanel to Modules
    CP -->|"logs_module"| LC
    CP -->|"data_module"| DT
    CP -->|"health_module"| HC
    CP -->|"functions_module"| FT
    CP -->|"code_inspection"| ME
    CP -->|"settings_module"| SM
    CP -->|"devtools_module"| DV
    CP -->|"connects"| CR

    %% Shared state integration
    DC -->|"provides_state"| CP
    CH -->|"manages_data"| CP

    %% Utility usage
    U -->|"utilized_by"| CP

    %% Styles
    classDef config fill:#FFE0B2,stroke:#EF6C00,stroke-width:2px;
    classDef ui fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef module fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef hook fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef external fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef util fill:#FFCDD2,stroke:#C62828,stroke-width:2px;

    %% Click Events
    click CP "https://github.com/robertalv/convex-panel/blob/main/src/ConvexPanel.tsx"
    click CT "https://github.com/robertalv/convex-panel/blob/main/src/Container.tsx"
    click EB "https://github.com/robertalv/convex-panel/blob/main/src/ErrorBoundary.tsx"
    click LC "https://github.com/robertalv/convex-panel/blob/main/src/logs/LogsContainer.tsx"
    click LT "https://github.com/robertalv/convex-panel/blob/main/src/logs/components/LogsTable.tsx"
    click LR "https://github.com/robertalv/convex-panel/blob/main/src/logs/components/LogRow.tsx"
    click DT "https://github.com/robertalv/convex-panel/blob/main/src/data/DataTable.tsx"
    click HC "https://github.com/robertalv/convex-panel/blob/main/src/health/HealthContainer.tsx"
    click FT "https://github.com/robertalv/convex-panel/blob/main/src/functions/FileTree.tsx"
    click FV "https://github.com/robertalv/convex-panel/blob/main/src/functions/FunctionsView.tsx"
    click FC "https://github.com/robertalv/convex-panel/blob/main/src/functions/FunctionContent.tsx"
    click DS "https://github.com/robertalv/convex-panel/blob/main/src/functions/DirectorySidebar.tsx"
    click FI "https://github.com/robertalv/convex-panel/blob/main/src/functions/FileItem.tsx"
    click ME "https://github.com/robertalv/convex-panel/blob/main/src/components/MonacoEditor.tsx"
    click SM "https://github.com/robertalv/convex-panel/blob/main/src/settings/SettingsModal.tsx"
    click SB "https://github.com/robertalv/convex-panel/blob/main/src/settings/SettingsButton.tsx"
    click DC "https://github.com/robertalv/convex-panel/blob/main/src/context/deploymentContext.tsx"
    click CH "https://github.com/robertalv/convex-panel/tree/main/src/hooks"
    click DV "https://github.com/robertalv/convex-panel/blob/main/src/devtools/DevToolsContainer.tsx"
    click JV "https://github.com/robertalv/convex-panel/blob/main/src/devtools/JsonView.tsx"
    click U "https://github.com/robertalv/convex-panel/tree/main/src/utils"
```
