scar-chat7/QUICKSTART.md

# SCAR Chat - Quick Start Guide

## Initial Setup

### 1. Install Dependencies

#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install -y \
    build-essential cmake git \
    qt6-base-dev libboost-all-dev \
    libssl-dev libsqlite3-dev \
    libpipewire-0.3-dev \
    libavcodec-dev libavformat-dev libavutil-dev \
    libdbus-1-dev
```

#### Fedora
```bash
sudo dnf install -y \
    gcc-c++ cmake git \
    qt6-qtbase-devel boost-devel \
    openssl-devel sqlite-devel \
    pipewire-devel \
    ffmpeg-devel \
    dbus-devel
```

#### Windows
1. Install Visual Studio 2022 with C++ support
2. Install CMake from https://cmake.org/
3. Install Qt6 from https://www.qt.io/
4. Install Boost via vcpkg:
   ```powershell
   vcpkg install boost-asio boost-system boost-thread openssl sqlite3 ffmpeg
   ```

### 2. Clone and Build

```bash
# Clone repository
cd /home/ganome/Projects/SCAR-719/repos/scar-chat7

# Build server and client
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
```

### 3. Generate SSL Certificates

For testing purposes, generate self-signed certificates:

```bash
openssl req -x509 -newkey rsa:4096 \
    -keyout server.key -out server.pem \
    -days 365 -nodes \
    -subj "/C=US/ST=State/L=City/O=SCAR/CN=localhost"
```

Place `server.key` and `server.pem` in the project root.

### 4. Create Test User

Use the `dbmanager` tool to create users with proper Argon2 password hashing:

```bash
# Create a test user
./build/dbmanager/dbmanager adduser testuser testpass

# Create admin user with avatar
./build/dbmanager/dbmanager adduser admin adminpass /path/to/avatar.jpg
./build/dbmanager/dbmanager modifyrole admin admin

# List all users
./build/dbmanager/dbmanager list
```

The database will be automatically created in the current directory as `scarchat.db`.

See `dbmanager/README.md` for complete documentation.

**Better approach:** Add a `--create-user` command-line option to the server (TODO).

### 5. Run Server

```bash
cd /home/ganome/Projects/SCAR-719/repos/scar-chat7
./build/server/scarchat-server

# Or with custom paths:
./build/server/scarchat-server \
    --db ./scarchat.db \
    --cert ./server.pem \
    --key ./server.key
```

Expected output:
```
SCAR Chat Server v1.0.0
=======================

Configuration:
  Database: scarchat.db
  SSL Cert: server.pem
  SSL Key:  server.key
  Host:     0.0.0.0
  Port:     8443

Server listening on 0.0.0.0:8443
```

### 6. Run Client

```bash
./build/client/scarchat
```

1. Login dialog will appear
2. Enter:
   - Username: `testuser`
   - Password: `password123`
   - Server: `localhost`
   - Port: `8443`
3. Click Connect

## Current Capabilities

### Working Features ✅
- Server accepts SSL connections
- Client connects with exponential backoff
- User authentication (username/password → argon2 → JWT)
- Text messaging with chat history
- User list display
- Dark Discord-inspired UI
- Status bar with connection status, user count, clock
- Typing indicators

### TODO Features 🔄
- **Media capture implementation:**
  - Pipewire camera integration
  - Screen capture (X11/Wayland/Windows)
  - DBus portal for Wayland
- **Video streaming protocol:**
  - Video stream message types
  - Server-side stream routing
  - Client video decoder/display
- **User management:**
  - Server command to create/delete users
  - User registration endpoint
  - Avatar upload/download
- **Enhanced features:**
  - Voice chat
  - File sharing
  - Emoji/reactions
  - User roles/permissions

## Testing

### Manual Testing Checklist

1. **Server Startup**
   - [ ] Server starts without errors
   - [ ] Database is created if missing
   - [ ] SSL certificates load correctly

2. **Client Connection**
   - [ ] Client shows login dialog
   - [ ] Connection succeeds with valid credentials
   - [ ] Connection fails gracefully with invalid credentials
   - [ ] Reconnect works after server restart

3. **Messaging**
   - [ ] Send text messages
   - [ ] Receive messages from other clients
   - [ ] Chat history persists across restarts
   - [ ] Typing indicators appear

4. **UI**
   - [ ] Dark theme renders correctly
   - [ ] User list updates when users join/leave
   - [ ] Status bar shows connection state
   - [ ] Clock updates every second
   - [ ] Video grid shows placeholder when empty

### Multi-Client Test

1. Start server
2. Run client #1, login as user1
3. Run client #2, login as user2
4. Send messages between clients
5. Verify both see each other in user list

## Troubleshooting

### "Cannot open database"
- Ensure write permissions in current directory
- Check `--db` path is valid

### "Cannot open certificate file"
- Run `openssl req ...` command above
- Ensure `server.pem` and `server.key` exist
- Use `--cert` and `--key` options

### "SSL handshake error"
- Client may need to trust self-signed cert
- Check OpenSSL versions match
- Verify certificate is valid

### Client won't connect
- Check server is running: `netstat -tlnp | grep 8443`
- Verify firewall allows port 8443
- Check server host/port in client config

### Qt platform plugin error
```bash
export QT_QPA_PLATFORM_PLUGIN_PATH=/path/to/qt6/plugins/platforms
```

## Development Workflow

### Adding a New Feature

1. Update PROGRESS.md with feature status
2. Implement in appropriate module (client/server/shared)
3. Add to CMakeLists.txt if new files
4. Build and test
5. Update README/docs

### Code Style
- C++20 standard
- Use `snake_case` for variables/functions
- Use `PascalCase` for classes
- Include guards: `#pragma once`
- Namespace: `scar`

## Next Steps

See [PROGRESS.md](PROGRESS.md) for detailed implementation status.

Priority tasks:
1. Add `--create-user` command to server
2. Implement Pipewire camera capture
3. Implement screen capture backends
4. Add video streaming protocol
5. Test on multiple platforms