# osmosis-labs/osmosis-frontend architecture

> Architecture diagram of the GitHub repository osmosis-labs/osmosis-frontend, 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/osmosis-labs/osmosis-frontend
- Repository: https://github.com/osmosis-labs/osmosis-frontend

## Overview

##### Main Components and Layers
- Frontend Web Application (“packages/web”): This is the Next.js/React application that provides the UI. It contains components, pages, hooks, integrations, styling (via Tailwind CSS), localization files, and various utilities for user interaction and presentation.
- Server/API and tRPC Layer (“packages/server” and “packages/trpc”): These packages expose backend APIs and business logic that power data queries (for instance, blockchain queries, transaction handling, and routing). The transition from Keplr’s architecture to a tRPC-driven structure suggests an evolution towards more efficient, typed, and maintainable API communication.
- Shared Libraries and Business Logic: Multiple packages (e.g., “packages/bridge”, “packages/math”, “packages/pools”, “packages/tx”, “packages/keplr-hooks”, “packages/keplr-stores”, “packages/stores”, “packages/utils”, and “packages/types”) encapsulate domain-specific logic such as bridging between chains, calculations for swaps/pools, transaction processing, and data storage. Represent these as service components that the UI and API layers call upon.
- Proto-codecs: This package handles protocol buffer files and code generation. It abstracts primitive messaging and data transformations for interacting with blockchain modules.

##### Interactions and Data Flow
- The user interacts with the front-end (Next.js app) which communicates with backend endpoints (via TRPC) to fetch live data (asset pricing, exchange rates, IBC transfer status, etc.).
- The frontend components invoke various shared utilities and hooks (for instance, asset conversion, wallet interactions, localization, and state management) that depend on business logic maintained in other packages.
- The server/APIs query external blockchain nodes (via IBC modules or REST endpoints provided by Osmosis) and external services (such as Coingecko for market data). This data flows back to the frontend through the TRPC layer.
- Build and deployment responsibilities are managed by Turbo Repo and Lerna, which handle script execution (for caching, build artifacts, and publishing) and ensure consistency across packages.

##### Key Architectural Patterns and Design Principles
- Modular Monorepo: The use of packages enables separation of concerns, which allows each library (UI components, logic, utilities, API layers, etc.) to be maintained independently and then composed into the final application.
- Typed and Component-Based Design: Adoption of TypeScript throughout and a heavy reliance on React functional components enforce a strongly typed, component-driven paradigm for building UIs.
- API Abstraction and tRPC: The refactoring from a Keplr-specific architecture to a tRPC stack makes the API layer more streamlined, with the benefits of seamless type sharing between backend and frontend.
- CI/CD & Build Optimization: With a combination of Turbo Repo (with remote caching) and Vercel deployment (with CloudFlare in front), the repo is designed for fast, incremental builds and deployments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        FE["Frontend Web Application (Next.js/React)"]:::ui
    end

    subgraph "API Layer"
        API["Server/API Layer"]:::api
        TRPC["tRPC Communication"]:::api
    end

    subgraph "Shared Libraries"
        BRIDGE["Bridge Service"]:::shared
        MATH["Math Library"]:::shared
        POOLS["Pools Service"]:::shared
        TX["Transaction Service"]:::shared
        KEPLR_HOOKS["Keplr Hooks"]:::shared
        KEPLR_STORES["Keplr Stores"]:::shared
        STORES["Stores Service"]:::shared
        UTILS["Utilities"]:::shared
        TYPES["Types Library"]:::shared
    end

    subgraph "Proto-codecs"
        PROTO["Proto-codecs Module"]:::shared
    end

    subgraph "External Data Sources"
        BC["Blockchain Nodes"]:::external
        CG["Coingecko API"]:::external
    end

    subgraph "Infrastructure & Deployment"
        TURBO["Turbo Repo"]:::infra
        LERNA["Lerna"]:::infra
        VERCEL["Vercel"]:::infra
        CLOUDFLARE["CloudFlare"]:::infra
    end

    %% Interactions and Data Flow
    FE -->|"calls"| TRPC
    TRPC -->|"invokes"| API
    TRPC -->|"uses_bridge"| BRIDGE
    TRPC -->|"uses_math"| MATH
    TRPC -->|"handles_pools"| POOLS
    TRPC -->|"processes_tx"| TX
    TRPC -->|"triggers_hooks"| KEPLR_HOOKS
    TRPC -->|"updates_stores"| KEPLR_STORES
    TRPC -->|"manages_state"| STORES
    TRPC -->|"utilizes"| UTILS
    TRPC -->|"verifies_types"| TYPES

    API -->|"queries"| BC
    API -->|"fetches_data"| CG

    %% Infrastructure Connections (dashed for build/deployment processes)
    TURBO ---|"builds"| FE
    TURBO ---|"builds"| API
    LERNA ---|"manages"| FE
    LERNA ---|"manages"| API
    VERCEL ---|"deploys"| FE
    CLOUDFLARE ---|"CDN_for"| VERCEL

    %% Click Events for Component Mapping (paths are hidden from diagram labels)
    click FE "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/web"
    click API "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/server"
    click TRPC "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/trpc"
    click BRIDGE "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/bridge"
    click MATH "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/math"
    click POOLS "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/pools"
    click TX "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/tx"
    click KEPLR_HOOKS "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/keplr-hooks"
    click KEPLR_STORES "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/keplr-stores"
    click STORES "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/stores"
    click UTILS "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/utils"
    click TYPES "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/types"
    click PROTO "https://github.com/osmosis-labs/osmosis-frontend/tree/stage/packages/proto-codecs"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef api fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef shared fill:#FFFACD,stroke:#000,stroke-width:2px;
    classDef external fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
