Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
101 lines (80 loc) · 3.4 KB

ARCHITECTURE.md

File metadata and controls

101 lines (80 loc) · 3.4 KB
Raw

Technical Architecture 🏗️

This document provides a deep dive into the internal mechanics of the AI-Driven Process Recommendation System.

🏗️ System Architecture

The system follows a decoupled Client-Server architecture:

graph TD
    subgraph "Frontend (Single File)"
        UI[React Dashboard]
        Charts[Real-time Charts]
        Actions[Action Triggers]
    end

    subgraph "Backend (Flask)"
        API[REST API]
        Cache[Process Cache Thread]
        RuleEngine[Rule Engine v1]
        MLEngine[ML Engine v2]
        ProcManager[psutil Manager]
    end

    subgraph "Storage"
        Model[process_model.pkl]
        Meta[model_metadata.json]
    end

    UI <--> API
    API <--> Cache
    Cache <--> ProcManager
    API <--> RuleEngine
    API <--> MLEngine
    MLEngine <--> Model
    MLEngine <--> Meta
Loading

🧠 Recommendation Engines

v1.0: Deterministic Rule Engine

The rule engine uses a prioritized list of heuristics to make recommendations:

  1. User Overrides: Checks for manual labels first.
  2. Protection: Targets "System" processes for prioritize.
  3. Thresholds:
    • CPU > 70% | Memory > 30% → terminate
    • CPU > 40% | Memory > 15% → pause
    • CPU > 20% | Memory > 8% → monitor
    • Default → monitor

v2.0: Machine Learning (Random Forest)

When enough data is collected, the system switches to a RandomForestClassifier.

  • Features Extracted:
    • cpu_percent: Resource usage.
    • memory_percent: RAM impact.
    • category: Categorical integer (System=0, Browser=1, etc.).
    • num_threads: Process complexity.
    • user_label: Historical importance assigned by user.
  • Workflow:
    1. Feature vectors are normalized.
    2. Model is trained on labeled snapshots.
    3. predict_proba() is used to provide a confidence score.

⚡ Backend Optimization

Background Caching

To prevent slow system calls (like psutil.process_iter) from blocking the UI, the backend runs a dedicated refresh thread.

  • Refreshes every 2 seconds.
  • Uses a threading.Lock to ensure atomic updates to the shared _cache object.
  • API requests always return the latest cached data instantly (~1ms response time).

Process Tree Resolution

When an action (Kill/Pause) is triggered on a PID:

  1. The system identifies all child processes recursively.
  2. Termination Logic: Kills children first (bottom-up), then the parent, to prevent orphaned processes.
  3. Resume Logic: Resumes the parent first, then children, to ensure the main thread is ready to receive data.

🎨 Frontend Design

The dashboard uses a Modern Glassmorphism aesthetic:

  • Style: Semi-transparent backgrounds (rgba), backdrop filters (blur), and subtle borders.
  • Interactivity: Hover effects, smooth transitions, and "shimmer" loading skeletons.
  • Responsiveness: Grid-based layout that adapts to various screen sizes.
  • Performance: Single-file delivery using Babel Standalone for minimal setup overhead.

🛡️ Security & Reliability

  • CORS Enabled: Allows development from separate frontend servers.
  • Error Boundaries: Handles AccessDenied or NoSuchProcess errors gracefully (common when interacting with restricted system processes).
  • Persistence: Metadata is saved to disk so accuracy metrics survive server restarts.

Documentation Version: 1.1