Update README.md to provide detailed project description, features, installation instructions, usage guidelines, and technical details for WebCounter - a Flask WebSocket server.

README.md

@@ -1,2 +1,112 @@
-# webcounter
+# WebCounter - WebSocket Server
+
+A Python Flask webserver with WebSocket support that serves two pages - a client and a controller. The controller can send events to connected clients via WebSocket.
+
+## Features
+
+- **Client Page**: Receives and displays events from the controller
+- **Controller Page**: Sends events to all connected clients
+- **Mechanical Counter**: Vintage-style 6-digit counter with animated number wheels
+- **Real-time Communication**: WebSocket-based event broadcasting
+- **Modern UI**: Clean, responsive design
+- **Event Types**: Support for different event types (message, notification, update, alert, custom)
+- **Quick Actions**: Pre-defined buttons for common events
+
+## Dependency Management with uv
+
+This project uses [`uv`](https://github.com/astral-sh/uv) for fast Python dependency management.
+
+### Install uv
+
+If you don't have `uv` installed, you can install it with:
+```bash
+pip install uv
+```
+Or see the [uv installation guide](https://github.com/astral-sh/uv#installation) for more options.
+
+### Install dependencies
+```bash
+uv pip install -r pyproject.toml
+```
+
+Or, to create a lockfile and install:
+```bash
+uv pip install --sync
+```
+
+## Running the Server
+
+1. Start the server:
+```bash
+python app.py
+```
+
+2. The server will start on port 8079. You'll see output like:
+```
+Starting webserver on port 8079...
+Client page: http://localhost:8079/client
+Controller page: http://localhost:8079/controller
+```
+
+## Usage
+
+1. **Main Page**: Visit `http://localhost:8079/` to see the navigation page
+2. **Client Page**: Visit `http://localhost:8079/client` to open a client that receives events
+3. **Controller Page**: Visit `http://localhost:8079/controller` to open the controller that sends events
+4. **Mechanical Counter Display**: Visit `http://localhost:8079/mechanical-counter` to see the vintage counter display
+5. **Mechanical Counter Controller**: Visit `http://localhost:8079/mechanical-counter-controller` to control the counter
+
+### How it Works
+
+1. Open multiple client pages in different browser tabs/windows
+2. Open the controller page
+3. Use the controller to send events (messages, notifications, etc.)
+4. All connected clients will receive the events in real-time
+
+### Mechanical Counter
+
+The mechanical counter simulates a vintage mechanical counter with:
+- **6-digit display** with individual animated wheels
+- **Vintage styling** with the OpenGost Type B font
+- **Smooth animations** that simulate mechanical wheel rotation
+- **Real-time updates** via WebSocket
+- **Individual digit control** from the controller
+- **Quick preset buttons** for common values
+
+### Event Types
+
+- **Message**: Simple text messages
+- **Notification**: System notifications with different priorities
+- **Update**: Data updates
+- **Alert**: Important alerts
+- **Custom**: Custom JSON data
+
+### Quick Actions
+
+The controller page includes quick action buttons for:
+- Success notifications
+- Warning notifications
+- Error notifications
+- Counter updates
+
+## Technical Details
+
+- **Backend**: Flask with Flask-SocketIO
+- **Frontend**: HTML, CSS, JavaScript with Socket.IO client
+- **WebSocket**: Real-time bidirectional communication
+- **Port**: 8079 (configurable in app.py)
+- **Dependency Management**: [uv](https://github.com/astral-sh/uv)
+
+## File Structure
+
+```
+webcounter/
+├── app.py                 # Main Flask application
+├── pyproject.toml         # Project metadata and dependencies
+├── templates/            # HTML templates
+│   ├── index.html        # Main navigation page
+│   ├── client.html       # Client page
+│   └── controller.html   # Controller page
+└── README.md            # This file
+```