TidyFlow System Manual

1Summary

What the product does, in one page.

You select a folder, for example Downloads. TidyFlow does these steps:

1. It looks at the folder and proposes a set of folders (a "plan"). You can change the plan with plain English, for example "remove Media" or "add a folder for Bills".
2. It reads every file. It reads the text in PDFs, Office files and code. It uses OCR to read text in images and scanned PDFs.
3. It gives each file a folder and a confidence value. Rules, keyword scores and an AI model (optional) make this decision.
4. It shows you the result. Files with high confidence are already in a folder. Files with low confidence wait for you.
5. When you approve, it copies the files into an Organized folder. It checks each copy with SHA-256.
6. You can undo. Undo removes only the copies that are still identical to what TidyFlow made.

2Terms

Words that this manual uses. Each word has one meaning.

3Architecture

The parts of the system and how they connect.

TidyFlow is a local web app inside a native window. One Python process runs the HTTP server and the file pipeline. The React UI talks to that server over HTTP on 127.0.0.1. Only the AI step goes to the internet, and only when you add an API key.

flowchart LR
  subgraph Desktop["Desktop app (one process)"]
    W["pywebview window
(WebKit / Edge WebView2)"]
    subgraph Server["uvicorn + FastAPI (src/api.py)"]
      API["REST endpoints"]
      SSE["/events SSE stream"]
      PIPE["Pipeline
src/main_loop.py"]
      AIA["AI assistant
src/ai_assistant.py"]
      APP["Applier + Undo
src/applier.py"]
    end
  end
  UI["React UI
frontend/dist"] -- "fetch JSON" --> API
  SSE -- "progress events" --> UI
  W -- "loads" --> UI
  PIPE --> FS[("Your files")]
  APP --> FS
  PIPE --> OCR["OCR
Apple Vision / PaddleOCR"]
  PIPE --> DB[("SQLite
tidyflow.db")]
  PIPE -. "names + 600-char excerpts
(secrets removed)" .-> LLM["LLM provider
(optional)"]
  AIA -. "file samples" .-> LLM

Main backend modules (src/)

4User flow

The five screens of the guided flow and the API calls behind them.

flowchart LR
  H["Home
pick folder"] --> P["Plan
agree on folders"]
  P --> S["Sorting
read + classify"]
  S --> V["Preview
review unsure files"]
  V --> D["Done
open / undo"]
  D -. "Undo" .-> H
  P -- "POST /ai/chat-structure" --> P
  S -- "POST /pipeline/run
+ SSE progress" --> S
  V -- "POST /ai/review-chat" --> V
  V -- "POST /pipeline/apply-direct" --> D
  D -- "POST /pipeline/undo-last" --> D

1. Home. You select a folder (quick locations, OS folder dialog, or an in-app browser). If an earlier sort of this folder exists, you can resume it.
2. Plan. The app asks the AI (or the offline planner) to propose folders from a sample of your files. You set detail level: Fewer, Balanced, Detailed. You can rename, add, remove, or type a change in plain English.
3. Sorting. The pipeline runs. The screen shows live messages from the server. You can cancel.
4. Preview. Files are in two groups: "sure" (already placed) and "to review". You can move, rename, exclude files, or type a command such as "put the invoices in Bills".
5. Done. TidyFlow copies the files. You can open the output folder, or undo everything with one click.

The app also has Search, Settings, and two "advanced" views (a full plan editor and a full review table).

5Pipeline overview

run_pipeline() in src/main_loop.py. Nine steps, in order. Each step adds data to the same list of FileRecords.

flowchart TD
  A["1 Scan
scanner.py"] --> B["2 Metadata + thumbnails
metadata.py"]
  B --> C["3 Duplicates
SHA-256 + pHash"]
  C --> D["4 Text extraction
PDF / Office / text"]
  D --> E["5 OCR
images + scanned PDFs"]
  E --> F["6 Rules + keyword scores
+ fast path"]
  F --> G{"AI enabled
and key set?"}
  G -- yes --> H["7 Batched LLM
for unclassified files"]
  G -- no --> I
  H --> I["8 Save records (JSONL)
+ optional reports"]
  I --> J{"auto_apply?"}
  J -- yes --> K["9 Copy / move
(CLI only)"]
  J -- no --> L["Index in SQLite
return to UI"]
  K --> L

6Scan and inventory

src/scanner.py — which files enter the pipeline.

iter_candidate_files() walks the folder with os.walk. It is the single source of truth for "what can be organized". The scan and the folder-plan sampler both use it.

The scanner skips

• Names in the default ignore list: .git, node_modules, venv, __pycache__, .DS_Store, Organized, Organized_Output, Staging, and more.
• Patterns in a .tidyignore file in the input folder (like .gitignore).
• The output and staging folders, so a second run does not sort its own output.
• Hidden files (start with .) and Office lock files (start with ~$).
• The inside of bundles: .app, .photoslibrary, .xcodeproj, .pages, and others. A bundle is one document. Its inner files must not be sorted one by one.
• Secret files (is_secret_file): known names such as .env, key extensions such as .pem, and CSV/TXT files whose first line looks like a saved-passwords export. These become "skipped" records.

For each accepted file

1. Read size and dates with stat().
2. Set too_large = True if the size is more than max_file_size_mb (200 MB). A large file is still organized by name and type, but its content is never read.
3. Compute SHA-256 in 64 KB chunks.
4. Make file_id = first 12 hex characters of sha256(content_hash + ":" + rel_path).
5. Set file_category from the extension: image, document, code, data, media, archive, binary, other.

7Duplicates

src/hashing.py — exact copies and images that look the same.

Exact duplicates

Files with the same SHA-256 go into one group. The group ID is dup_<first 10 chars of hash>. This is a dictionary group-by, O(n).

Near duplicates (images)

1. For each image (not too large), compute a pHash. The code has its own pHash: it resizes to 32×32 grayscale, applies a 2D DCT with a NumPy matrix, keeps the 8×8 low-frequency block, and sets each bit to "value > median". This avoids SciPy, which keeps the packaged app small.
2. Compare each pair of hashes. The Hamming distance is the number of different bits.
3. If the distance is ≤ 8 (hamming_distance_threshold), join the two images with Union-Find.
4. Each Union-Find set with 2 or more images becomes a group near_<id>.

flowchart LR
  A["photo.jpg"] -- "distance 3" --- B["photo_small.jpg"]
  B -- "distance 6" --- C["photo_edit.jpg"]
  A -. "distance 11
(no direct link)" .- C
  subgraph G["One group: near_xxxx"]
    A
    B
    C
  end

Union-Find uses path compression (parent[x] = parent[parent[x]]). The pair loop is O(n²) in the number of images.

8Text extraction and OCR

src/extractor.py and src/ocr_engine.py — how TidyFlow reads content.

Direct extraction (step 4)

All extracted text goes through redact_secrets(). Then normalize_ocr_text() makes it lowercase, removes single punctuation marks, and collapses spaces.

OCR (step 5)

OCR runs on images, and on documents that have no text after step 4.

flowchart TD
  S["Candidate file"] --> SM{"Smaller than
120 px?"}
  SM -- yes --> X["Skip (icon)"]
  SM -- no --> C{"SHA-256 in
ocr_cache.json?"}
  C -- yes --> R["Use cached text"]
  C -- no --> M{"macOS and
bin/macos_ocr exists?"}
  M -- yes --> V["Apple Vision
VNRecognizeTextRequest (.accurate)"]
  M -- no --> P{"PaddleOCR
available?"}
  P -- yes --> PO["PaddleOCR PP-OCRv5 det + v4 rec
after preprocessing"]
  P -- no --> N["No text"]
  V --> W["Save to cache"]
  PO --> W

• Apple Vision. src/native/macos_ocr.swift is a small Swift program. The build compiles it to bin/macos_ocr. In development, the app compiles it on first use if swiftc exists. Python calls it with subprocess.
• PaddleOCR. The engine loads lazily (only when needed). Preprocessing: fix EXIF rotation, convert to RGB, shrink to max 768 px, increase contrast by 1.2.
• Cache. The key is the file's SHA-256. If you rename or move a file, OCR does not run again. Only changed content runs OCR again.

9Rules and keyword scores

src/rules.py — fast decisions that need no AI.

Rule order in RuleEngine.evaluate_record()

1. Large file. Size > 50 MB and the plan has Large_Files (or no plan) → Large_Files, confidence 1.0.
2. User rules from rules.yaml (app data folder first). A rule matches by extensions, a regex pattern on the name, or a contains word. Result: confidence 1.0, source user_rule. A rule is ignored if its category is not in the current plan.
3. Extension rule. Only for code, archive and media files. Example: .mp3 → Media/Audio. Confidence 0.90, source extension_rule. Only if that category is in the plan.

Keyword scoring

For each file with text, and for each category, the score is the best score of its keywords (0–100):

• Multi-word keyword: 100 if the exact phrase is in the text. Otherwise rapidfuzz.fuzz.partial_ratio.
• Single word: 100 if it matches on a word boundary (\bword\b). Otherwise fuzzy score only if the word has 6 or more letters. Short words get 0, because fuzzy matching on short words gives false positives.

Fast path (skip the AI)

A file goes on the fast path when the top score ≥ 88 and the second score < 50. A clear winner means the AI is not necessary. Confidence = score / 100. The action is "sure" only if that is ≥ the threshold. This saves API cost and time.

10AI classification

classify_files_batched() in src/llm_provider.py.

Only files with no classification after step 6 go to the AI. They go in batches (default batch_size: 15). One HTTP request classifies a full batch. This uses fewer tokens than one request per file, because the long system prompt is sent once per batch.

What the AI receives for each file (LlmFilePayload)

file_id, name, extension, file category, size, up to 600 characters of text, keyword scores above 40, and duplicate group IDs. No file bytes. No images.

The prompt

• The list of allowed categories, with descriptions and up to 8 keywords each.
• Your custom instructions (optional).
• A confidence scale: 0.95–1.0 name and content agree; 0.75–0.94 mostly name; 0.40–0.74 a guess; below 0.40 prefer Unknown.
• Rename rule: suggest a name only if it says more than the current name.
• Strict JSON output: {"results":[{file_id, category, confidence, file_type, suggested_filename, reason, action}]}.

There are two prompt modes. Standard mode always picks the closest category with a lower confidence. Strict mode (custom narrow categories) puts every file that does not clearly fit into Unknown.

Request settings

temperature: 0.1, max_tokens: 8000, response_format: json_object, endpoint {base_url}/chat/completions, Bearer key.

sequenceDiagram
  participant P as Pipeline
  participant L as LLM API
  P->>L: system prompt + batch (JSON)
  alt 200 OK and valid JSON
    L-->>P: {"results":[...]}
    P->>P: validate with Pydantic (LlmBatchResponse)
  else 429 rate limit
    P->>P: wait Retry-After or 2^n x 2.5 s (max 30 s)
    P->>L: retry
  else 401 / 402
    P->>P: stop batch, keep friendly error
  else bad JSON
    P->>L: same request + broken answer + "return ONLY valid JSON"
  end
  P->>P: files with no answer -> Unknown, manual_review

After the answer

1. Category resolve. Exact match, then case-insensitive, then last path part ("Invoices" → "Finance/Invoices"). No match → Unknown. The AI cannot invent a folder.
2. Confidence normalize. If the model answers 0–100, divide by 100. Clamp to 0–1.
3. Action decide. The code ignores the model's action. It sets "sure" only if category ≠ Unknown and confidence ≥ threshold. So the result always agrees with your threshold.
4. Rename check. rename_adds_meaning() keeps a new name only if it adds a real word that is not filler (such as "image", "scan", "final").

Providers

All providers use the same OpenAI-compatible format, so one HTTP client (httpx) serves all of them. At startup, verify_llm_key() tests the key in the background. The last AI error is kept so the UI can show a clear message.

11Folder plan (AI assistant)

chat_generate_structure() in src/ai_assistant.py, called by POST /ai/chat-structure.

Step A — describe the folder

inspect_directory() makes two things:

• Summary of the whole folder: total files, counts by kind, top 12 extensions, top 10 subfolders.
• Sample of up to 80 files. Each line has the path, type, size, and a short text preview for text files and PDFs. Secret files show only name and size.

The sample uses _spread_sample(). It groups files by (top subfolder, extension). Groups take turns and get one slot each, until the sample is full. Then it picks files evenly spaced in each group. This makes sure rare file types appear, not only the first 80 files found.

Step B — ask the AI

The system prompt has a detail level:

Rules in the prompt: the returned categories replace the full set; remove, rename, merge and split exactly as asked; every folder must hold several files; for fewer than about 30 files, prefer flat; do not stretch a category to hold an unrelated file; pick an SF Symbol for each folder. The last 8 chat turns are sent, so you can make changes in steps.

Without a key

_fallback_heuristic_structure() makes a plan from file names and types, and parses simple commands such as "add a folder for X". If the AI call fails, the same fallback runs, and the UI marks the plan as "basic".

The plan for each folder is saved in the app data folder (GET/POST /categories?folder=…), so it comes back when you open the same folder again.

12Review step

PreviewScreen.tsx and apply_review_command().

Sure or unsure

The UI puts a file in "to review" when there is no user override and one of these is true:

• the category is Unknown;
• the confidence is below the threshold;
• the category is not a folder in the current plan.

All other files are "sure" and are shown inside their folders. When you change a file by hand, it becomes sure.

Plain-English review commands

Example: "move the course screenshots to Academic". POST /ai/review-chat does this:

1. Number the folders. Send the files as a compact tab-separated table: id, name, folder number, organize flag, size, 200-character text excerpt.
2. Split large folders into chunks of 150 files. Send up to 4 chunks in parallel with a ThreadPoolExecutor.
3. The AI returns moves, renames, exclude, include, and a short message.
4. _validate_review_result() keeps only real IDs, cleans folder and file names (removes \ / : * ? " < > |, keeps the extension), drops changes that do nothing, and joins "Bills" and "bills" into one folder.
5. If the counts changed during validation, the code writes a new message from the real changes, so the message never claims something that did not happen.

13Apply

POST /pipeline/apply-direct → apply_decisions() in src/applier.py.

The UI sends one decision for each file: approved, override folder, new filename. The server uses the FileRecords from the last run (in memory, or loaded from disk after restart).

flowchart TD
  A["Approved decision"] --> B{"Folder is Unknown
and no override?"}
  B -- yes --> SK["Skip"]
  B -- no --> C{"Unsafe extension?
.exe .sh .ps1 .pem .env ..."}
  C -- yes --> SK
  C -- no --> D["choose_destination()"]
  D --> E{"Same name AND
same SHA-256 there?"}
  E -- yes --> SK2["Skip: already organized"]
  E -- no --> F["shutil.copy2()
keeps dates"]
  F --> G{"SHA-256 of copy
= original?"}
  G -- no --> RB["Delete copy (rollback)"]
  G -- yes --> H{"move_mode?"}
  H -- yes --> RM["Delete original"]
  H -- no --> M["Add manifest entry"]
  RM --> M

Name clashes (choose_destination)

Organizing makes folders flat, so two files can have the same name. TidyFlow never overwrites. It tries, in order:

1. photo.jpg
2. photo (Trip).jpg — the name of the folder where the file came from
3. photo (2).jpg … photo (999).jpg — like Finder
4. photo_1a2b3c4d.jpg — first 8 characters of the hash, as a last fallback

After apply

• Write the manifest to <app data>/manifests/copy_manifest.csv.
• Save undo data to last_apply.json. It records if the output folder was new.
• On macOS 26+, set each new folder's symbol, emoji and colour (only folders that did not exist before).
• Clear the run results, so a restart does not offer the same results again.
• If nothing was copied and the output folder is new, delete the empty folder.

14Undo

POST /pipeline/undo-last in src/api.py.

sequenceDiagram
  participant U as UI
  participant A as API
  participant F as File system
  U->>A: POST /pipeline/undo-last
  A->>A: read last_apply.json
  loop each manifest entry
    A->>F: SHA-256 of destination
    alt missing or changed
      A->>A: skip (do not touch user's file)
    else copy
      A->>F: delete copy
    else move
      A->>F: move back (only if original place is empty)
    end
  end
  A->>F: remove emptied folders, deepest first, never above output root
  A->>F: remove output root if TidyFlow made it and it is empty
  A-->>U: {restored, skipped}

The applier also skips files that are "already organized". This makes sure each manifest entry is a file that TidyFlow made, so undo cannot delete an older copy from a previous run.

15Safety and privacy

All the protections in one table.

Data that leaves your computer: only with an API key, and only file names, extension, size, up to 600 characters of redacted text, and keyword hints. OCR and extraction run on your computer.

16Data storage

Where TidyFlow keeps its files.

The app data folder is ~/Library/Application Support/TidyFlow (macOS), %APPDATA%\TidyFlow (Windows), or ~/.local/share/tidyflow (Linux). The packaged app writes caches and logs here, because its own folder is read-only. From source, the work folder is ./data.

SQLite design (src/database.py)

• WAL mode + synchronous=NORMAL: reads do not block writes.
• Table files: path (unique), category, new path, confidence, text, thumbnail, status, suggested name, reason. Columns are added automatically if an old database lacks them.
• FTS5 table files_fts on path, text and category. Three triggers (insert, delete, update) keep it in sync.
• Single writer. All async writes go into an asyncio.Queue. One task takes up to 100 writes and runs them as one batch in a thread. This avoids "database is locked" errors.
• Search. The query becomes tokens "tok"* joined with AND (prefix search), ranked, max 30, with a highlighted snippet. If FTS finds nothing, a LIKE search runs. Rows whose file no longer exists are deleted.
• Crash recovery. At start, rows with status processing go back to pending.

17Live progress

How the Sorting screen gets updates while the pipeline runs.

sequenceDiagram
  participant UI as React UI
  participant API as FastAPI (event loop)
  participant T as Worker thread (pipeline)
  UI->>API: GET /events (EventSource, stays open)
  UI->>API: POST /pipeline/run
  API->>T: asyncio.to_thread(run_pipeline)
  T->>API: progress_callback("extract", "Reading...")
via run_coroutine_threadsafe
  API-->>UI: event: pipeline_progress
  Note over API,UI: every 15 s without news: event "ping"
  T-->>API: records, summary
  API-->>UI: event: pipeline_complete
  API-->>UI: HTTP response with all files (JSON)

The pipeline runs in a thread, but the queues belong to the event loop. So the callback uses asyncio.run_coroutine_threadsafe(…, loop) to put events safely on the loop. SSE is enough here because data goes only from server to UI. WebSocket is not necessary.

18API reference

Endpoints in src/api.py (FastAPI, version 2.3.1).

Startup (lifespan): start the DB writer, start the processor workers, load the last run from disk, test the AI key in the background.

19Frontend

frontend/src — React 19 + TypeScript.

• App.tsx holds all state and all API calls. It mirrors the current folder into localStorage.
• flow/ has the five screens (HomeScreen, PlanScreen, SortingScreen, PreviewScreen, DoneScreen) plus TopBar, ReviewAssistant, FolderLookPicker. The screens only show data and call callbacks. flow/contracts.ts defines their props. This is the "container / presentational" pattern.
• components/ has the advanced views: ReviewView, CategoriesView, AiStructureAssistant, SearchView, SettingsView, modals.
• wizard/ is an animated SVG mascot. Each body part rotates around its own joint (rig.ts, poses.ts, motions.ts).
• utils/: folder icons and colours, preset categories, category history.
• config.ts picks the API base. In the packaged app, the page comes from the backend on a free port, so it uses window.location.origin. In dev (Vite on port 1420) it uses http://127.0.0.1:8000 or VITE_API_BASE.

Styling uses Tailwind CSS 4 with tokens, Inter and JetBrains Mono fonts, light and dark mode, Motion for animation, and Lucide icons. frontend/src-tauri holds a Tauri project, but the release build uses pywebview.

20Desktop shell and build

desktop.py, build/, .github/workflows/build.yml.

Start sequence (desktop.py)

1. Fix stdout/stderr (they are None in a Windows GUI build).
2. Find a free port from 8000 (try 50 ports).
3. Start uvicorn in a daemon thread with its own event loop. Bind to 127.0.0.1 only.
4. Poll the server until it answers (max 10 s).
5. Open a pywebview window (1280×840). On Windows use Edge WebView2. If pywebview fails, open the system browser.
6. When the window closes, stop the server and exit.

Build (build/build.py)

1. Build the frontend (npm run build).
2. On macOS, compile the Apple Vision helper with swiftc.
3. Run PyInstaller with build/tidyflow.spec.
4. Package: TidyFlow.dmg on macOS, TidyFlow-windows.zip on Windows.

PyInstaller cannot cross-compile. A v* git tag starts GitHub Actions on macos-latest and windows-latest. It attaches both builds to the release. get_resource_path() finds bundled files in dev, in sys._MEIPASS, and in Contents/Resources of a macOS app.

21CLI and configuration

src/cli.py (Typer) and config.yaml.

python3 -m src.cli run -i ~/Downloads -o ~/Downloads/Organized         # dry run + HTML report
python3 -m src.cli run -i ~/Downloads -o ~/Organized --auto-apply --confirm
python3 -m src.cli inventory -i ~/Downloads -o ./report                 # offline, no AI
python3 -m src.cli config-set-llm deepseek <key>

Commands: run, inventory, scan, report, apply (from a reviewed review_decisions.csv), serve, config-set-llm, status.

Important config keys

22Tests

tests/ — pytest, 26 test files.

There is one test file for almost every module: scanner, hashing, extractor, rules, keyword scorer, LLM provider, AI assistant, applier, undo API, file system API, search, database, config, models, utils, CLI, folder style, MCP server, graph, main loop. There are also end-to-end (test_e2e.py) and scale (test_scale.py) tests. The AI is mocked, so tests need no key and no network.

python3 -m pytest tests/

23Other modules

Code that is in the repository but is not on the main path.

• graph.py — a LangGraph state machine for one file (scan → route → extract → classify → review or move → checkpoint). Only its tests use it. The main pipeline is a batch function, which is simpler and cheaper.
• mcp_server.py — file tools (list, copy, move, delete) with a path allow-list, using FastMCP if it is installed. The API calls set_allowed_directories() with the input and output folders on each run.
• file_mover.py — uses the MCP tools to move files inside the allow-list.
• Processor in main_loop.py — an async worker pool (queue + semaphore, 5 workers). It applies basic rules to single files and writes to the DB. It starts with the server.
• reporter.py — CSV inventory, OCR JSONL, classification CSV, run summary, and an HTML review report (Jinja template). Used by the CLI and when export_reports is on.
• scripts/compare_decision_models.py — compares the decisions of different AI models.

24Limits and next steps

Honest weak points. Interviewers often ask about these.

25Interview questions and answers

Click a question to see a short, clear answer.

Product and design

Pipeline and algorithms

AI and LLM

Safety and correctness

Backend engineering

Frontend and packaging

Scale and improvement