# oceans404/fullstack-sockets-demo architecture

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

- Interactive diagram: https://gitdiagram.com/oceans404/fullstack-sockets-demo
- Repository: https://github.com/oceans404/fullstack-sockets-demo

## Overview

##### Project type and purpose
- This is a full-stack, real-time chat application.
- Frontend: React (Vite) SPA that renders a chat UI and connects to a WebSocket server.
- Backend: Node.js server using Socket.io to manage bi-directional, event-based communication.

##### File structure
- Top level:
- README.md (project overview, tutorial steps)
- frontend/ (React app)
- server/ (Node.js Socket.io server)
- frontend/:
- vite.config.js, package.json – build and dependency definitions
- src/ – React components (App.jsx, SingleFieldForm.jsx) and CSS
- public/ & index.html – static host page
- server/:
- package.json – scripts (start: nodemon server.js), dependencies (socket.io, dotenv)
- server.js (implicitly present) – Socket.io server logic, CORS setup, custom event handlers
- Config files:
- .gitignore in both packages
- .env files (frontend/.env with VITE_SERVER_URL; server/.env with NODE_CLIENT_ORIGIN)
- Deployment manifests are handled externally (Fleek, Render).

##### Core README insights
- Establishes Socket.io connection (client ↔ server) over port 3000.
- CORS configuration on the server to permit the frontend origin (localhost:5173 or deployed URL).
- Tracks special events (connect, disconnect) and custom events (“set-username”, “new-user”, “send-message”, “new-message”).
- Environment variable setup for runtime URLs.
- Deployment processes using Fleek (IPFS) for frontend and Render for backend.

##### Main components and their interactions
a. Components
- Client App (React SPA)
- Socket.io Client (in App.jsx)
- Socket.io Server (Node.js + socket.io)
- Environment Layer (.env variables)
- Optional Infrastructure: IPFS/CDN (frontend), Render service (backend), DNS/CORS gateway
b. Relationships & data flow
1. User types into the React UI → form component emits “send-message” over socket.
2. Socket.io Client connects to Socket.io Server; handles built-in events (connect, disconnect).
3. Server listens, logs, emits back to all connected clients (“new-message”, “new-user”).
4. React App useEffect hooks capture “new-message” and “new-user” events → update UI state.
5. Env vars inject proper server URL on both sides.
c. Architectural patterns & principles
- Separation of Concerns: distinct client and server codebases.
- Event-driven messaging: pub/sub style socket events.
- Configuration via environment variables for portability.
- Stateless server: messages are broadcasted, no persistent storage (could be extended).
d. Key technologies
- React (Vite) – fast dev server, JSX components, state/hooks
- Socket.io – real-time websockets fallback to polling, server & client libraries
- Node.js – Express-style server script (server.js) with nodemon for development
- dotenv – config loader for .env files
- Fleek (IPFS/CDN) & Render.com – hosting/deployment platforms

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["User's Browser"]:::external
        HTMLshell["index.html"]:::frontend
        ReactSPA["React SPA"]:::frontend
        SingleFieldForm["SingleFieldForm Component"]:::frontend
        SocketClient["Socket.io Client"]:::api
        AppCSS["App.css"]:::frontend
        IndexCSS["index.css"]:::frontend
        ViteConfig["vite.config.js"]:::config
        FrontPkg["package.json"]:::config
        FrontGitignore[".gitignore"]:::config
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        NodeServer["Node.js Server"]:::backend
        SocketServer["Socket.io Server"]:::backend
        CORSConfig["CORS Configuration"]:::config
        EventHandlers["Event Handlers"]:::backend
        ServerPkg["package.json"]:::config
        ServerGitignore[".gitignore"]:::config
    end

    %% Environment Layer
    subgraph "Environment Configuration"
        direction TB
        FrontEnv[".env (frontend)"]:::env
        ServerEnv[".env (server)"]:::env
    end

    %% Deployment Layer
    subgraph "Deployment"
        direction TB
        CDN["IPFS / CDN (Fleek)"]:::external
        RenderService["Render Service"]:::external
    end

    %% Connections - Frontend
    Browser --> HTMLshell
    HTMLshell --> ReactSPA
    ReactSPA --> SingleFieldForm
    ReactSPA --> SocketClient
    SingleFieldForm -->|"send-message"| SocketClient
    ReactSPA -->|"uses styles"| AppCSS
    ReactSPA -->|"global styles"| IndexCSS
    ReactSPA -->|"build config"| ViteConfig

    %% Connections - Frontend to Backend
    SocketClient -->|"ws://localhost:3000/socket.io"| SocketServer
    SocketClient -->|"connect / disconnect"| SocketServer

    %% Connections - Backend
    SocketServer --> CORSConfig
    SocketServer --> EventHandlers
    EventHandlers -->|"emit new-message / new-user"| SocketServer

    %% Backend to Frontend events
    SocketServer -->|"new-message / new-user"| SocketClient

    %% Environment wiring
    ViteConfig --> FrontEnv
    NodeServer --> ServerEnv
    SocketClient --> FrontEnv
    CORSConfig --> ServerEnv

    %% Deployment flows
    ReactSPA --> CDN
    NodeServer --> RenderService

    %% Shared project files
    Browser -.-> Readme["README.md"]:::config

    %% Click Events
    click ReactSPA "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/src/App.jsx"
    click SingleFieldForm "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/src/SingleFieldForm.jsx"
    click Main "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/src/main.jsx"
    click AppCSS "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/src/App.css"
    click IndexCSS "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/src/index.css"
    click HTMLshell "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/index.html"
    click ViteConfig "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/vite.config.js"
    click FrontPkg "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/package.json"
    click FrontGitignore "https://github.com/oceans404/fullstack-sockets-demo/blob/main/frontend/.gitignore"
    click ServerPkg "https://github.com/oceans404/fullstack-sockets-demo/blob/main/server/package.json"
    click ServerGitignore "https://github.com/oceans404/fullstack-sockets-demo/blob/main/server/.gitignore"
    click Readme "https://github.com/oceans404/fullstack-sockets-demo/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6;
    classDef backend fill:#DFF5D0,stroke:#228B22;
    classDef api fill:#FFE0B2,stroke:#FB8C00;
    classDef config fill:#F0F0F0,stroke:#B3B3B3;
    classDef env fill:#FFF3CD,stroke:#FFB300;
    classDef external fill:#E0E0E0,stroke:#687076;
```
