# sagigl/split-connectivity architecture

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

- Interactive diagram: https://gitdiagram.com/sagigl/split-connectivity
- Repository: https://github.com/sagigl/split-connectivity

## Overview

##### Project type and purpose
- This is a full-stack real-time web application built with Next.js/React on the frontend and a standalone Node.js/Socket.IO server on the backend.
- Purpose: launch multiple synchronized browser windows that communicate in real time, animate “sphere” components, and display live data via WebSockets.

##### File structure
- Top-level:
- pages/index.tsx → Next.js entry point for the UI
- server/server.js → Node/Express + Socket.IO real-time server
- components/… → React UI components, including sphere visuals and link lines
- styles/, tailwind.config.ts, postcss.config.mjs, globals.scss → styling via Tailwind, Sass, CSS-in-JS
- types/Windows.type.ts → TypeScript types for window metadata
- openChrome.scpt → AppleScript to programmatically open new windows
- Configuration: next.config.ts, tsconfig.json, eslint.config.mjs, postcss.config.mjs, .prettierrc

##### Key architecture details from README
- Next.js for SSR/SSG of the React UI
- Socket.IO for real-time, cross-window synchronization
- Styled-Components (in code) + Tailwind + Sass for visual styling
- No external database—state is held in memory and broadcast via Socket.IO

##### Main components and their relationships
a. Frontend (Next.js/React)
- pages/index.tsx loads React app
- React components (Container, NewWindowButton, sphere subcomponents) handle visuals & user interactions
- openChrome.scpt can be invoked to spawn new browser windows pointing to the same URL
b. Backend (Node.js + Socket.IO)
- server/server.js sets up an HTTP + WebSocket endpoint
- Maintains connection registry and relays events (window join, move, sphere updates)
c. Communication flow
- HTTP(S) GET / → Next.js server → serves initial HTML/CSS/JS
- WebSocket (Socket.IO) channel → bidirectional real-time events
- Clients emit “move” or “createSphere” events → server broadcasts to all connected clients

##### Architectural patterns & design principles
- Real-time Pub/Sub via Socket.IO (event bus)
- Component-based UI (React) with clear separation of concerns (Container vs. sphere visuals)
- CSS layering: global Tailwind/Sass + scoped Styled-Components
- Type safety via TypeScript

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/UI Layer
    subgraph "Clients (Browser Windows)" 
        direction TB
        BW["Browser Window"]:::client
        Container["Container"]:::client
        NewWindowBtn["NewWindowButton"]:::client
        subgraph "Sphere Components"
            direction TB
            SphereBase["Sphere"]:::client
            SphereDisplay["SphereDisplay"]:::client
            SphereWrapper["SphereWrapper"]:::client
            SphereLine["SphereLine"]:::client
            LinkSphere["Link"]:::client
        end
    end

    %% Auxiliary Script
    openChrome["openChrome.scpt"]:::script

    %% Frontend Layer
    subgraph "Frontend Layer (Next.js)" 
        direction TB
        NextJS["Next.js Server"]:::frontend
        IndexPage["pages/index.tsx"]:::frontend
        GlobalsStyles["globals.scss"]:::frontend
        TailwindConfig["tailwind.config.ts"]:::frontend
        PostCSSConfig["postcss.config.mjs"]:::frontend
        NextConfig["next.config.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Real-Time Layer (Node.js + Socket.IO)"
        direction TB
        SocketServer["Node.js + Socket.IO Server"]:::backend
        ServerFile["server/server.js"]:::backend
    end

    %% Utils & Types
    subgraph "Utilities & Types"
        direction TB
        ColorUtil["utils/colors.utils.ts"]:::frontend
        WindowTypes["types/Windows.type.ts"]:::frontend
    end

    %% Connections
    BW -->|"GET /"| NextJS
    NextJS -->|"HTML/CSS/JS"| BW
    BW -.->|"socket.connect"| SocketServer
    SocketServer -.->|"broadcast"| BW
    BW -->|"moveEvent, createSphere"| SocketServer
    openChrome -.->|"launch"| BW

    %% Group component relationships
    BW --> Container
    Container --> NewWindowBtn
    Container --> SphereBase
    Container --> SphereDisplay
    Container --> SphereWrapper
    Container --> SphereLine
    Container --> LinkSphere

    %% click events
    click IndexPage "https://github.com/sagigl/split-connectivity/blob/main/pages/index.tsx"
    click Container "https://github.com/sagigl/split-connectivity/blob/main/components/Container.tsx"
    click NewWindowBtn "https://github.com/sagigl/split-connectivity/blob/main/components/NewWindowButton.tsx"
    click SphereBase "https://github.com/sagigl/split-connectivity/blob/main/components/sphere/Sphere.tsx"
    click SphereDisplay "https://github.com/sagigl/split-connectivity/blob/main/components/sphere/SphereDisplay.tsx"
    click SphereWrapper "https://github.com/sagigl/split-connectivity/blob/main/components/sphere/SphereWrapper.tsx"
    click SphereLine "https://github.com/sagigl/split-connectivity/blob/main/components/sphere/SphereLine.tsx"
    click LinkSphere "https://github.com/sagigl/split-connectivity/blob/main/components/sphere/Link.tsx"
    click ServerFile "https://github.com/sagigl/split-connectivity/blob/main/server/server.js"
    click GlobalsStyles "https://github.com/sagigl/split-connectivity/blob/main/styles/globals.scss"
    click TailwindConfig "https://github.com/sagigl/split-connectivity/blob/main/tailwind.config.ts"
    click PostCSSConfig "https://github.com/sagigl/split-connectivity/blob/main/postcss.config.mjs"
    click NextConfig "https://github.com/sagigl/split-connectivity/blob/main/next.config.ts"
    click ColorUtil "https://github.com/sagigl/split-connectivity/blob/main/utils/colors.utils.ts"
    click WindowTypes "https://github.com/sagigl/split-connectivity/blob/main/types/Windows.type.ts"
    click openChrome "https://github.com/sagigl/split-connectivity/blob/main/openChrome.scpt"

    %% Styles
    classDef client fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef frontend fill:#d4edda,stroke:#28a745,color:#000;
    classDef backend fill:#ffe5b4,stroke:#ff8c00,color:#000;
    classDef script fill:#fff3cd,stroke:#ffecb5,color:#000;
```
