Skip to content

Latest commit

 

History

History
254 lines (177 loc) · 9.34 KB

ARCHITECTURE.md

File metadata and controls

254 lines (177 loc) · 9.34 KB

Architecture

Overview

System Health Tool is a Tauri 2 desktop app with a Rust backend and a React frontend. The frontend keeps the shell, layout, and presentation logic in TypeScript while the Rust backend owns the real system operations.

The important architectural rule is still the same:

  • src/lib/api.ts is the only frontend layer that talks to the backend.
  • Screen hooks call api.ts.
  • Screen components render UI from hook state.
  • Shared primitives keep the five screens visually and structurally consistent.

Runtime topology

flowchart LR
    subgraph Shell ["App shell"]
        App["App.tsx"]
        Nav["NavRail"]
        Pages["Active screen"]
    end

    subgraph Frontend ["Frontend layers"]
        Hooks["Screen hooks"]
        UI["Shared UI primitives"]
        Api["api.ts"]
        Mock["mockApi.ts<br/>(browser preview only)"]
    end

    subgraph Backend ["Rust commands"]
        Disk["disk.rs"]
        Memory["memory.rs"]
        Startup["startup.rs"]
        Cleanup["cleanup.rs"]
        Recommendations["recommendations.rs"]
    end

    App --> Nav
    App --> Pages
    Pages --> UI
    Pages --> Hooks
    Hooks --> Api
    Api --> Mock

    Api -- "invoke()" --> Disk
    Api -- "invoke()" --> Memory
    Api -- "invoke()" --> Startup
    Api -- "invoke()" --> Cleanup
    Api -- "invoke()" --> Recommendations
Loading

Frontend structure

Shell

src/App.tsx is intentionally thin:

  • owns the Tab state
  • renders the left nav rail on desktop widths
  • renders a compact horizontal tab fallback on smaller widths
  • switches the active screen with a small framer-motion transition

src/components/layout/NavRail.tsx is the only shell-level layout component today. It owns branding, navigation labels, and the desktop left rail.

Error boundary

src/components/ErrorBoundary.tsx wraps the entire app in main.tsx. If a React render crash occurs, it catches the error and displays a styled recovery screen with the error message and a reload button, instead of a blank white page.

Shared UI primitives

The shared layer lives in src/components/ui/:

  • PageHeader gives every screen the same top command bar pattern.
  • MetricCard standardizes KPI presentation.
  • SectionCard standardizes section framing and headers.
  • DataRow standardizes dense review/list rows.
  • StatusBadge, ProgressBar, AppCheckbox, and AppSwitch wrap the most repeated controls.
  • Tooltip wraps Radix UI tooltips with the app's dark theme styling. Used for truncated paths and commands instead of native title attributes.
  • LoadingState, EmptyState, and StickyActionBar cover the common state and workflow patterns.

This is the main reason the screen files are shorter and more maintainable than the previous design.

Screen hooks

Each major screen now owns its data flow in a dedicated hook:

  • useDashboardData
  • useDiskCleanup
  • useMemoryData
  • useStartupData
  • useRecommendations

These hooks:

  • fetch data
  • compute derived metrics
  • expose user actions
  • expose an error field so screens can render failure states
  • keep the React components mostly declarative

Error handling

All five hooks follow the same pattern for error handling:

  1. Wrap the initial boot() call in try/catch.
  2. Wrap refresh() in try/catch.
  3. Store the error message in an error state field.
  4. Clear error on retry/refresh before re-fetching.
  5. Return error so the screen component can decide how to render it.

Each screen renders errors differently depending on context:

  • Loading + error: Shows an EmptyState with the error message and a retry button.
  • Loaded + refresh error: Shows a warning banner above existing data (data becomes stale but still visible).
  • Action error (e.g., toggle failure): Shows an inline error banner near the action.

The ErrorBoundary catches uncaught render errors at the top level.

API contract

src/lib/api.ts preserves the frontend contract and chooses the correct runtime path:

  • In the real Tauri runtime, it calls Rust commands through invoke().
  • In browser-only dev mode, it uses src/lib/mockApi.ts so the UI can be previewed and browser-tested without a native backend.

This fallback exists for frontend iteration only. The Rust backend remains the source of truth for real cleanup, memory, startup, and recommendation behavior.

Recommendation action types

The Recommendation.action_type field uses a typed union:

Value Behavior
navigate_disk CTA navigates to the Disk Cleanup screen.
navigate_memory CTA navigates to the Memory screen.
navigate_startup CTA navigates to the Startup screen.
info No navigation CTA; shows an "Info" badge instead.

New action types must be added to the RecommendationAction union in src/lib/types.ts and handled in the getAction() switch in Recommendations.tsx.

Browser preview limitations

The mock API (src/lib/mockApi.ts) covers most normal flows but has limitations:

  • Cannot simulate backend errors (all mock calls succeed).
  • Returns an empty recommendation list when the system is healthy, which exercises the empty state. But it cannot produce action_type: "info" rows since the mock logic does not emit them.
  • Process kill always succeeds for non-system processes.

Use npm run tauri:dev to test real backend behavior.

Screen behavior

Overview

Dashboard.tsx is an operational summary screen:

  • health score is computed client-side from drive pressure, memory pressure, startup load, and cleanup opportunities
  • quick clean still submits only risk === "safe" items
  • drive capacity rows stay visible as a stable storage overview
  • States: loading, error (banner above metrics), healthy (no alerts), quick-cleaning (button loading state)

Disk Cleanup

DiskCleanup.tsx is a review workflow, not just a list:

  • auto-scans on mount
  • preselects safe items
  • separates filtering from selection
  • keeps grouped cleanup targets inside accordions
  • submits itemIds and itemPaths together to cleanItems()
  • States: scanning, scan error (retry surface), review, cleaning (dedicated progress screen), done (result log)

Memory

MemoryPanel.tsx is an inspector layout:

  • summary metrics at the top
  • process table in the primary column
  • category mix, VM inventory, and problem-process sections in the secondary column
  • kill actions remain disabled in the UI for system processes (shows "Protected" label)
  • VM and problem process accordions auto-open when they contain actionable items
  • States: loading, load error (retry surface), loaded, refresh error (stale-data banner)

Startup

StartupManager.tsx is a grouped operations list:

  • entries grouped by impact
  • recommendation badges stay visible
  • toggles keep using opaque backend IDs so reversibility is preserved
  • States: loading, load error (retry surface), empty (no entries), loaded, toggle error (inline banner)

Recommendations

Recommendations.tsx is an action queue:

  • priority groups are rendered by severity
  • CTA buttons map to tab navigation; info-only rows show an "Info" badge
  • refresh stays manual because generating recommendations is relatively expensive
  • States: loading, load error (retry surface), empty (healthy), loaded, refresh error (stale-data banner)

Data flow

Overview

  1. useDashboardData loads drives, memory, startup items, and disk scan data.
  2. The hook computes health score and summary alerts.
  3. Quick Clean filters to safe items only and refreshes the overview after cleanup.

Disk Cleanup

  1. useDiskCleanup scans on mount.
  2. Safe items are preselected.
  3. The current filter changes visible groups only.
  4. Cleanup submits paired itemIds and itemPaths.
  5. The completion screen renders the per-item result log from CleanupSummary.

Memory

  1. useMemoryData loads RAM info, process list, and VM info in parallel.
  2. The hook groups processes by category and derives zombie/process heuristics.
  3. Killing a process refreshes the memory snapshot.

Startup

  1. useStartupData loads startup entries.
  2. Toggling an item calls toggleStartupItem(id, enable).
  3. The frontend updates local state optimistically after a successful response.

Recommendations

  1. useRecommendations loads the recommendation list once on mount.
  2. Results are sorted into severity groups.
  3. CTA buttons switch tabs in the shell instead of duplicating remediation flows.

Backend command map

Module Commands Notes
disk.rs scan_disk, get_drive_info Enumerates cleanup targets and drive capacity.
memory.rs get_memory_info, get_processes, kill_process, get_vm_info Handles RAM stats, process inventory, kill actions, and VM discovery.
startup.rs get_startup_items, toggle_startup_item Reads from registry/startup folders and toggles launch-on-sign-in state.
cleanup.rs clean_items Executes the actual cleanup and returns per-item results.
recommendations.rs get_recommendations Generates prioritized actions from live system state.

Validation strategy

Current validation has two layers:

  • Browser preview validation through mockApi.ts for layout, interaction, and automated UI checks.
  • Real Tauri validation through npm run tauri:dev for any behavior that touches the actual system.

That split keeps frontend iteration fast without weakening the real command contract.