veza/veza-backend-api/docs/USER_GUIDE.md

# Veza Platform - User Guide

## Table of Contents

1. [Getting Started](#getting-started)
2. [Account Management](#account-management)
3. [Profile Management](#profile-management)
4. [Audio Tracks](#audio-tracks)
5. [Playlists](#playlists)
6. [Marketplace](#marketplace)
7. [Social Features](#social-features)
8. [Chat & Conversations](#chat--conversations)
9. [Search & Discovery](#search--discovery)
10. [Analytics](#analytics)
11. [Settings & Preferences](#settings--preferences)
12. [Troubleshooting](#troubleshooting)

## Getting Started

### Creating an Account

1. **Visit the Registration Page**
   - Navigate to the Veza platform
   - Click "Sign Up" or "Register"

2. **Fill in Your Information**
   - **Email**: Your email address (will be used for verification)
   - **Username**: Choose a unique username (3-30 characters)
   - **Password**: Create a strong password (minimum 12 characters)
   - **Password Confirmation**: Re-enter your password

3. **Password Requirements**
   - Minimum 12 characters
   - At least one uppercase letter
   - At least one lowercase letter
   - At least one number
   - At least one special character
   - Cannot contain common words like "password"

4. **Verify Your Email**
   - Check your email inbox
   - Click the verification link
   - Your account will be activated

### Logging In

1. **Enter Your Credentials**
   - Email address
   - Password
   - (Optional) Check "Remember me" for persistent session

2. **Two-Factor Authentication (2FA)**
   - If 2FA is enabled, you'll be prompted for a code
   - Enter the code from your authenticator app (e.g., Google Authenticator)
   - Or use a recovery code if you've lost access to your device

3. **Forgot Password?**
   - Click "Forgot Password"
   - Enter your email address
   - Check your email for reset instructions
   - Follow the link to create a new password

### First Steps After Registration

1. **Complete Your Profile**
   - Add a profile picture
   - Write a bio
   - Add your location
   - Link your social media accounts

2. **Explore the Platform**
   - Browse tracks
   - Discover playlists
   - Follow other users
   - Explore the marketplace

## Account Management

### Profile Settings

Access your profile settings from the user menu.

#### Basic Information

- **Username**: Your unique identifier (can be changed, but limited)
- **Email**: Your account email (used for login and notifications)
- **Display Name**: How your name appears to others
- **Bio**: A short description about yourself
- **Location**: Your city, country, or region
- **Birthdate**: Your date of birth (optional, for age verification)
- **Gender**: Your gender identity (optional)

#### Privacy Settings

- **Profile Visibility**: Public or Private
- **Email Visibility**: Show or hide email on profile
- **Activity Visibility**: Control what others can see

#### Security Settings

- **Change Password**: Update your password
- **Two-Factor Authentication**: Enable/disable 2FA
- **Active Sessions**: View and manage active login sessions
- **Logout All Devices**: Sign out from all devices

### Email Verification

If you haven't verified your email:

1. Go to Account Settings
2. Click "Resend Verification Email"
3. Check your inbox
4. Click the verification link

### Account Deletion

To delete your account:

1. Go to Account Settings
2. Scroll to "Danger Zone"
3. Click "Delete Account"
4. Confirm the deletion
5. All your data will be permanently deleted

## Profile Management

### Viewing Your Profile

Your profile shows:
- Profile picture and banner
- Username and display name
- Bio and location
- Number of tracks uploaded
- Number of playlists created
- Number of followers
- Number of users you're following
- Recent activity

### Editing Your Profile

1. Click on your profile picture
2. Select "Edit Profile"
3. Update any information
4. Click "Save Changes"

### Profile Completion

Complete your profile to unlock features:
- **0-25%**: Basic features only
- **25-50%**: Access to marketplace
- **50-75%**: Advanced features
- **75-100%**: All features unlocked

Check your profile completion percentage in your profile settings.

### Viewing Other Users' Profiles

1. Search for a username
2. Click on the user's profile
3. View their tracks, playlists, and activity
4. Follow them to see their updates

## Audio Tracks

### Uploading a Track

1. **Navigate to Upload**
   - Click "Upload" in the navigation menu
   - Or go to "Studio" → "Upload Track"

2. **Select Your File**
   - Supported formats: MP3, WAV, FLAC, OGG
   - Maximum file size: 500MB
   - Click "Choose File" or drag and drop

3. **Add Track Information**
   - **Title**: Track name (required)
   - **Artist**: Artist name (required)
   - **Album**: Album name (optional)
   - **Genre**: Select a genre
   - **Year**: Release year
   - **Description**: Track description (optional)

4. **Set Privacy**
   - **Public**: Visible to everyone
   - **Private**: Only visible to you
   - **Unlisted**: Accessible via direct link only

5. **Upload**
   - Click "Upload"
   - Wait for processing to complete
   - You'll receive a notification when ready

### Chunked Upload (Large Files)

For large files, use chunked upload:

1. **Initiate Upload**
   - Select "Chunked Upload" option
   - Enter file information
   - System generates upload ID

2. **Upload Chunks**
   - File is split into chunks
   - Each chunk is uploaded separately
   - Progress is tracked automatically

3. **Complete Upload**
   - Once all chunks are uploaded
   - System assembles the file
   - Processing begins automatically

### Managing Your Tracks

#### Viewing Your Tracks

1. Go to "My Tracks" or "Library"
2. See all your uploaded tracks
3. Filter by:
   - Status (processing, completed, failed)
   - Genre
   - Date uploaded
   - Privacy setting

#### Editing Track Information

1. Click on a track
2. Click "Edit"
3. Update metadata:
   - Title, artist, album
   - Genre, year
   - Description
   - Cover art
4. Click "Save Changes"

#### Deleting Tracks

1. Go to "My Tracks"
2. Select the track(s) to delete
3. Click "Delete"
4. Confirm deletion
5. Track and associated files are permanently removed

#### Batch Operations

- **Batch Delete**: Select multiple tracks and delete at once
- **Batch Update**: Update metadata for multiple tracks
- **Batch Privacy**: Change privacy settings for multiple tracks

### Track Features

#### Liking Tracks

1. Click the heart icon on a track
2. Track is added to your liked tracks
3. Click again to unlike

#### Sharing Tracks

1. Click "Share" on a track
2. Choose sharing method:
   - Copy link
   - Share on social media
   - Generate shareable token
3. Share the link with others

#### Downloading Tracks

1. Click "Download" on a track
2. If you have a license (marketplace purchase), download begins
3. If track is free, download begins immediately

#### Track Statistics

View track analytics:
- Total plays
- Unique listeners
- Average play duration
- Completion rate
- Geographic distribution
- Play over time

## Playlists

### Creating a Playlist

1. **Navigate to Playlists**
   - Click "Playlists" in navigation
   - Click "Create Playlist"

2. **Set Playlist Details**
   - **Title**: Playlist name (required, 1-200 characters)
   - **Description**: Playlist description (optional)
   - **Privacy**: Public or Private

3. **Add Tracks**
   - Search for tracks
   - Click "Add to Playlist"
   - Select your playlist
   - Or drag and drop tracks

4. **Save Playlist**
   - Click "Save"
   - Playlist is created and ready

### Managing Playlists

#### Editing Playlist Information

1. Open your playlist
2. Click "Edit"
3. Update:
   - Title
   - Description
   - Cover image
   - Privacy setting
4. Click "Save"

#### Adding Tracks to Playlist

1. Open the playlist
2. Click "Add Tracks"
3. Search and select tracks
4. Tracks are added to the end
5. Reorder by dragging tracks

#### Removing Tracks from Playlist

1. Open the playlist
2. Hover over a track
3. Click "Remove"
4. Confirm removal

#### Reordering Tracks

1. Open the playlist
2. Drag tracks to reorder
3. Changes save automatically

#### Deleting Playlists

1. Open the playlist
2. Click "Delete"
3. Confirm deletion
4. Playlist is permanently removed

### Playlist Collaboration

#### Adding Collaborators

1. Open your playlist
2. Click "Collaborators"
3. Enter username or email
4. Select permission level:
   - **Read**: Can view playlist
   - **Write**: Can add/remove tracks
   - **Admin**: Full control
5. Click "Add"

#### Managing Collaborators

- **View Collaborators**: See all collaborators
- **Change Permissions**: Update collaborator permissions
- **Remove Collaborator**: Remove access

#### Sharing Playlists

1. Click "Share" on a playlist
2. Generate share link
3. Set expiration (optional)
4. Share the link

### Playlist Recommendations

Discover playlists recommended for you:
- Based on your listening history
- Based on your liked tracks
- Based on similar users
- Based on genres you follow

## Marketplace

### Browsing the Marketplace

1. **Navigate to Marketplace**
   - Click "Marketplace" in navigation
   - Browse available products

2. **Filter Products**
   - By genre
   - By price range
   - By license type
   - By seller

3. **View Product Details**
   - Product description
   - Price and license type
   - Preview (if available)
   - Seller information

### Creating a Product

1. **Navigate to Create Product**
   - Go to "Marketplace" → "Sell"
   - Or "Studio" → "Create Product"

2. **Select Product Type**
   - **Track**: Single audio track
   - **Pack**: Collection of tracks
   - **Service**: Custom service offering

3. **Fill Product Information**
   - **Title**: Product name (required, 3-200 characters)
   - **Description**: Detailed description (optional, max 2000 characters)
   - **Price**: Set price in your currency
   - **License Type**: 
     - **Standard**: Basic usage rights
     - **Premium**: Extended usage rights
     - **Exclusive**: Full ownership transfer
   - **Track ID**: Link to your track (if product type is track)

4. **Set Product Status**
   - **Draft**: Not visible to buyers
   - **Active**: Available for purchase
   - **Archived**: No longer available

5. **Publish Product**
   - Click "Create Product"
   - Product is listed in marketplace

### Purchasing Products

1. **Browse Products**
   - Find products you want
   - Read descriptions and reviews

2. **Add to Cart** (if cart feature available)
   - Click "Add to Cart"
   - Continue shopping or checkout

3. **Purchase**
   - Click "Buy Now"
   - Review order details
   - Complete payment (Stripe integration)
   - Order is processed

4. **Download Purchased Products**
   - Go to "My Purchases"
   - Find your order
   - Click "Download"
   - File downloads to your device

### Managing Your Products

#### Viewing Your Products

- Go to "My Products" or "Seller Dashboard"
- See all your products
- Filter by status (draft, active, archived)

#### Updating Products

1. Open your product
2. Click "Edit"
3. Update information
4. Click "Save"

#### Managing Orders

- View all orders for your products
- See order details
- Track order status
- Process refunds (if applicable)

## Social Features

### Following Users

1. Visit a user's profile
2. Click "Follow"
3. You'll see their updates in your feed
4. Click "Unfollow" to stop following

### Likes and Comments

#### Liking Tracks

- Click the heart icon on any track
- Liked tracks appear in "Liked Tracks"
- Unlike by clicking the heart again

#### Commenting on Tracks

1. Open a track
2. Scroll to comments section
3. Type your comment
4. Click "Post Comment"
5. Comments are visible to all viewers

#### Managing Comments

- Edit your comments
- Delete your comments
- Report inappropriate comments

### Sharing Content

#### Sharing Tracks

1. Click "Share" on a track
2. Choose method:
   - Copy link
   - Share on social media
   - Generate QR code
3. Share with others

#### Sharing Playlists

1. Open a playlist
2. Click "Share"
3. Generate share link
4. Share the link

## Chat & Conversations

### Starting a Conversation

1. **Navigate to Chat**
   - Click "Chat" or "Messages" in navigation
   - Click "New Conversation"

2. **Select Recipient**
   - Search for username
   - Select from your followers
   - Or enter username directly

3. **Send Message**
   - Type your message
   - Press Enter or click "Send"
   - Message is delivered in real-time

### Managing Conversations

#### Viewing Conversations

- See all your conversations
- Unread messages are highlighted
- Most recent conversations appear first

#### Creating Chat Rooms

1. Click "Create Room"
2. Enter room name
3. Add participants
4. Set room permissions
5. Create room

#### Managing Chat Rooms

- **Add Members**: Invite users to room
- **Remove Members**: Remove users from room
- **Update Permissions**: Change member roles
- **Delete Room**: Permanently delete room

### Chat Features

- **Real-time Messaging**: Instant message delivery
- **File Sharing**: Share audio files in chat
- **Message History**: View past messages
- **Typing Indicators**: See when others are typing
- **Read Receipts**: Know when messages are read

## Search & Discovery

### Searching for Content

1. **Use the Search Bar**
   - Located at the top of the page
   - Type your search query
   - Results appear as you type

2. **Search Filters**
   - **Type**: Tracks, Playlists, Users
   - **Genre**: Filter by music genre
   - **Date Range**: Filter by upload date
   - **Duration**: Filter by track length
   - **Format**: Filter by audio format

3. **Advanced Search**
   - Combine multiple filters
   - Sort by relevance, popularity, date
   - Use pagination for more results

### Discovering Content

#### Browse by Genre

- Explore tracks by genre
- Discover new artists
- Find trending tracks

#### Browse by Popularity

- See most played tracks
- View trending playlists
- Discover top artists

#### Recommendations

- Personalized recommendations based on:
  - Your listening history
  - Your liked tracks
  - Similar users
  - Popular content

## Analytics

### Track Analytics

View detailed analytics for your tracks:

1. **Navigate to Analytics**
   - Go to "Analytics" → "Tracks"
   - Or click "Analytics" on a track

2. **View Statistics**
   - **Total Plays**: Number of times track was played
   - **Unique Listeners**: Number of unique users
   - **Average Duration**: Average play time
   - **Completion Rate**: Percentage of complete plays
   - **Geographic Data**: Plays by country/region
   - **Time Series**: Plays over time

3. **Export Data**
   - Export analytics as CSV
   - Generate reports
   - Share with others

### User Analytics

View your overall statistics:
- Total tracks uploaded
- Total plays across all tracks
- Total followers
- Total likes received
- Engagement metrics

### Analytics Dashboard

Access comprehensive analytics:
- Overview metrics
- Detailed breakdowns
- Visualizations and charts
- Export capabilities

## Settings & Preferences

### Account Settings

- **Profile Information**: Update personal details
- **Privacy Settings**: Control visibility
- **Security Settings**: Password, 2FA, sessions
- **Notification Preferences**: Email, push notifications

### Application Settings

- **Theme**: Light or Dark mode
- **Language**: Select preferred language
- **Timezone**: Set your timezone
- **Audio Quality**: Streaming quality preferences

### Notification Settings

Control what notifications you receive:
- **Email Notifications**: 
  - New followers
  - Track likes
  - Comments
  - Messages
- **Push Notifications**: Real-time alerts
- **In-App Notifications**: Platform notifications

## Troubleshooting

### Common Issues

#### Can't Log In

1. **Check Credentials**
   - Verify email address
   - Check password (case-sensitive)
   - Try password reset if needed

2. **2FA Issues**
   - Verify time sync on authenticator app
   - Use recovery codes if available
   - Contact support if locked out

3. **Account Locked**
   - Too many failed login attempts
   - Wait 15 minutes or contact support

#### Upload Fails

1. **Check File Format**
   - Supported: MP3, WAV, FLAC, OGG
   - Convert if needed

2. **Check File Size**
   - Maximum: 500MB
   - Use chunked upload for large files

3. **Check Internet Connection**
   - Stable connection required
   - Try again if connection drops

#### Track Not Processing

1. **Wait for Processing**
   - Processing can take time
   - Check status in "My Tracks"

2. **Check for Errors**
   - View error messages
   - Try re-uploading if failed

3. **Contact Support**
   - If issue persists
   - Provide track ID and error details

#### Can't Access Purchased Content

1. **Check Order Status**
   - Verify order completed
   - Check payment confirmation

2. **Check License**
   - Ensure license is active
   - Contact seller if issue

3. **Try Download Again**
   - Links may expire
   - Generate new download link

### Getting Help

- **Help Center**: Browse documentation
- **Contact Support**: Email support@veza.app
- **Community Forum**: Ask other users
- **Report Bug**: Submit bug reports

## Tips & Best Practices

### For Content Creators

1. **Optimize Your Profile**
   - Complete your profile
   - Add professional photos
   - Write engaging bio

2. **Upload Quality Content**
   - Use high-quality audio files
   - Add detailed metadata
   - Include cover art

3. **Engage with Community**
   - Respond to comments
   - Follow other creators
   - Collaborate on projects

4. **Promote Your Work**
   - Share on social media
   - Create playlists
   - Participate in community

### For Listeners

1. **Discover New Music**
   - Use search and filters
   - Explore recommendations
   - Follow artists you like

2. **Organize Your Library**
   - Create playlists
   - Like favorite tracks
   - Follow artists

3. **Support Artists**
   - Like and comment
   - Share tracks
   - Purchase from marketplace

## Additional Resources

- **API Documentation**: For developers integrating with Veza
- **Community Guidelines**: Rules and best practices
- **Terms of Service**: Legal terms and conditions
- **Privacy Policy**: How we handle your data
- **FAQ**: Frequently asked questions

## Support

For additional help:
- **Email**: support@veza.app
- **Documentation**: https://docs.veza.app
- **Community**: https://community.veza.app
- **Status Page**: https://status.veza.app