# calpa/orbitgo architecture

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

- Interactive diagram: https://gitdiagram.com/calpa/orbitgo
- Repository: https://github.com/calpa/orbitgo

## Overview

##### Main system components
- Frontend: This is the core React + TypeScript application that handles UI, routing, state management, Web3 integration, and manages real-time updates.
- Backend Integration: Cloudflare Workers act as the permissionless API, exposing endpoints for token data and webhook management. This also includes key aspects like caching, rate limiting, CORS, and error handling.
- Features/Services: Specific components such as the token terminal for portfolio tracking, advanced analytics (charts, data grid), and detailed webhook management (creation, monitoring, and multi-address support).
- Supported Networks: Represent the various blockchain networks (Ethereum, Arbitrum, Base, Kaia, Optimism, Polygon) from which token balances and protocol data are fetched.

##### File structure to extract further details
- The “src” folder contains key directories:
– components: Contains reusable UI pieces (e.g., BalanceCard, Navbar, Sidebar, and specialized webhook components).
– routes: Organized views and pages following a route hierarchy (dashboard, about, notifications). This emphasizes the separation of concerns and routing logic.
– utils and constants: Hold all configuration constants (e.g., chains.json, networks.ts) and utility functions (e.g., format.ts, coins utilities) that are critical for managing chain and token data.
– services and store: Responsible for handling the API calls (portfolio.ts, transactions.ts) and application state (Jotai atoms, TanStack Query integration).
- Configuration files like tsconfig, vite.config, and eslint configurations guarantee uniform development standards.

##### Summarize architectural patterns and technologies
- Architectural Pattern: The project uses a typical full-stack separation where the frontend operates independently from backend APIs. There is a clear division between concerns through dedicated directories (components, routes, store, types).
- Technologies: React (UI), TypeScript (strong typing), Vite (build tool), TailwindCSS (styling), TanStack Query & Jotai (state & data management), and web3 integrations with wagmi and RainbowKit.
- Routing is managed via TanStack Router, allowing modular and logical UI navigation.
- API Integration: Clearly defined endpoints in the README (for tokens and webhooks) mean that the frontend communicates with Cloudflare Workers, ensuring secure and efficient data retrieval.

##### Instructing the principal software engineer
- Be as detailed as possible: for every component, indicate its role and any dependencies (e.g., “UI Components” rely on TailwindCSS for styling and Framer Motion for animations; API interactions are managed via axios calls in src/axios.ts).
- Use standardized notation to mark internal modules (e.g., routers, stores, utilities) and external integrations (web3 wallet connectors).

Happy diagramming!

## Diagram (Mermaid)

```mermaid
graph TD
    User["User"]:::userclass

    subgraph "Frontend (React + TypeScript)"
        F_Main["React + TypeScript App<br/>(src/main.tsx)"]:::frontend
        F_Components["UI Components<br/>(src/components)"]:::frontend
        F_Routes["Routing<br/>(src/routes)"]:::frontend
        F_State["State Management<br/>(src/store & src/atoms)"]:::frontend
        F_Web3["Web3 Integration<br/>(wagmi, RainbowKit)"]:::frontend
    end

    subgraph "Backend Integration (Cloudflare Workers)"
        API1["Token API<br/>(API.md & BackendREADME.md)"]:::backend
        WebhookAPI["Webhook API<br/>(src/api/webhooks.ts)"]:::backend
        NoteBackend["Auxiliary Features<br/>(Caching,RateLimiting,CORS)"]:::backend
    end

    subgraph "Features/Services"
        TokenTerminal["Token Terminal & Portfolio Tracking"]:::features
        AdvancedAnalytics["Advanced Analytics<br/>(charts & data grids)"]:::features
        WebhookManagement["Webhook Management"]:::features
    end

    subgraph "Supported Networks"
        Networks["Blockchain Networks:<br/>Ethereum,Arbitrum,Base,Kaia,Optimism,Polygon"]:::networks
    end

    %% Connections
    User -->|"initiates"| F_Main

    F_Main -->|"API call"| API1
    F_Main -->|"Webhook call"| WebhookAPI
    API1 -->|"data response"| F_Main
    WebhookAPI -->|"data response"| F_Main

    F_Main -->|"renders"| TokenTerminal
    F_Main -->|"renders"| AdvancedAnalytics
    F_Main -->|"manages"| WebhookManagement
    F_Main -->|"integrates"| Networks

    %% Optional internal flow within Frontend
    F_Main --> F_Components
    F_Main --> F_Routes
    F_Main --> F_State
    F_Main --> F_Web3

    %% Backend internal note connection
    API1 --- NoteBackend
    WebhookAPI --- NoteBackend

    %% Click Events for Frontend
    click F_Main "https://github.com/calpa/orbitgo/blob/main/src/main.tsx"
    click F_Components "https://github.com/calpa/orbitgo/tree/main/src/components"
    click F_Routes "https://github.com/calpa/orbitgo/tree/main/src/routes"
    click F_State "https://github.com/calpa/orbitgo/tree/main/src/atoms"
    
    %% Click Events for Backend Integration
    click API1 "https://github.com/calpa/orbitgo/blob/main/API.md"
    click API1 "https://github.com/calpa/orbitgo/blob/main/BackendREADME.md"
    click WebhookAPI "https://github.com/calpa/orbitgo/blob/main/src/api/webhooks.ts"
    
    %% Click Events for Token Terminal Feature
    click TokenTerminal "https://github.com/calpa/orbitgo/blob/main/src/components/PortfolioDetails.tsx"
    click TokenTerminal "https://github.com/calpa/orbitgo/blob/main/src/atoms/portfolio.ts"
    click TokenTerminal "https://github.com/calpa/orbitgo/blob/main/src/services/portfolio.ts"

    %% Click Events for Advanced Analytics Feature
    click AdvancedAnalytics "https://github.com/calpa/orbitgo/blob/main/src/components/ProtocolAllocationChart.tsx"
    click AdvancedAnalytics "https://github.com/calpa/orbitgo/blob/main/src/components/TransactionChart.tsx"
    click AdvancedAnalytics "https://github.com/calpa/orbitgo/blob/main/src/components/TransactionTable.tsx"
    click AdvancedAnalytics "https://github.com/calpa/orbitgo/blob/main/src/components/ValueChart.tsx"
    click AdvancedAnalytics "https://github.com/calpa/orbitgo/blob/main/src/components/Stats.tsx"

    %% Click Events for Webhook Management Feature
    click WebhookManagement "https://github.com/calpa/orbitgo/tree/main/src/components/webhooks"
    click WebhookManagement "https://github.com/calpa/orbitgo/tree/main/src/routes/dashboard/notifications"

    %% Click Events for Supported Networks
    click Networks "https://github.com/calpa/orbitgo/blob/main/src/constants/chains.json"
    click Networks "https://github.com/calpa/orbitgo/blob/main/src/constants/networks.ts"
    click Networks "https://github.com/calpa/orbitgo/blob/main/src/constants/chains.ts"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFE45E,stroke:#000,stroke-width:2px;
    classDef features fill:#C1F7C9,stroke:#000,stroke-width:2px;
    classDef networks fill:#F7C1C1,stroke:#000,stroke-width:2px;
    classDef userclass fill:#D3BFF9,stroke:#000,stroke-width:2px;
```
