194 lines
24 KiB
Markdown
194 lines
24 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
ArchNest Dashboard is a 6-page custom dashboard designed as a portfolio showcase piece. It provides system health monitoring, infrastructure management, network analytics, bookmark management, an embedded SSH terminal, and user settings — all unified under a dark/gold aesthetic. The application targets deployment on AWS infrastructure as a free, open-source tool with a potential paid tier for advanced features.
|
||
|
||
## Glossary
|
||
|
||
- **Dashboard**: The ArchNest single-page application providing all 6 pages of functionality
|
||
- **Sidebar**: The fixed left navigation component (80px wide) containing the logo, nav items, and system status indicator
|
||
- **Top_Bar**: The shared header component (56px height) displaying page title, search bar, notifications, and user info
|
||
- **Hero_Banner**: A full-width banner image component shown on certain pages (Glance, Infrastructure, Network, BookNest)
|
||
- **Card**: A styled container element with 12px border radius, dark background (#141518), and 1px border (#1E2025)
|
||
- **Glance_Page**: The main operations dashboard showing system health overview at route `/`
|
||
- **Infrastructure_Page**: The cloud infrastructure monitoring page at route `/infrastructure`
|
||
- **Network_Page**: The network performance and security monitoring page at route `/network`
|
||
- **BookNest_Page**: The digital library and bookmark management page at route `/booknest`
|
||
- **Terminal_Page**: The embedded SSH terminal page at route `/terminal`
|
||
- **Settings_Page**: The user preferences and system configuration page at route `/settings`
|
||
- **Sparkline**: A small inline chart showing data trends without axes or labels
|
||
- **Progress_Ring**: A circular progress indicator displaying percentage values
|
||
- **Status_Indicator**: A colored dot (green/yellow/red) representing operational state
|
||
- **Gold_Accent**: The primary accent color (#C8A434) used for active states, links, and highlights
|
||
- **CDN**: The GitHub-hosted asset repository at `https://raw.githubusercontent.com/SamuelSJames/assets-public/master/`
|
||
- **Terminal_Bridge**: The Node.js WebSocket-to-SSH bridge service enabling browser-based terminal connections
|
||
- **Bookmark**: A stored link entry with name, URL, icon, category, and favorite status
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: Application Shell and Navigation
|
||
|
||
**User Story:** As a user, I want a consistent navigation sidebar and top bar across all pages, so that I can move between dashboard sections efficiently.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Dashboard SHALL render a fixed left Sidebar of 80px width containing the ArchNest logo, 6 navigation items (Glance, Infrastructure, Network, BookNest, Terminal, Settings) each displaying an icon at 18px and a label at 14px, a collapse/expand toggle button, and a system status indicator at the bottom showing a colored dot (green for operational, orange for degraded, red for critical) with accompanying status text.
|
||
2. WHEN a user clicks a navigation item in the Sidebar, THE Dashboard SHALL navigate to the corresponding route, highlight the active item with Gold_Accent color and a 3px left border, and remove the highlight from the previously active item.
|
||
3. WHEN a user clicks the Sidebar collapse toggle, THE Sidebar SHALL collapse to icon-only mode at 50px width (hiding labels and showing only icons), and clicking the toggle again SHALL expand the Sidebar back to 80px with labels visible.
|
||
4. THE Top_Bar SHALL display at a fixed height of 56px the current page title (bold, uppercase, 18px), a search bar (300px width, rounded), a notification bell icon, and a user avatar (36px with gold ring) with the user name and role label.
|
||
5. IF the notification count is greater than zero, THEN THE Top_Bar SHALL display a badge on the notification bell icon showing the numeric count up to 99, and "99+" for counts exceeding 99.
|
||
6. WHILE the viewport width is between 768px and 1200px, THE Sidebar SHALL auto-collapse to icon-only mode at 50px width and display a tooltip with the navigation item label when the user hovers over a navigation icon.
|
||
7. WHILE the viewport width is below 768px, THE Sidebar SHALL transform into a bottom navigation bar displaying all 6 navigation items as icons with labels below each icon, and the system status indicator SHALL be hidden.
|
||
8. IF a user navigates to an undefined route, THEN THE Dashboard SHALL redirect the user to the Glance page at the root route.
|
||
|
||
### Requirement 2: Global Design System
|
||
|
||
**User Story:** As a user, I want a cohesive dark theme with gold accents throughout the application, so that the interface is visually consistent and professional.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Dashboard SHALL use background color #0D0E10 for pages, #141518 for Cards, and #0A0B0D for the Sidebar.
|
||
2. THE Dashboard SHALL use #C8A434 as the primary Gold_Accent color for links, active states, progress bars, and interactive highlights.
|
||
3. THE Dashboard SHALL use #2ECC71 for success/operational states, #E67E22 for warnings, and #E74C3C for critical/error states.
|
||
4. THE Dashboard SHALL render text in #E8E6E0 (primary, 14px body), #7A7D85 (secondary/labels, 12-13px), and #C8A434 (accent/active elements).
|
||
5. THE Dashboard SHALL render Card titles at 12-13px, uppercase, with 1px letter-spacing in secondary color (#7A7D85), and large numbers at 28-36px bold in primary color (#E8E6E0).
|
||
6. WHEN a user hovers over a Card, THE Dashboard SHALL transition the Card border color to Gold_Accent (#C8A434) over 0.2 seconds using ease timing.
|
||
7. THE Dashboard SHALL apply 12px border radius, 1px solid #1E2025 border, 20-24px padding, and no box-shadow (flat design) to all Cards.
|
||
8. WHEN a Card or interactive element receives keyboard focus, THE Dashboard SHALL display a visible Gold_Accent (#C8A434) outline of at least 2px to meet accessibility focus indicator requirements.
|
||
|
||
### Requirement 3: Hero Banner Display
|
||
|
||
**User Story:** As a user, I want a branded hero banner on main pages, so that the dashboard has visual identity and branding.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Hero_Banner SHALL display the archnest-brand.png image from the CDN at full width (100%) of the main content area with 12px border radius, overflow hidden, and the image scaled to cover the entire banner area while maintaining its aspect ratio.
|
||
2. WHILE the Glance_Page is active, THE Hero_Banner SHALL render at 200px height.
|
||
3. WHILE the Infrastructure_Page, Network_Page, or BookNest_Page is active, THE Hero_Banner SHALL render at 120px height.
|
||
4. WHILE the Terminal_Page or Settings_Page is active, THE Dashboard SHALL hide the Hero_Banner.
|
||
5. IF the hero banner image fails to load, THEN THE Hero_Banner SHALL display the banner container at the specified height with the card background color (#141518) and no broken-image icon visible.
|
||
|
||
### Requirement 4: Glance Page — System Overview
|
||
|
||
**User Story:** As a user, I want a high-level overview of system health, resources, alerts, and network traffic on the main page, so that I can assess operational status at a glance.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Glance_Page SHALL display a top row of 4 status Cards showing: System Status (percentage 0–100% with Progress_Ring, "Last checked: Xm ago" timestamp, and a gold Sparkline at the bottom showing recent health check trend), Infrastructure (server icon + resource count + "Total Resources" subtitle + colored dot breakdown: Running/Warning/Critical), Security (shield icon + alert count + "Active Alerts" subtitle + severity breakdown: Low/Medium/High), and Network (network icon + uptime percentage + "Network Uptime" subtitle + gold area Sparkline showing 24h uptime trend).
|
||
2. THE Glance_Page SHALL display a middle row with 3 columns (30%/40%/30%): Resource Overview (card title + X close button, 5 progress bars each with an icon, label, gold fill bar, and "current / max" value), Recent Activity (card title + X close button, 5 timestamped events each showing an icon, event title, source/service subtitle, and relative timestamp), and Top Alerts (card title + "View all" link, up to 4 alerts each with severity-colored dot, alert name, source subtitle, and relative timestamp).
|
||
3. THE Glance_Page SHALL display a bottom row with 2 columns (65%/35%): Network Traffic (card title, dark area chart with gold/amber gradient fill, stats showing Incoming Gbps with percentage change and Outgoing Gbps with percentage change) and Shortcuts (card title, 4 icon buttons in a 2x2 or 1x4 grid, each with an outlined icon in a bordered container and label below: Add Server, Create Backup, Deploy App, View Logs).
|
||
4. THE Glance_Page footer SHALL display contextual stats: System Status percentage, Resource count, Alert count, and Uptime percentage, along with a "Last updated" timestamp on the right indicating time since last data refresh.
|
||
5. IF data for any status Card or section fails to load, THEN THE Glance_Page SHALL display a loading skeleton placeholder within that Card or section and not block rendering of other sections.
|
||
6. WHEN the Glance_Page loads, THE Progress_Ring and Sparkline SHALL animate their fill from 0 to the current value within 1 second.
|
||
7. WHEN a user clicks the X close button on a Card (Resource Overview or Recent Activity), THE Glance_Page SHALL hide that Card from view for the current session.
|
||
|
||
### Requirement 5: Infrastructure Page — Resource Management
|
||
|
||
**User Story:** As a user, I want to monitor cloud infrastructure resources, costs, and health across regions, so that I can manage my cloud environment effectively.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Infrastructure_Page SHALL display sub-tabs with a maximum of 4 tabs visible at once (Overview, Compute, Storage, Database) and remaining tabs (Network, Containers, Load Balancers, DNS, Backups, Tags) accessible via a scrollable overflow menu, defaulting to the Overview tab as active.
|
||
2. THE Infrastructure_Page SHALL display a top row of 5 status Cards: Total Resources (integer count with percentage trend and up/down arrow), Total Cost MTD (dollar amount formatted as $XX,XXX.XX with percentage trend), Resource Health (percentage 0–100% with trend), Active Alerts (integer count with percentage trend), and Uptime (percentage 0–100% with trend).
|
||
3. THE Infrastructure_Page SHALL display a middle row with 3 columns (30%/40%/30%): Resource Distribution (donut chart showing category name and percentage share), Infrastructure Map (dark world map with gold glowing dots at region locations and connection lines, footer showing region count, AZ count, and resource count with a "Live" indicator), and Top Resources by Utilization (ranked list of up to 5 items showing instance name, type, and percentage utilization).
|
||
4. THE Infrastructure_Page SHALL display a bottom row with 3 columns (35%/35%/30%): Resource Trend (multi-line area chart showing Compute, Storage, Database, and Network lines over a 7-day X-axis), Cost Breakdown MTD (donut chart showing service name, dollar amount, and percentage share), and Recent Activity (timestamped list of up to 5 events ordered newest-first).
|
||
5. THE Infrastructure_Page SHALL provide an "+ Add Resource" action button positioned adjacent to the sub-tabs.
|
||
6. THE Infrastructure_Page footer SHALL display contextual stats: provider name, region count, AZ count, resource count, health percentage, MTD cost, and alert count.
|
||
|
||
### Requirement 6: Network Page — Performance Monitoring
|
||
|
||
**User Story:** As a user, I want to monitor network performance, traffic patterns, and security threats, so that I can ensure network reliability and safety.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Network_Page SHALL display sub-tabs with a maximum of 4 tabs visible at once (Overview, Traffic, Topology, Devices) and remaining tabs (Interfaces, VPN, DNS, Firewalls, Load Balancers, Alerts, Reports) accessible via a scrollable overflow menu, defaulting to the Overview tab as active.
|
||
2. THE Network_Page SHALL display a top row of 6 status Cards: Network Health (percentage, 0–100%), Total Traffic (throughput in Gbps or Tbps), Packet Loss (percentage, 0–100%), Active Connections (integer count), Threats Blocked (integer count with an orange warning icon displayed when count exceeds 0), and Average Latency (value in milliseconds).
|
||
3. THE Network_Page SHALL display a middle row with 3 columns (25%/50%/25%): Top Talkers (ranked list of up to 5 items showing host name and throughput in Gbps), Network Topology (interactive map supporting click-and-drag pan, zoom in/out buttons, and a fullscreen toggle, with gold nodes and connection lines, and a legend indicating Live in green, Warning in orange, and Critical in red), and Interface Utilization (up to 5 interfaces with percentage bars) stacked with Alert Summary (counts grouped by Critical, Warning, and Info severity).
|
||
4. THE Network_Page SHALL display a bottom row with 3 columns (35%/35%/30%): Traffic Over Time (area chart with inbound, outbound, and total lines over a 24-hour X-axis from 00:00 to 24:00, Y-axis ranging from 250 Gbps to 1.5 Tbps), Protocol Distribution (donut chart showing protocol name and percentage share), and Recent Events (timestamped list of up to 5 entries, ordered newest first).
|
||
5. THE Network_Page SHALL provide a "Last 24 Hours" time-range dropdown and an "Export Report" action button positioned in the page action area adjacent to the sub-tabs.
|
||
6. THE Network_Page footer SHALL display contextual stats: region count, site count, device count, interface count, connection count, and network health percentage.
|
||
|
||
### Requirement 7: BookNest Page — Bookmark Management
|
||
|
||
**User Story:** As a user, I want to organize, access, and monitor my bookmarks by category with health status tracking, so that I can efficiently manage my digital resources.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE BookNest_Page SHALL display page stats below the title showing total link count, category count, and favorites count in the format: "🔗 {count} Links | 📁 {count} Categories | ⭐ {count} Favorites".
|
||
2. THE BookNest_Page SHALL display a Quick Access row with 5 category Cards (Infrastructure, Development, AI Tools, AWS, Networking), each showing up to 5 service icons from the CDN and the total link count for that category.
|
||
3. THE BookNest_Page SHALL display bookmark groups in 2 rows of 4 columns each: Row 1 (Infrastructure & Self Hosted, Development & Code, Lab & Networking, AWS) and Row 2 (AI Tools, Learning, Finance, Life), each group displaying up to 20 Bookmark items.
|
||
4. THE BookNest_Page SHALL display a right sidebar (25% width) with 4 widgets: Favorites list (maximum 10 items), Recently Used list showing the 5 most recently accessed Bookmarks with relative timestamps (e.g., "5m", "1h", "2h"), Link Health donut chart (Online/Warning/Offline), and Category Breakdown donut chart.
|
||
5. WHEN a user clicks the star toggle on a Bookmark item, THE BookNest_Page SHALL add or remove the Bookmark from the Favorites list and render the star icon in Gold_Accent color when favorited or in secondary text color (#7A7D85) when not favorited.
|
||
6. THE BookNest_Page SHALL render each Bookmark item with a colored icon (16-20px), name (14px), and star toggle aligned to the right.
|
||
7. THE BookNest_Page SHALL classify each Bookmark's link health as "Online" when the link responds successfully, "Warning" when the link responds with degraded performance or non-success status, or "Offline" when the link is unreachable, and display the counts in the Link Health donut chart.
|
||
8. IF a Bookmark's service icon fails to load from the CDN, THEN THE BookNest_Page SHALL display a generic fallback icon at the same dimensions (16-20px) without breaking the layout of the Bookmark item.
|
||
|
||
### Requirement 8: Terminal Page — Embedded SSH
|
||
|
||
**User Story:** As a user, I want an embedded SSH terminal in the browser with multiple session tabs, so that I can manage remote servers without leaving the dashboard.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Terminal_Page SHALL render a full-height terminal viewport using xterm.js with JetBrains Mono or Fira Code font at 14px, 5000-line scrollback, and gold block cursor with 500ms blink interval.
|
||
2. THE Terminal_Page SHALL display a tab bar (40px height) at the top showing open sessions (maximum 10 simultaneous tabs) with host name and connection Status_Indicator (green for connected, yellow for connecting, gray for disconnected), with the active tab having a gold bottom border.
|
||
3. WHEN a user clicks the "+" button in the tab bar, THE Terminal_Page SHALL display a quick-connect dropdown listing saved hosts (Pre, Proxmox, Linode, RackNerd 1, RackNerd 3, Studio).
|
||
4. WHEN a user selects a saved host from the dropdown, THE Terminal_Page SHALL initiate an SSH connection through the Terminal_Bridge with a 10-second connection timeout and open a new terminal tab displaying the host name.
|
||
5. THE Terminal_Page SHALL display a status bar (28px height) at the bottom showing connection state (Connecting, Connected, or Disconnected), host name, session duration in HH:MM:SS format, and shell type, with split-pane, fullscreen, and disconnect controls on the right.
|
||
6. THE Terminal_Page SHALL apply syntax coloring: Gold_Accent for prompts, #E8E6E0 for commands, #7A7D85 for output, #E74C3C for errors, and #1ABC9C for directories.
|
||
7. IF an SSH connection attempt fails or times out, THEN THE Terminal_Page SHALL display an error message indicating the failure reason in the terminal viewport and set the tab Status_Indicator to disconnected (gray).
|
||
8. WHEN a user clicks the close button on a terminal tab, THE Terminal_Page SHALL terminate the SSH session for that tab and remove the tab from the tab bar, switching focus to the nearest remaining tab.
|
||
9. IF the Terminal_Bridge service is unreachable, THEN THE Terminal_Page SHALL display an error message indicating the bridge is unavailable and disable the quick-connect dropdown until connectivity is restored.
|
||
|
||
### Requirement 9: Settings Page — Configuration
|
||
|
||
**User Story:** As a user, I want to configure my profile, appearance, integrations, and notification preferences, so that I can personalize the dashboard experience.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Settings_Page SHALL display a left navigation panel (200px) with sections: Profile, Appearance, Integrations, Notifications, Data & Backup, and About, with the active section highlighted using Gold_Accent color.
|
||
2. THE Settings_Page Profile section SHALL display editable fields for avatar (64px with gold ring), display name (maximum 50 characters), role (maximum 30 characters), email (validated for standard email format), and timezone (selectable from standard timezone list), with a "Save Changes" button.
|
||
3. THE Settings_Page Appearance section SHALL provide: a Dark/Light theme toggle, accent color swatches (Gold, Teal, Purple, Blue, Green, Red), a font size slider (12-16px in 1px increments), a sidebar expanded/collapsed toggle, an animations on/off toggle, and a card border radius slider (4-16px in 1px increments).
|
||
4. THE Settings_Page Integrations section SHALL display configuration Cards for Proxmox, Docker, NetBird, Cloudflare, AWS, Uptime Kuma, and Weather API, each with a Status_Indicator (green for connected, red for disconnected), configuration fields, masked secrets with eye toggle for visibility, and a "Test Connection" button.
|
||
5. WHEN a user clicks "Test Connection" on an integration Card, THE Settings_Page SHALL display a loading state during the connection attempt and then show a success indicator if the connection succeeds within 10 seconds.
|
||
6. IF a "Test Connection" attempt fails or times out after 10 seconds, THEN THE Settings_Page SHALL display an error indicator with a message describing the failure reason.
|
||
7. THE Settings_Page Notifications section SHALL provide toggles for enable/disable, threshold selection (All/Critical/Warning+), email notifications, browser push notifications, and sound with volume slider (0-100%).
|
||
8. THE Settings_Page Data & Backup section SHALL provide actions for Export Bookmarks (JSON), Import Bookmarks (accepting JSON files up to 5MB), Export Settings, Reset to Defaults, and Clear Cache.
|
||
9. WHEN a user clicks "Reset to Defaults", THE Settings_Page SHALL display a confirmation dialog requiring explicit user confirmation before executing the reset, and SHALL not proceed if the user dismisses or cancels the dialog.
|
||
10. THE Settings_Page About section SHALL display application version, author name, repository link, technology stack, and license information.
|
||
|
||
### Requirement 10: Responsive Layout
|
||
|
||
**User Story:** As a user, I want the dashboard to adapt to different screen sizes, so that I can use the application on desktop, tablet, and mobile devices.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHILE the viewport width exceeds 1200px, THE Dashboard SHALL render the full layout with expanded Sidebar (80px), multi-column Card grids (up to 6 columns per row as defined per page), and all widgets visible.
|
||
2. WHILE the viewport width is between 768px and 1200px, THE Dashboard SHALL collapse the Sidebar to icon-only mode (50px), arrange status Card rows in 2-column grids, and stack middle/bottom row columns vertically where they exceed 2 columns.
|
||
3. WHILE the viewport width is below 768px, THE Dashboard SHALL replace the Sidebar with a bottom navigation bar (56px height), arrange all Cards in single-column layout, and hide the BookNest right sidebar widgets in favor of a toggleable overlay.
|
||
4. THE Dashboard SHALL support a minimum viewport width of 320px without horizontal scrolling or content overflow.
|
||
|
||
### Requirement 11: Asset Loading from CDN
|
||
|
||
**User Story:** As a user, I want dashboard assets (logos, banners, service icons) to load reliably from the CDN, so that the interface renders correctly with all visual elements.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Dashboard SHALL load the ArchNest logo from `logos/brands/archnest-logo.png` on the CDN for the Sidebar.
|
||
2. THE Dashboard SHALL load the hero banner image from `backgrounds/archnest-brand.png` on the CDN.
|
||
3. THE BookNest_Page SHALL load service icons from the CDN repository for the following services: Proxmox, GitHub, GitLab, Gitea, AWS, Docker, Cloudflare, NetBird, CasaOS, Portainer, Cockpit, ChatGPT, Claude, GNS3, EVE-NG, and Wireshark.
|
||
4. IF a CDN asset does not produce a successful image load event within 10 seconds, THEN THE Dashboard SHALL treat the asset as failed and render a fallback placeholder element that occupies the same dimensions as the intended asset, preserving the surrounding layout without visible reflow.
|
||
5. IF a CDN asset fails to load, THEN THE Dashboard SHALL display a generic icon placeholder for service icons (matching the 16-20px icon size) or a solid background fill matching the Card background color for banner and logo assets.
|
||
|
||
### Requirement 12: State Management
|
||
|
||
**User Story:** As a user, I want my preferences, session data, and UI state to persist across navigation, so that the dashboard remembers my context.
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. THE Dashboard SHALL use Zustand for global state management of user preferences, active sessions, navigation state, and bookmark data.
|
||
2. WHEN a user changes a setting in the Settings_Page, THE Dashboard SHALL persist the change to local storage and apply the setting to the UI within 100 milliseconds without triggering a full page reload.
|
||
3. WHEN a user navigates between pages, THE Dashboard SHALL preserve and restore terminal session scrollback buffers, scroll positions (to the nearest pixel), and active sub-tab selections so that returning to a previously visited page displays the same state the user left.
|
||
4. WHEN the Dashboard loads and local storage contains previously persisted state, THE Dashboard SHALL restore user preferences, theme settings, sidebar expansion state, bookmark favorites, notification preferences, and active sub-tab selections from the stored data within 200 milliseconds of app initialization.
|
||
5. IF local storage is unavailable or the storage quota is exceeded, THEN THE Dashboard SHALL continue operating with in-memory state for the current session and display an indicator in the Settings_Page that persistence is degraded.
|
||
6. IF stored state fails validation or is corrupt, THEN THE Dashboard SHALL discard the invalid data, apply default values for all preferences, and operate normally without displaying an error to the user.
|