# anycable/vercel-anycable-demo architecture

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

- Interactive diagram: https://gitdiagram.com/anycable/vercel-anycable-demo
- Repository: https://github.com/anycable/vercel-anycable-demo

## Overview

The project is a full‐stack real-time web application built with Next.js that integrates with AnyCable to enable WebSocket-based real-time features. The main purpose, as described in the README, is to demonstrate how to use AnyCable with Next.js (and Vercel) for building serverless real-time applications, particularly in the context of chat channels and authentication via JWT tokens.

##### Main Components
- Frontend (Next.js Application):
– Contains pages (e.g., app/page.tsx, app/auth/page.tsx) and layouts managing the user interface.
– Houses UI components like chat components, headers, avatars, forms, and message lists found in app/components.
- API Endpoints and Serverless Functions:
– Located under app/api (with subdirectories for anycable, auth, channels, and og). These endpoints handle interactions with AnyCable, authentication, and channel logic.
- Real-time Communication Layer (AnyCable Integration):
– Next.js communicates with the AnyCable-Go server via the API endpoints (e.g., app/api/anycable/route.ts) and client-side stores (app/stores/cable.ts, messages.ts, user.ts) to manage WebSocket connections.
- External Real-time Server (AnyCable-Go):
– Although not part of the repository code, the README explains that an external AnyCable-Go server (which can be deployed on platforms like Fly.io) will process WebSocket connections, broadcast messages, and authenticate connections via JWTs.
- Configuration and Deployment:
– Several configuration files (next.config.js, tailwind.config.ts, fly.toml.example) indicate deployment considerations for Vercel and Fly.io.
- Utility and State Management Layers:
– Utility functions in app/utils (e.g., format-date, gravatar-url) support standard operations, while the stores manage client state and maintain connection information.

##### Relationships and Interactions
- Data Flow:
– The browser (client) makes requests to Next.js pages which use both SSR and client-side rendering.
– Client-side components and stores trigger API calls for actions like authentication, channel communication, and message broadcasting.
– API endpoints route these actions to the AnyCable integration endpoints, which in turn forward or transform these actions to the AnyCable-Go server.
- Communication:
– Additionally, include feedback paths showing how real-time messages flow back from the AnyCable-Go server (via API or WebSocket channels) to update the client state.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
– The project separates UI components, API logic, and real-time communication handling.
– Different concerns (authentication vs. channel messaging) are handled in distinct directories.
- Serverless and Microservices:
– By deploying the Next.js application on Vercel and the AnyCable-Go server separately (with its dedicated configuration), the system adheres to a microservices-inspired deployment.
- Real-time Communication Pattern:
– The architecture leverages web sockets (via AnyCable) for bidirectional communication, using JWT-based authentication for efficient real-time identification.

##### Relevant Technologies and Frameworks
- Next.js for the frontend application structure.
- AnyCable for WebSocket-based real-time communication.
- Vercel as a deployment platform for the Next.js application.
- Fly.io as an optional deployment platform for the AnyCable-Go server.
- Tailwind CSS for styling (with configurations in tailwind.config.ts).
- TypeScript for static typing (as seen in tsconfig.json).

##### Elements to Always Include
- Clear labels for each system component (Frontend Application, API Endpoints, AnyCable Integration, External AnyCable-Go Server, Utilities, and State Stores).
– From the client (browsers) to Next.js pages/components.
– From the API endpoints to the external AnyCable-Go server.
– Feedback loops for real-time message broadcasting.
– UI components vs. backend services.
– Internal application logic vs. external systems (AnyCable-Go server).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    ClientBrowser("Client Browser"):::external

    %% Frontend Layer
    subgraph "Next.js Frontend"
        subgraph "Pages"
            MainPage("Main Page"):::page
            AuthPage("Auth Page"):::page
        end
        subgraph "UI Components"
            MainLayout("Main Layout"):::component
            ChatComp("Chat Component"):::component
            AuthForm("Auth Form"):::component
        end
    end

    %% API Endpoints and Serverless Functions
    subgraph "API Endpoints"
        AnyCableAPI("AnyCable API"):::api
        AuthAPI("Authentication API"):::api
        ChannelAPI("Channel API"):::api
        OGAPI("Open Graph API"):::api
        APICable("Cable API Support"):::api
    end

    %% Real-time Communication Layer (Client-side stores)
    subgraph "Real-time Communication"
        CableStore("Cable Store"):::realtime
        MessageStore("Messages Store"):::realtime
        UserStore("User Store"):::realtime
    end

    %% External Real-time Server
    ExternalServer("External AnyCable-Go Server"):::external

    %% Configurations and Deployment
    subgraph "Configurations & Deployment"
        NextConfig("Next.js Config"):::config
        TailwindConfig("Tailwind Config"):::config
        FlyConfig("Fly.io Config"):::config
        EnvSample("Environment Sample"):::config
    end

    %% Utility and State Management Layers
    subgraph "Utilities"
        FormatDate("Format Date"):::utility
        GravatarUrl("Gravatar URL"):::utility
        RoomLabel("Room Label"):::utility
        SeedRandom("Seed Random"):::utility
    end

    %% Data Flow Connections
    ClientBrowser -->|"loads"| MainPage
    ClientBrowser -->|"loads"| AuthPage

    MainPage -->|"renders"| MainLayout
    AuthPage -->|"renders"| AuthForm

    MainLayout -->|"calls"| AnyCableAPI
    MainLayout -->|"calls"| AuthAPI
    MainLayout -->|"calls"| ChannelAPI
    MainLayout -->|"calls"| OGAPI
    MainLayout -->|"calls"| APICable

    AuthForm -->|"triggers"| AuthAPI

    AnyCableAPI -->|"forwards"| ExternalServer
    AuthAPI -->|"forwards"| ExternalServer
    ChannelAPI -->|"forwards"| ExternalServer
    OGAPI -->|"forwards"| ExternalServer
    APICable -->|"forwards"| ExternalServer

    ExternalServer -->|"broadcasts"| CableStore
    ExternalServer -->|"broadcasts"| MessageStore
    ExternalServer -->|"broadcasts"| UserStore

    CableStore -->|"updates"| ChatComp
    MessageStore -->|"updates"| ChatComp
    UserStore -->|"updates"| ChatComp

    ChatComp -->|"formats"| FormatDate
    ChatComp -->|"uses"| GravatarUrl
    ChatComp -->|"labels"| RoomLabel
    ChatComp -->|"randomizes"| SeedRandom

    %% Click Events for Frontend Pages & Components
    click MainPage "https://github.com/anycable/vercel-anycable-demo/blob/master/app/page.tsx"
    click AuthPage "https://github.com/anycable/vercel-anycable-demo/blob/master/app/auth/page.tsx"
    click MainLayout "https://github.com/anycable/vercel-anycable-demo/blob/master/app/layout.tsx"
    click ChatComp "https://github.com/anycable/vercel-anycable-demo/blob/master/app/components/chat.tsx"
    click AuthForm "https://github.com/anycable/vercel-anycable-demo/blob/master/app/components/auth-form.tsx"

    %% Click Events for API Endpoints
    click AnyCableAPI "https://github.com/anycable/vercel-anycable-demo/blob/master/app/api/anycable/route.ts"
    click AuthAPI "https://github.com/anycable/vercel-anycable-demo/blob/master/app/api/auth/cable/route.ts"
    click ChannelAPI "https://github.com/anycable/vercel-anycable-demo/blob/master/app/api/channels/chat-channel.ts"
    click OGAPI "https://github.com/anycable/vercel-anycable-demo/blob/master/app/api/og/route.tsx"
    click APICable "https://github.com/anycable/vercel-anycable-demo/blob/master/app/api/cable.ts"

    %% Click Events for Real-time Communication Stores
    click CableStore "https://github.com/anycable/vercel-anycable-demo/blob/master/app/stores/cable.ts"
    click MessageStore "https://github.com/anycable/vercel-anycable-demo/blob/master/app/stores/messages.ts"
    click UserStore "https://github.com/anycable/vercel-anycable-demo/blob/master/app/stores/user.ts"

    %% Click Events for Configurations & Deployment
    click NextConfig "https://github.com/anycable/vercel-anycable-demo/blob/master/next.config.js"
    click TailwindConfig "https://github.com/anycable/vercel-anycable-demo/blob/master/tailwind.config.ts"
    click FlyConfig "https://github.com/anycable/vercel-anycable-demo/blob/master/fly.toml.example"
    click EnvSample "https://github.com/anycable/vercel-anycable-demo/blob/master/.env.sample"

    %% Click Events for Utilities
    click FormatDate "https://github.com/anycable/vercel-anycable-demo/blob/master/app/utils/format-date.ts"
    click GravatarUrl "https://github.com/anycable/vercel-anycable-demo/blob/master/app/utils/gravatar-url.ts"
    click RoomLabel "https://github.com/anycable/vercel-anycable-demo/blob/master/app/utils/room-label.ts"
    click SeedRandom "https://github.com/anycable/vercel-anycable-demo/blob/master/app/utils/seed-random.ts"

    %% Styles
    classDef page fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef component fill:#90EE90,stroke:#333,stroke-width:2px
    classDef api fill:#FFD700,stroke:#333,stroke-width:2px
    classDef realtime fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:2px
    classDef utility fill:#FFC0CB,stroke:#333,stroke-width:2px
    classDef external fill:#FFA07A,stroke:#333,stroke-width:2px
```
