LAN Secure Chat
& Video Calls

1.1 What is XteVision SecuChat?

XteVision SecuChat (xtevision-secuchat v1.0.0) is a lightweight, local-first, self-hosted chat server and single-page web client for quick LAN messaging and peer-to-peer video calls. It stores data in data.json, serves the UI from public/, and saves uploads to uploads/. It is designed to run with minimal setup — no external database required.

1.2 Key Capabilities

• Account-based users: register / login with salted scrypt password hashing
• Real-time presence & messaging using Server-Sent Events (SSE)
• Contacts: request / accept workflow and presence updates
• File uploads: attachments & avatars (limits enforced) saved to uploads/
• P2P video calls: via PeerJS + a local PeerServer (port 5009)
• AI helpers & assistant: on-device or remote model integrations for conversational chat, translation, summarization, embeddings and content moderation; configurable model selection and streaming responses
• Security: CSP and common security headers set by the server

1.3 Target Users

• Primary: Teams and organizations that want a private, LAN-based chat and video-calling solution without cloud dependency
• Secondary: Privacy-sensitive users who want on-device or self-hosted AI helpers for chat, translation, and moderation

2.1 High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Browser (Single-Page Client)              │
│  ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌──────────────┐  │
│  │ Login  │ │ Chat     │ │Contacts │ │Calls   │ │AI Assistant  │  │
│  └────────┘ └──────────┘ └────────┘ └────────┘ └──────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP / SSE
┌──────────────────────────────┴──────────────────────────────────┐
│                    Node.js Server (port 5008)                     │
│  ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────────┐  │
│  │ Auth      │ │Messages   │ │Contacts   │ │AI Proxy (optional) │  │
│  │(scrypt)   │ │(SSE)      │ │(request/  │ │ → local/remote LLM │  │
│  │           │ │           │ │ accept)   │ └────────────────────┘  │
│  └───────────┘ └──────────┘ └──────────┘                          │
│  ┌───────────┐ ┌───────────────────────────────────────────────┐  │
│  │Uploads    │ │ data.json (users, messages, contacts)          │  │
│  │ (uploads/ │ │ public/ (served UI)                           │  │
│  └───────────┘ └───────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ PeerJS signaling
┌──────────────────────────────┴──────────────────────────────────┐
│                    Local PeerServer (port 5009)                    │
│  P2P media connection between peers (video calls)                 │
└───────────────────────────────────────────────────────────────────┘

2.2 Communication Flow

1. Frontend → Server: HTTP requests for auth, messages, contacts, uploads; SSE subscription for real-time presence & messages
2. Server → data.json: All user, message, and contact state persisted to a single JSON file — no external database
3. Frontend → PeerServer: P2P video calls signal through the local PeerServer (port 5009), then media flows peer-to-peer
4. Frontend → AI Backend: Chat, translation, summarization, embeddings, and moderation go through the AI proxy to a local (Ollama/MLX) or remote model

2.3 Deployment Model

XteVision SecuChat is designed for self-hosted, LAN-first operation:

• Runs as a standalone Node.js server on your own hardware
• For LAN-only usage, binding to a private interface is sufficient
• For remote access, run behind a reverse proxy (nginx) and enable HTTPS
• All chat data stays on your local server — no cloud dependency

4.1 Prerequisites

• Node.js LTS (e.g. 16+)
• npm or yarn
• PeerServer (optional, only for P2P fallback — see peerjs/)
• Local AI service (optional, for the AI endpoints)

4.2 Install

Install dependencies, then optionally install the Peer server for P2P fallback.

# 1. Install server dependencies
npm install

# 2. (Optional) Install Peer server for P2P fallback
cd peerjs
npm install
cd ..

4.3 Access the Application

http://your-server-ip:5008

The server runs on port 5008 by default. Connect from your local network. The PeerServer for P2P calls uses port 5009.

4.4 Start the Server

# Development
npm run dev        # if defined in package.json

# Production
NODE_ENV=production npm start
# or: node server.js

XteVision reads runtime settings from config.json in the project root. Edit it for your deployment values before starting the server.

5.1 Key Sections

5.2 Common Environment Variables

6.1 Directory Layout

xtevision-secuchat/
├── server.js                 # Main Express server: routes, SSE, uploads, AI proxy
├── config.json               # Runtime configuration (server / ai / client)
├── data.json                 # Users, messages, and contacts (back up before edits)
├── public/                   # Single-page UI (served as static assets)
├── uploads/                  # Attachments & avatars (enforced limits)
├── peerjs/                   # Optional local PeerServer for P2P fallback
└── package.json              # Dependencies & scripts

6.2 Key Files

7.1 Endpoints Overview

7.2 AI Helper Endpoints

Optional — require a configured AI service. Refer to the server code for exact parameter names and response formats.

8.1 Quick Guide

• Local-first: If an internal/local AI service (AI_BASE_URL) is available it is preferred; requests are proxied to it with model + key as configured.
• Streaming: Set AI_STREAM=true and request with Accept: text/event-stream to receive incremental assistant tokens (SSE).
• Embeddings: Use /api/ai/embeddings for vector representations for search or clustering; batching controlled by AI_BATCH_EMBEDDINGS.
• Privacy: Set AI_LOCAL_ONLY=true to prevent forwarding content to external services. API keys are read from env vars and not logged.

8.2 Examples

Chat (non-streaming):

curl -s -X POST http://localhost:5008/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Summarize this message: ..."}]}'

Chat (streaming SSE):

curl -N -X POST http://localhost:5008/api/ai/chat \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"messages":[{"role":"user","content":"Tell me about XteVision in one paragraph."}], "model":"gpt-4o-mini"}

Embeddings:

curl -s -X POST http://localhost:5008/api/ai/embeddings \
  -H "Content-Type: application/json" \
  -d '{"texts":["hello","world"]}

9.1 Server-Side Security

• Password hashing: Salted scrypt — no plaintext passwords stored
• Content Security Policy: CSP and common security headers are set by the server
• Upload limits: Enforced server-side — oversized uploads are rejected
• No auth for LAN: The server is designed for local LAN use; add HTTPS + reverse proxy for remote access

9.2 AI Privacy Notes

• API keys (AI_API_KEY) remain in the server environment and are treated like secrets — the server will not log keys.
• If AI_BASE_URL points to an external service, user content is forwarded to that service — enable AI_LOCAL_ONLY for privacy-sensitive setups.
• Rate limiting (AI_RATE_LIMIT) helps avoid abuse and unexpected costs.

10.1 Server & Port

• Issue: Port conflict
• Solution: Ensure PORT is free or change it via env var.

10.2 Uploads

• Issue: Upload errors
• Solution: Check write permissions on the uploads/ directory.

10.3 Video Calls

• Issue: Peer connections fail
• Solution: Ensure PeerServer is running and reachable from clients; check the browser console for WebRTC errors.

10.4 AI Requests

• Issue: AI requests failing
• Solution: Verify AI_BASE_URL, AI_API_KEY, and model names; check rate limits and set AI_STREAM_TIMEOUT appropriately. If a local AI service is used, ensure it is healthy and reachable.