# astraly-labs/pragma architecture

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

- Interactive diagram: https://gitdiagram.com/astraly-labs/pragma
- Repository: https://github.com/astraly-labs/pragma

## Overview

##### Project type and purpose
- This is primarily a Next.js‑based frontend and minimal backend (API routes) for the “Pragma” provable oracle ecosystem.
- It serves both a marketing site (static pages) and a dashboard (dynamic, data‑driven UI) that interacts with Starknet contracts and event streams.

##### File structure
- Top‑level:
- README.md, LICENSE, .gitignore – project metadata
- `assets/`, `components/`, `path/` – legacy or shared helper code
- `pragma-ui/` – the real Next.js application
- Inside `pragma-ui/`:
- `pages/` – React pages and API routes (`pages/api/...`)
- `src/app/` – Next.js App Router directory with `(marketing)` and `(dashboard)` sections
- `src/components/`, `src/hooks/`, `src/lib/`, `src/services/`, `src/providers/` – UI components, utilities, data-fetching hooks, service abstractions
- `src/abi/` – contract ABIs (ERC20, Oracle, etc.) for on‑chain calls
- `public/assets/` – static Lottie JSON, videos, images
- Config files – `package.json`, `tsconfig.json`, `tailwind.config.ts`

##### README for additional insights
- Describes “Pragma” as a modular provable oracle built on Starknet
- Mentions related repos (contracts, indexer, SDK) – this repo is just the UI

##### Final advice
- Every logical layer without overcrowding: client, framework, services, blockchain, assets.
- Data flow paths (SSR, CSR, SSE, JSON‑RPC).
- Review pages vs. App Router to distinguish static vs. dynamic routes.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Browser (React UI)"]:::client
    end

    %% Next.js Application
    subgraph "Next.js Application" 
        direction TB
        NextApp["Application Root: pragma-ui/"]:::server
        subgraph "App Router"
            direction TB
            Marketing["Marketing Pages (SSG)"]:::static
            Dashboard["Dashboard Pages (SSR/ISR/Streaming)"]:::dynamic
        end
        subgraph "Pages Router (Legacy)"
            direction TB
            CustomApp["_app.tsx & _document.tsx"]:::server
            Page404["404 Page"]:::server
            Request["request.tsx"]:::server
        end
    end

    %% API Routes
    subgraph "API Routes (Serverless Functions)" 
        direction TB
        Assertions["Assertions API [id]"]:::api
        AuthToken["Auth Token API"]:::api
        OnchainProxy["On-chain Proxy API"]:::api
        StreamAPI["Streaming SSE API"]:::api
        TokensAPI["Tokens Management API"]:::api
    end

    %% Data-access Layer
    subgraph "Data-access Layer"
        direction TB
        subgraph Services
            direction TB
            WalletSvc["Wallet Service"]:::service
            AddressSvc["Address Service"]:::service
            StatusSvc["Starknet Status Service"]:::service
        end
        subgraph Utilities & Endpoints
            direction TB
            EventStream["RPC & Event-Stream Helpers"]:::service
            Endpoints["API Endpoints Definitions"]:::service
            ConfigConsts["Config & Constants"]:::service
        end
        Hooks["React Hooks (oracle, streaming)"]:::service
        Providers["Context Providers"]:::service
        StarknetProv["StarknetProvider Component"]:::service
        Components["Shared UI Components"]:::service
    end

    %% On-chain ABIs
    subgraph "On-chain Contracts ABIs"
        direction TB
        ABIs["Oracle.json, ERC20.json, Ancillary.json, OO.json"]:::external
    end

    %% Static Assets
    subgraph "Static Assets & Lottie"
        direction TB
        Assets["public/assets/"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        JSONRPC["Starknet JSON-RPC Node(s)"]:::external
        Indexer["Pragma Indexer Service"]:::external
        CDN["IPFS/CDN"]:::external
    end

    %% Connections
    Browser -->|"renders"| Marketing
    Browser -->|"renders"| Dashboard
    Browser -->|"navigates to legacy pages"| CustomApp
    Marketing -->|SSR/SSG| NextApp
    Dashboard -->|SSR/ISR/Streaming| NextApp
    CustomApp -->|SSR| NextApp
    NextApp -->|calls| Assertions
    NextApp -->|calls| AuthToken
    NextApp -->|calls| OnchainProxy
    NextApp -->|calls| StreamAPI
    NextApp -->|calls| TokensAPI

    Assertions -->|uses| Services
    AuthToken -->|uses| Services
    OnchainProxy -->|uses| Services
    StreamAPI -->|uses| EventStream
    TokensAPI -->|uses| Services

    Services -->|invokes| JSONRPC
    Services -->|invokes| Indexer
    EventStream -->|EventSource/SSE| Browser

    Hooks -->|calls| JSONRPC
    Hooks -->|calls| Indexer

    Providers -->|wraps| Browser
    StarknetProv -->|provides context| Browser

    Components -->|rendered by| Browser

    ABIs -->|loaded by| Services
    Assets -->|served by| CDN

    JSONRPC -->|interacts with| ABIs

    %% Click Events
    click NextApp "https://github.com/astraly-labs/pragma/tree/master/pragma-ui/"
    click Marketing "https://github.com/astraly-labs/pragma/tree/master/pragma-ui/src/app/(marketing)/"
    click Dashboard "https://github.com/astraly-labs/pragma/tree/master/pragma-ui/src/app/(dashboard)/"
    click Assertions "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/pages/api/assertions/[id].ts"
    click AuthToken "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/pages/api/auth/token.ts"
    click OnchainProxy "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/pages/api/onchain.ts"
    click StreamAPI "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/pages/api/stream.ts"
    click TokensAPI "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/pages/api/tokens/add.ts"
    click WalletSvc "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/services/wallet.service.ts"
    click AddressSvc "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/services/address.service.ts"
    click StatusSvc "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/services/starknetStatus.service.ts"
    click EventStream "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/lib/get-event-stream.tsx"
    click Endpoints "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/lib/endpoints.ts"
    click ConfigConsts "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/lib/config.ts"
    click ConfigConsts "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/lib/constants.ts"
    click ABIs "https://github.com/astraly-labs/pragma/tree/master/pragma-ui/src/abi/"
    click Assets "https://github.com/astraly-labs/pragma/tree/master/pragma-ui/public/assets/"
    click Hooks "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/hooks/oracle.ts"
    click Providers "https://github.com/astraly-labs/pragma/tree/master/pragma-ui/src/providers/"
    click StarknetProv "https://github.com/astraly-labs/pragma/blob/master/pragma-ui/src/components/Provider/StarknetProvider.tsx"
    click Components "https://github.com/astraly-labs/pragma/tree/master/pragma-ui/src/components/"

    %% Styles
    classDef client fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px
    classDef server fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px
    classDef static fill:#E3F2FD,stroke:#0D47A1,stroke-width:2px
    classDef dynamic fill:#DCEDC8,stroke:#1B5E20,stroke-width:2px
    classDef api fill:#FFE0B2,stroke:#E65100,stroke-width:2px
    classDef service fill:#FFF9C4,stroke:#F57F17,stroke-width:2px
    classDef external fill:#ECEFF1,stroke:#455A64,stroke-width:2px
```
