# irislib/iris-client architecture

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

- Interactive diagram: https://gitdiagram.com/irislib/iris-client
- Repository: https://github.com/irislib/iris-client

## Overview

##### Project type and purpose
- This is a single‐page, full‐client social networking/webchat application (“Iris”) built with TypeScript and React (via Vite).
- It ships as a static SPA (index.html + JS/CSS bundles) and communicates at runtime with decentralized back‐ends (Nostr relays, WebRTC peers) and various third‐party embed services.

##### File structure
- Top‐level “src” holds all UI pages and shared components; “public” holds built assets and static files.
- There is no monolithic server code here—build is handled by Vite and served as static content (Dockerfile + docker-compose.yml suggest an Nginx or similar static‐file container).
- “config” contains environment/relay settings; “scripts” and “tests” folders define automation and E2E test suites.
- CI is defined under .github/workflows; Playwright/E2E runs against the deployed static site.

##### README
- Confirms that this is a front‐end client for iris.to, built and tested via Yarn/Vite, and deployed as a static site.
- No internal database or backend service code—runtime data comes from Nostr and WebRTC sessions.

##### Detail
- Major folder or module as a sub‐component (e.g., “Chat module,” “Feed module,” “Embed engine”).
- Caching layer (memcache.ts) and configuration loading.
- Test harness (Playwright) as an external actor that runs against the deployed SPA.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        Developer["Developer"]:::ci
        CI["GitHub Actions CI"]:::ci
        Developer -->|"git push"| CI
        subgraph "Build System"
            Vite["Vite + TS + Tailwind"]:::ci
        end
        CI -->|"runs lint/tests & build"| Vite
        DockerBuild["Docker Build"]:::ci
        Vite -->|"bundle & dockerize"| DockerBuild
    end

    click CI "https://github.com/irislib/iris-client/blob/main/.github/workflows/ci.yml"
    click Vite "https://github.com/irislib/iris-client/blob/main/vite.config.ts"
    click Vite "https://github.com/irislib/iris-client/blob/main/tsconfig.json"
    click Vite "https://github.com/irislib/iris-client/blob/main/tailwind.config.js"
    click Vite "https://github.com/irislib/iris-client/blob/main/postcss.config.js"
    click DockerBuild "https://github.com/irislib/iris-client/tree/main/Dockerfile"
    click DockerBuild "https://github.com/irislib/iris-client/blob/main/docker-compose.yml"

    %% Deployment
    subgraph "Deployment"
        Registry["Container Registry"]:::ci
        CDN["CDN"]:::ci
        StaticServer["Static-File Server (Nginx)"]:::ci
    end

    DockerBuild -->|"push image"| Registry
    Registry -->|"deploy image"| CDN
    CDN -->|"serve static"| StaticServer

    %% Runtime Client
    subgraph "Client Runtime"
        Browser["User's Browser (SPA)"]:::runtime
        click Browser "https://github.com/irislib/iris-client/blob/main/index.html"
        click Browser "https://github.com/irislib/iris-client/blob/main/src/main.tsx"
        click Browser "https://github.com/irislib/iris-client/blob/main/src/index.css"

        Config["Config Layer"]:::runtime
        click Config "https://github.com/irislib/iris-client/blob/main/config/default.json"
        click Config "https://github.com/irislib/iris-client/blob/main/config/dev.json"
        click Config "https://github.com/irislib/iris-client/blob/main/config/nestr.json"
        Browser -->|"load + config"| Config

        subgraph "SPA Modules"
            Embed["Embed Engine"]:::runtime
            click Embed "https://github.com/irislib/iris-client/blob/main/src/shared/utils/imgproxy.ts"
            click Embed "https://github.com/irislib/iris-client/tree/main/src/shared/components/embed/"

            ChatUI["Chat Module"]:::runtime
            click ChatUI "https://github.com/irislib/iris-client/tree/main/src/pages/chats/"

            FeedUI["Feed Module"]:::runtime
            click FeedUI "https://github.com/irislib/iris-client/tree/main/src/pages/home/feed/"
            click FeedUI "https://github.com/irislib/iris-client/tree/main/src/shared/components/feed/"

            Notif["Notifications Module"]:::runtime
            click Notif "https://github.com/irislib/iris-client/tree/main/src/pages/notifications/"
            click Notif "https://github.com/irislib/iris-client/blob/main/src/shared/components/feed/NotificationsFeed.tsx"

            Profile["User Profile Module"]:::runtime
            click Profile "https://github.com/irislib/iris-client/tree/main/src/pages/user/"
            click Profile "https://github.com/irislib/iris-client/tree/main/src/shared/components/user/"

            Settings["Settings Module"]:::runtime
            click Settings "https://github.com/irislib/iris-client/tree/main/src/pages/settings/"

            Thread["Thread Module"]:::runtime
            click Thread "https://github.com/irislib/iris-client/blob/main/src/pages/thread/index.tsx"

            Explorer["Explorer Module"]:::runtime
            click Explorer "https://github.com/irislib/iris-client/tree/main/src/pages/explorer/"

            Wallet["Wallet Module"]:::runtime
            click Wallet "https://github.com/irislib/iris-client/blob/main/src/pages/wallet/WalletPage.tsx"
            click Wallet "https://github.com/irislib/iris-client/blob/main/src/shared/hooks/useWalletBalance.ts"
        end

        Memcache["Caching Layer"]:::runtime
        click Memcache "https://github.com/irislib/iris-client/blob/main/src/utils/memcache.ts"

        NDK["Nostr Relay Network"]:::external
        click NDK "https://github.com/irislib/iris-client/blob/main/src/utils/ndk.ts"
        click NDK "https://github.com/irislib/iris-client/blob/main/src/utils/nostr.ts"

        WebRTC["WebRTC P2P Mesh"]:::external
        click WebRTC "https://github.com/irislib/iris-client/blob/main/src/utils/chat/webrtc/PeerConnection.ts"
        click WebRTC "https://github.com/irislib/iris-client/blob/main/src/utils/chat/Sessions.ts"

        WebLN["WebLN Provider"]:::runtime
        click WebLN "https://github.com/irislib/iris-client/blob/main/src/shared/hooks/useWebLNProvider.ts"

        Browser -->|"run SPA"| Embed
        Browser -->|"render UI"| ChatUI
        Browser -->|"render UI"| FeedUI
        Browser -->|"render UI"| Notif
        Browser -->|"render UI"| Profile
        Browser -->|"render UI"| Settings
        Browser -->|"render UI"| Thread
        Browser -->|"render UI"| Explorer
        Browser -->|"render UI"| Wallet
        Browser -->|"cache APIs"| Memcache
        Browser -->|"Ws connect"| NDK
        Browser -->|"WebRTC"| WebRTC
        Browser -->|"LightningPay"| WebLN
        Browser -->|"embed fetch"| Embed
    end

    %% External Services
    subgraph "External Services"
        RelaysNDK["Nostr Relays (WebSocket)"]:::external
        P2PPeers["WebRTC Peers"]:::external
        EmbedAPIs["Embed APIs\n(Spotify, YouTube, Twitter)"]:::external
    end

    Browser -->|"WebSocket"| RelaysNDK
    Browser -->|"WebRTC handshake"| P2PPeers
    Browser -->|"HTTP"| EmbedAPIs

    %% E2E Tests
    Playwright["Playwright Tests"]:::external
    click Playwright "https://github.com/irislib/iris-client/blob/main/playwright.config.ts"
    click Playwright "https://github.com/irislib/iris-client/tree/main/tests/"
    Playwright -->|"run against"| StaticServer

    %% Legend Styles
    classDef ci fill:#cce5ff,stroke:#004085
    classDef runtime fill:#d4edda,stroke:#155724
    classDef external fill:#ffe5b4,stroke:#cc8400
```
