docs: add diagrams to project report

[adnan275]

Sentinel: Project Report

AI-Powered File Organization & Cleanup Agent

---

1. Abstract

Sentinel is an intelligent, local-first AI agent designed to automate the organization and cleanup of file systems. Traditional file management tools rely on rigid rules and manual intervention. Sentinel bridges this gap by leveraging local Large Language Models (LLMs) via Ollama, combined with deterministic execution rules. This ensures that the system can intuitively categorize files, detect duplicates, and suggest optimal organization plans, all while strictly prioritizing user data safety and system integrity.

2. Introduction

As digital storage capacities grow, users accumulate thousands of files, leading to cluttered directories, duplicated content, and wasted disk space. Manually organizing these files is a tedious and time-consuming task. Sentinel acts as a smart assistant that scans your file system, understands the context and content of your files, and proposes a comprehensive cleanup and organization plan. Built with a focus on local execution, Sentinel ensures that your personal data never leaves your machine.

3. Problem Statement

• Cluttered Workspaces: Users struggle with unorganized folders (like Downloads or Desktop) filled with mixed file types (installers, screenshots, old archives).
• Redundant Data: Duplicate files consume valuable storage space without the user's knowledge.
• Privacy Concerns: Cloud-based cleanup tools require uploading file metadata or content to external servers, posing significant privacy risks.
• Risk of Data Loss: Automated scripts can accidentally delete important system files or personal documents.

4. Objectives

• Intelligent Classification: Automatically detect and categorize files (e.g., old installers, archives, media, duplicates).
• AI-Driven Planning: Generate smart, context-aware file organization plans without executing them blindly.
• Strict Safety: Ensure no destructive actions (like permanent deletion) occur without explicit user approval.
• Local First: Maintain 100% data privacy by running the AI models locally.
• Accessibility: Provide multiple interfaces (CLI, Web Dashboard, Desktop App) to cater to different user preferences.

5. System Architecture

Sentinel operates on a modular architecture divided into several key layers. The following diagram illustrates the high-level architecture and how different components interact:

graph TB
    subgraph "User Interfaces"
        CLI[CLI - Typer]
        WEB[Web UI - Next.js]
        DESKTOP[Desktop - Tauri]
    end
    
    subgraph "API Layer"
        API[FastAPI + WebSockets]
    end
    
    subgraph "Core Engine"
        SCANNER[Scanner]
        CLASSIFIER[File Classifier]
        RULES[Rules Engine]
        PLANNER[AI Planner]
        SAFETY[Safety Validator]
        EXECUTOR[Executor]
    end
    
    subgraph "External Services"
        OLLAMA[Ollama - Local LLM]
        DB[(SQLite DB)]
    end
    
    CLI --> API
    WEB --> API
    DESKTOP --> API
    
    API --> SCANNER
    SCANNER --> CLASSIFIER
    CLASSIFIER --> RULES
    RULES --> PLANNER
    PLANNER --> OLLAMA
    PLANNER --> SAFETY
    SAFETY --> EXECUTOR
    
    EXECUTOR --> DB
    SCANNER --> DB
    
    style SAFETY fill:#ff6b6b,stroke:#333,stroke-width:2px
    style EXECUTOR fill:#51cf66,stroke:#333,stroke-width:2px
    style PLANNER fill:#339af0,stroke:#333,stroke-width:2px

Loading

[vercel]

@adnan275 is attempting to deploy a commit to the Yug's projects Team on Vercel.

A member of the Team first needs to authorize it.