# Requirements Document ## Introduction This feature addresses multiple critical issues with the SamCloud dashboard including broken download functionality, inaccurate system information display, poor share management UX, and missing service/device monitoring. The goal is to create a fully functional, real-time dashboard that accurately reflects the Mac Mini server's current state and provides seamless file sharing capabilities. ## Requirements ### Requirement 1: Fix Bulk Download Functionality **User Story:** As a user accessing shared files, I want to download all files as a ZIP archive so that I can efficiently retrieve multiple files at once. #### Acceptance Criteria 1. WHEN a user visits a share page THEN the system SHALL display a "Download All as ZIP" button 2. WHEN a user clicks "Download All as ZIP" THEN the system SHALL create a ZIP archive containing all shared files 3. WHEN the ZIP creation is in progress THEN the system SHALL show a progress indicator 4. WHEN the ZIP is ready THEN the system SHALL automatically start the download 5. IF the ZIP creation fails THEN the system SHALL display an error message with retry option ### Requirement 2: Improve Share Management UX **User Story:** As a user managing file shares, I want the share links to be immediately available without refreshing and I want to track who accesses my shares so that I can monitor usage and security. #### Acceptance Criteria 1. WHEN a user creates a new share THEN the share link SHALL appear immediately in the share management interface 2. WHEN a user creates a share THEN the system SHALL update the share list in real-time without requiring a page refresh 3. WHEN a user deletes a share THEN the share SHALL be removed from the interface immediately 4. WHEN the share management page loads THEN all existing shares SHALL be displayed with their current status 5. WHEN someone accesses a share link THEN the system SHALL log the visitor's IP address and timestamp 6. WHEN a user views share details THEN the system SHALL display access history including IP addresses, timestamps, and download counts 7. WHEN share access occurs THEN the system SHALL update the access count and history in real-time ### Requirement 3: Fix Mac Mini System Information Display **User Story:** As a system administrator, I want accurate real-time system information displayed throughout the dashboard so that I can monitor the server's current state. #### Acceptance Criteria 1. WHEN the dashboard loads THEN the system SHALL display accurate macOS version information 2. WHEN the Mac Mini header loads THEN the OrbStack uptime SHALL remain in the Mac Mini icon area 3. WHEN the system overview and top bar load THEN they SHALL show the Mac Mini system boot uptime (not container uptime) 4. WHEN the dashboard loads THEN the system SHALL display accurate storage information with current usage 5. WHEN the dashboard loads THEN the system SHALL show real Mac Mini hardware specifications 6. WHEN system information changes THEN the display SHALL update automatically every 5 seconds ### Requirement 4: Replace Duplicate CPU Widget **User Story:** As a user viewing system metrics, I want unique and useful information in each widget so that I can get comprehensive system insights without redundancy. #### Acceptance Criteria 1. WHEN the dashboard displays system widgets THEN there SHALL be no duplicate CPU usage displays 2. WHEN the bottom-right widget is displayed THEN it SHALL show unique Mac-specific system information 3. WHEN the new widget loads THEN it SHALL display information like disk I/O, network activity, or system processes 4. WHEN the widget updates THEN it SHALL refresh every 5 seconds with current data ### Requirement 5: Implement OrbStack Services Monitoring **User Story:** As a system administrator, I want to see running OrbStack containers and services so that I can monitor the containerized applications on my Mac Mini. #### Acceptance Criteria 1. WHEN OrbStack is running THEN the system SHALL display a list of active containers 2. WHEN containers are running THEN the system SHALL show container names, status, and resource usage 3. WHEN no containers are running THEN the system SHALL display "No containers found" message 4. WHEN container status changes THEN the display SHALL update automatically 5. IF OrbStack is not installed THEN the system SHALL display appropriate message ### Requirement 6: Implement Connected Network Devices Detection **User Story:** As a network administrator, I want to see devices connected to my Mac Mini server so that I can monitor network activity and connected clients. #### Acceptance Criteria 1. WHEN the dashboard loads THEN the system SHALL scan for connected network devices 2. WHEN devices are found THEN the system SHALL display device IP addresses, hostnames, and connection types 3. WHEN SMB shares are active THEN the system SHALL show connected SMB clients 4. WHEN SSH connections exist THEN the system SHALL display active SSH sessions 5. WHEN screen sharing is active THEN the system SHALL show VNC connections 6. WHEN no devices are connected THEN the system SHALL display "No devices connected" message 7. WHEN device status changes THEN the list SHALL update every 30 seconds ### Requirement 7: Enhanced File Browser Integration **User Story:** As a user managing files, I want seamless integration between the dashboard file browser and external FileBrowser service so that I have consistent file management capabilities. #### Acceptance Criteria 1. WHEN FileBrowser service is available THEN the system SHALL use it for file operations 2. WHEN FileBrowser service is unavailable THEN the system SHALL fall back to internal file browser 3. WHEN browsing files THEN the system SHALL hide macOS metadata files (._*) by default 4. WHEN uploading files THEN the system SHALL show progress indicators 5. WHEN file operations complete THEN the system SHALL refresh the file list automatically ### Requirement 8: System Process and Resource Monitoring **User Story:** As a system administrator, I want detailed process and resource monitoring so that I can identify performance bottlenecks and resource usage patterns. #### Acceptance Criteria 1. WHEN the dashboard loads THEN the system SHALL display top CPU-consuming processes 2. WHEN the dashboard loads THEN the system SHALL show memory usage by process 3. WHEN the dashboard loads THEN the system SHALL display disk I/O statistics 4. WHEN the dashboard loads THEN the system SHALL show network interface statistics 5. WHEN resource usage changes THEN the displays SHALL update every 10 seconds ### Requirement 9: Enhanced Weather Integration **User Story:** As a user, I want location-aware weather information integrated into my dashboard so that I can see relevant environmental conditions. #### Acceptance Criteria 1. WHEN the dashboard loads THEN the system SHALL display current weather for the server location 2. WHEN weather data is available THEN the system SHALL show temperature, conditions, and forecast 3. WHEN weather data updates THEN the display SHALL refresh every 30 minutes 4. WHEN weather service is unavailable THEN the system SHALL show cached data or appropriate message ### Requirement 10: Advanced Logging and Monitoring **User Story:** As a system administrator, I want comprehensive logging and monitoring capabilities so that I can track system events and troubleshoot issues. #### Acceptance Criteria 1. WHEN system events occur THEN the system SHALL log them with timestamps and details 2. WHEN users access the system THEN login attempts SHALL be logged with IP addresses 3. WHEN file operations occur THEN they SHALL be logged with user and file details 4. WHEN errors occur THEN they SHALL be logged with stack traces and context 5. WHEN viewing logs THEN users SHALL be able to filter by date, type, and severity