Temporary Archive

A friendly multiplayer archive system for collaborative file sharing and management. Built with Node.js, Express, and Socket.IO for real-time collaboration.

Features

File Management

• File Upload: Drag-and-drop or click to upload files and folders
• File Download: Download individual files or entire folders as ZIP
• Directory Management: Create, rename, and navigate directories
• File Operations: Rename files, delete items via context menu
• Text Files: Create and edit text files directly in the browser
• Link Data Type: Upload links as a special data type with custom metadata

Views

• Table View: Traditional file browser with sortable columns and customizable visibility
• Grid View: Are.na-style responsive grid layout (2-4 columns based on screen size)
• Full-Page Viewer: Image/media viewer with navigation, zoom, and metadata editing
• Mobile Responsive: Grid view automatically uses GridViewer on narrow screens

Real-Time Collaboration

• Live Cursors: See other users' mouse cursors in real-time
• User Presence: View who's currently browsing and in which directory
• Live Chat: Chat with other users in a separate window
• Real-Time Updates: File changes sync instantly across all connected clients

Metadata & Organization

• Custom Metadata: Edit title, description, tags, alt text, contributor
• Inline Editing: Click any metadata field to edit directly
• Tag System: Add and manage tags for files
• Column Visibility: Show/hide metadata columns in table view
• Search & Filter: (Future feature)

Media Support

• Images: View with zoom, EXIF data extraction
• Videos: Built-in video player
• Audio: Audio playback controls
• PDFs: PDF viewer
• 3D Models: GLB/GLTF support via model-viewer
• Text Files: Syntax highlighting and editing

Getting Started

Prerequisites

• Node.js 20+
• npm or yarn

Installation

1. Clone the repository:

git clone <repository-url>
cd social-filesystem

2. Install dependencies:

npm install

3. Configure environment (optional):

cp env.example .env
# Edit .env if needed (defaults work for local development)

Running the Application

Development mode (with auto-reload):

npm run dev

Production mode:

npm start

The server will start on http://localhost:3000 (or the port specified in your .env file).

Project Structure

social-filesystem/
├── config/
│   └── storage.js          # Storage configuration
├── public/
│   ├── css/
│   │   └── main.css        # All styles
│   ├── js/
│   │   ├── api/            # API client modules
│   │   ├── components/     # UI components (CursorManager, GridViewer, etc.)
│   │   ├── utils/          # Utility functions
│   │   └── views/          # View implementations (TableView, GridView)
│   ├── library/            # File storage directory
│   ├── index.html          # Main application page
│   └── chat.html           # Chat window
├── server.js               # Express server and Socket.IO
├── package.json            # Dependencies
└── README.md               # This file

Usage

Uploading Files

• Click the + button in the header and select "Upload"
• Or drag and drop files/folders directly onto the page
• Supports uploading entire folder structures

Creating Items

Click the + button to:

• Upload files
• Create a new directory
• Create a new text file
• Create a new link

Viewing Files

• Table View: Double-click a file to open in MediaViewer
• Grid View: Click a file to open in GridViewer (full-page overlay)
• Use arrow keys to navigate between files in the viewer
• Press Escape to close viewers

Editing Metadata

• Click any metadata field (title, description, tags, etc.) to edit inline
• Changes save automatically
• Tags can be added/removed by clicking

Collaboration

• Set your name in the top-right corner
• Other users' cursors will appear in real-time
• Click the chat icon (💬) to open the chat window
• File changes sync automatically to all users

Architecture

The application uses a modular architecture:

• Components: Reusable UI components (CursorManager, GridViewer, MetadataEditor, etc.)
• Views: Different display modes (TableView, GridView) managed by ViewManager
• API Layer: Separated API calls for files, metadata, and Socket.IO
• Utils: Shared utility functions for formatting, path manipulation, local storage

Storage

Files are stored locally in public/library/ directory. Metadata is stored in public/library/library.json.

Development

Scripts

• npm start - Run production server
• npm run dev - Run development server with nodemon (auto-reload)
• npm run test:storage - Test storage functionality

Code Style

• ES6 modules for client-side code
• Modular component architecture
• Custom CSS (no framework dependencies)
• Socket.IO for real-time features

Deployment

This repository contains example deployment configurations:

• Dockerfile - Container image definition
• docker-compose.yml.example - Docker Compose template
• Caddyfile.example - Reverse proxy configuration example
• .forgejo/workflows/*.example - CI/CD workflow templates

Note: Actual deployment configurations (with real paths, secrets, and environment-specific settings) should be kept in a separate private infrastructure repository. See DEPLOYMENT_REPO_STRUCTURE.md and MIGRATE_TO_INFRA_REPO.md for details.

For deployment guides:

• DEPLOYMENT.md - General deployment documentation
• CI_CD.md - CI/CD setup guide

Troubleshooting

Port Already in Use

Change the PORT in your .env file or stop the process using that port.

Files Not Appearing

• Check that public/library/ directory exists and is writable
• Verify public/library/library.json exists
• Check server logs for errors

Real-Time Features Not Working

• Ensure Socket.IO connection is established (check browser console)
• Verify no firewall is blocking WebSocket connections
• Check that server is running and accessible