## User's Guide to the Loxation UI

# Overview
Loxation is a decentralized mesh communication app with location-based features. The interface consists of a tabbed iOS application with multiple views for chat, profiles, groups, and location services.

## Main Navigation - Tab Bar (Bottom)
The app uses a 6-tab bottom navigation bar:

### 1. **Map Tab** 🗺️
- **Icon**: Blue map icon
- **Function**: Location-based view showing beacons, peers, and location context
- **Features**:
  - Interactive map with peer and beacon locations
  - Filter controls (All, Connected, Nearby, By Location)
  - Location following toggle
  - Beacon scanning integration

### 2. **Profile Tab** 👤
- **Icon**: Person circle icon
- **Function**: Your personal profile management
- **Features**:
  - Dynamic profile fields (username, emojis, photos, etc.)
  - Tabbed interface for different profile sections
  - Photo upload and management
  - Profile synchronization with server

### 3. **Chat Tab** 💬
- **Icon**: Message bubble icon
- **Function**: Main chat interface for public messaging
- **Features**:
  - Public chat room with all connected peers
  - Message history with encryption indicators
  - Command system (/block, /hug, /msg, etc.)
  - Attachment support (photos, files)

### 4. **Groups Tab** 👥
- **Icon**: Three people icon
- **Function**: MLS-encrypted group chat management
- **Features**:
  - Join/leave groups by ID
  - Group member management
  - Encrypted group messaging
  - Group invitation system

### 5. **TOTP Tab** 🔑
- **Icon**: Key icon
- **Function**: Time-based One-Time Password authentication
- **Features**:
  - TOTP code generation and management
  - Secure authentication integration

### 6. **Filters Tab** 🛡️
- **Icon**: Lock shield icon
- **Function**: Peer filtering and privacy controls
- **Features**:
  - Peer visibility preferences
  - Favorite peer management
  - Connection state filtering

## Detailed Interface Guide

### Main Chat View (Chat Tab)
**Layout Components:**
- **Header Bar**: Contains app name, user display name with emojis, peer count, and settings gear
- **Message Area**: Scrollable chat with message bubbles, timestamps, and encryption status
- **Input Bar**: Text field with attachment, photo, and camera buttons (iOS)

**Interactions:**
- **Triple-tap message area**: Clear chat history
- **Long-press messages**: Show actions menu (private message, hug, slap, block)
- **Command system**: Type `/` for autocomplete suggestions
- **@mentions**: Type `@` for peer name autocomplete

### Sidebar (Left Slide-out)
**Access**: Drag from left edge or tap peer count in header

**Sections:**
- **NETWORK Header**: App status indicator
- **GROUPS Section**: 
  - Lists joined groups with unread indicators
  - Tap to open group chat
- **PEOPLE Section**:
  - Shows connected peers with status icons
  - Connection indicators: 🔵 Mesh, 🌐 Nostr, ⚫ Offline
  - Unread message indicators
  - Encryption status icons

**Peer Row Interactions:**
- **Single tap**: Open private chat with peer
- **Double tap**: View encryption fingerprint
- **Long press**: View peer's profile (read-only)
- **Star button**: Toggle favorite status

### Private Chat View
**Access**: From sidebar or message actions menu

**Layout:**
- **Header**: Peer info with transport icon, name, encryption status
- **Message Area**: Private conversation with delivery status
- **Input Bar**: Same as main chat

**Header Interactions:**
- **Tap center**: View encryption fingerprint
- **Long press center**: View peer's profile
- **Back button**: Return to main chat
- **Notes button**: Open notes for this peer
- **Block/Report buttons**: Moderation actions
- **Star button**: Toggle favorite

### Group Chat View
**Access**: From sidebar groups list

**Layout:**
- **Header**: Group name, member count button
- **Message Area**: Group conversation
- **Input Bar**: Same as main chat

**Features:**
- **Member management**: Tap member count to view/add/remove members
- **Encrypted messaging**: MLS-based group encryption

### Profile Management
**Your Profile (Profile Tab):**
- **Edit Mode**: Full editing capabilities with save functionality
- **Display Mode**: Read-only view of your profile
- **Tabbed Interface**: Organized profile sections
- **Photo Management**: Upload and manage profile photos

**Peer Profiles:**
- **Access**: Long-press in private chat header or people list
- **Read-only**: View peer's profile information
- **No editing**: Cannot modify other users' profiles

### Location Map View (Map Tab)
**Layout:**
- **Map Area**: Interactive MapKit view with annotations
- **Control Overlay**: Filter and location buttons (top)
- **Navigation Bar**: Title and scan button

**Features:**
- **Peer Annotations**: Shows connected peers on map
- **Beacon Annotations**: Displays location beacons
- **Filtering**: Filter by connection type, proximity, location
- **Location Following**: Toggle to follow your location

**Map Controls:**
- **Filter Button**: Access filtering options
- **Location Button**: Toggle location following
- **Annotations**: Tap to view peer/beacon details

### Notes System
**Access**: Notes button in private chat header

**Features:**
- **Private Notes**: Per-peer note storage
- **Search Functionality**: Search through notes
- **Attachment Support**: Add photos and files to notes
- **Edit/Delete**: Long-press notes for actions

**Note Management:**
- **Add Notes**: Type in the input area
- **Edit Notes**: Tap existing note to edit
- **Delete Notes**: Long-press for delete option
- **Search**: Use search bar to filter notes

### Security & Verification
**Fingerprint View:**
- **Access**: Tap in private chat header or double-tap in people list
- **Features**:
  - Compare encryption fingerprints
  - Mark as verified
  - Block user option
  - Copy fingerprint to clipboard

**Verification Process:**
- Compare your fingerprint with peer's fingerprint
- Mark as verified if they match
- Block if verification fails

### Settings and Configuration
**Access**: Gear icon in main header

**Features:**
- **Peer Filters**: Configure who can see you
- **Privacy Settings**: Connection and visibility preferences
- **App Information**: Version, legal information

## Interaction Patterns

### Gestures
- **Drag from left**: Open sidebar
- **Long press**: Context actions (profiles, message actions)
- **Double tap**: Quick actions (fingerprints, clear chat)
- **Triple tap**: Administrative actions (clear data, panic)

### Visual Indicators
- **Connection Status**:
  - 🔵 Blue dot: Mesh connected
  - 🌐 Purple globe: Nostr available
  - ⚫ Black circle: Offline
- **Encryption Status**:
  - 🛡️ Shield: Verified encryption
  - 🔒 Lock: Secured connection
  - 🔶 Orange: Handshaking
  - 🔴 Red: Unencrypted
- **Message Status**:
  - Envelope icon: Unread messages
  - Check marks: Delivery confirmation

### Command System
Type `/` in chat for available commands:
- `/emojis [emojis]` - Set your display emojis
- `/m [nickname] [message]` - Send private message
- `/msg [nickname] [message]` - Alternative private message
- `/w` - Show who's online
- `/clear` - Clear chat messages
- `/hug [nickname]` - Send virtual hug
- `/slap [nickname]` - Playful interaction
- `/block [nickname]` - Block/unblock peers
- `/unblock [nickname]` - Unblock a peer
- `/fav [nickname]` - Add to favorites
- `/unfav [nickname]` - Remove from favorites
- `/join [groupId] [welcomeB64]` - Join group chat
- `/leave` - Leave current group
- `/invite [nickname] [groupId]` - Invite to group
- `/groups` - List joined groups
- `/members [groupId]` - List group members
- `/report [nickname]` - Report a user
- `/removechat [nickname]` - Remove private chat
- `/wipe` - Clear all local data

## Advanced Features

### Group Management
**Member Controls:**
- **Add Members**: Select from eligible peers (BLE connected or mutual favorites)
- **Remove Members**: Remove selected members (admins only)
- **Admin Promotion**: Promote members to admin status
- **Leave Groups**: Leave groups (with admin succession rules)

**Group Policies:**
- Only admins can add/remove members
- Sole admin must promote successor before leaving
- Leaving as only member removes group locally

### Notes System
**Per-Peer Notes:**
- Private notes for each peer
- Search functionality across all notes
- Attachment support (photos, files)
- Edit and delete capabilities

**Note Attachments:**
- **Camera**: Take photos for notes
- **Photo Library**: Add existing photos
- **File Import**: Attach documents and files
- **Image Display**: View attached images inline

### Security Features
**Encryption Verification:**
- Compare fingerprints with peers
- Mark connections as verified
- Block unverified or suspicious connections
- Report malicious users

**Privacy Controls:**
- Block/unblock peers
- Favorite system for trusted connections
- Connection state filtering
- Profile visibility management

## Error Handling and States
- **Offline Mode**: Limited functionality when server unavailable
- **Connection Issues**: Visual indicators for peer connectivity
- **Permission Prompts**: Location and notification permissions
- **Loading States**: Progress indicators for data loading

## Accessibility
- **VoiceOver Support**: All interactive elements labeled
- **Dynamic Type**: Text scales with system settings
- **High Contrast**: Color choices maintain accessibility
- **Keyboard Navigation**: Full keyboard support on iPad/macOS

This interface provides a comprehensive mesh communication experience with location awareness, encrypted messaging, and flexible peer management capabilities.