⚡ SortForge

One-click local file organizer that permanently sorts messy folders into clean, structured hierarchies.

---

---

No cloud. No virtual folders. Your real filesystem gets organized — permanently.

---

🎯 What It Does

Select a folder, click Organize, and SortForge scans every file, creates category folders, and moves files into their correct locations — directly on your computer.

Before:                            After:
─────────                          ──────
Project/                           Project/
├── clip1.mp4                      ├── Videos/
├── clip2.mp4                      │   ├── clip1.mp4
├── music.mp3                      │   └── clip2.mp4
├── logo.png                       ├── Audio/
├── document.pdf                   │   └── music.mp3
├── photo.jpg                      ├── Images/
├── notes.txt                      │   ├── logo.png
├── backup.zip                     │   └── photo.jpg
└── song.flac                      ├── Documents/
                                   │   ├── document.pdf
                                   │   └── notes.txt
                                   ├── Archives/
                                   │   └── backup.zip
                                   └── Audio/
                                       └── song.flac

---

🚀 Quick Start

Prerequisites

None. start.bat automatically detects and installs Node.js if it's missing.

Option 1 — Double-click to launch

start.bat

Auto-installs Node.js if needed, installs dependencies, starts both servers, and opens the browser automatically. Works out of the box for non-technical users.

Option 2 — Manual start (two terminals)

# Terminal 1 — Bridge (backend)
cd apps/bridge
npm run dev

# Terminal 2 — Frontend (UI)
cd apps/web
npm run dev

Then open http://localhost:3000 in your browser.

To stop

stop.bat

---

🔄 How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│  1. Click Browse        → Folder picker opens (drives, quick       │
│                             access, visual navigation)               │
│  2. Navigate & Select   → Choose any folder on your computer       │
│  3. Scan                → SortForge scans every file recursively    │
│  4. Review Summary      → See file counts by category               │
│  5. Click Organize      → Folders created, files moved             │
│  6. Watch Live          → Real-time folder tree + activity feed     │
│  7. Done                → Completion summary with stats             │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

---

🏗️ Architecture

┌──────────────────────┐    HTTP/WS     ┌──────────────────────┐    Filesystem    ┌──────────────┐
│                      │                │                      │                  │              │
│   Frontend (UI)      │ ────────────── │   Bridge (Server)    │ ────────────── │  Your Disk   │
│   Next.js :3000      │                │   Node.js :43125     │                  │              │
│                      │                │                      │                  │              │
│   ┌──────────────┐   │                │   ┌──────────────┐   │                  │              │
│   │ FolderPicker │   │   GET /scan    │   │   Scanner    │   │  Recursive walk  │              │
│   │ Modal        │   │ ──────────────▶│   │   + Classify │◀──│──────────────────│              │
│   └──────────────┘   │                │   └──────────────┘   │                  │              │
│                      │   POST /organize                       │                  │              │
│   ┌──────────────┐   │ ──────────────▶┌──────────────────┐   │  Create folders  │              │
│   │ Event Tree   │◀──│ ◀──────────── │ │  Planner +      │───│────────────────▶│              │
│   │ View         │   │   WS events   │ │  Executor       │   │  Move files     │              │
│   └──────────────┘   │               └──────────────────┘   │                  │              │
│                      │                                       │                  │              │
│   ┌──────────────┐   │   WS events   ┌──────────────────┐   │                  │              │
│   │ Activity     │◀──│ ◀──────────── │ WebSocket Server │   │                  │              │
│   │ Feed         │   │               │ (real-time)      │   │                  │              │
│   └──────────────┘   │               └──────────────────┘   │                  │              │
│                      │                                       │                  │              │
└──────────────────────┘                                       └──────────────────┘──────────────┘

Communication Flow

Browser ──HTTP POST──▶ Bridge ──filesystem──▶ Disk
Browser ◀──HTTP 202── Bridge (organization started)
Browser ◀──WS events── Bridge (real-time progress)

---

📦 Tech Stack

Layer	Technology	Purpose
Frontend	Next.js 16	React framework, SSR, routing
UI Library	React 19	Component rendering
Language	TypeScript 5/6	Type safety across all packages
Styling	Tailwind CSS 4	Utility-first CSS
State	Zustand 5	Lightweight global state
Icons	Lucide React	Icon library
Animations	Framer Motion	UI micro-animations
Data Fetching	TanStack Query 5	Async operations, caching
Backend	Node.js + Express 5	HTTP server, API endpoints
WebSocket	ws 8	Real-time event streaming
Validation	Zod 4	Schema validation (shared)
Testing	Jest 30 + Vitest	Unit tests (bridge + web)
Dev Server	tsx	TypeScript execution for bridge

---

📁 Project Structure

SortForge/
├── apps/
│   ├── web/                          # Next.js frontend
│   │   ├── src/
│   │   │   ├── app/
│   │   │   │   ├── layout.tsx        # Root layout (Geist font, metadata)
│   │   │   │   ├── page.tsx          # Entry page → OrganizerScreen
│   │   │   │   ├── globals.css       # Tailwind directives + global styles
│   │   │   │   └── favicon.ico       # Application favicon
│   │   │   ├── components/
│   │   │   │   ├── organizer-screen.tsx   # Main screen composing all UI
│   │   │   │   ├── folder-picker-modal.tsx # File Explorer-style modal
│   │   │   │   ├── folder-picker.tsx      # Basic folder picker
│   │   │   │   ├── folder-browser.tsx     # Inline folder browser
│   │   │   │   ├── scan-summary.tsx       # Category count display
│   │   │   │   ├── organize-button.tsx    # Organize trigger button
│   │   │   │   ├── event-tree.tsx         # Live folder tree visualization
│   │   │   │   ├── activity-feed.tsx      # Real-time event log
│   │   │   │   ├── summary-panel.tsx      # Completion summary stats
│   │   │   │   └── index.ts              # Barrel export
│   │   │   ├── hooks/
│   │   │   │   └── use-bridge-connection.ts # Health check polling (5s)
│   │   │   ├── lib/
│   │   │   │   └── bridge-client.ts    # HTTP/WS client wrapper
│   │   │   ├── store/
│   │   │   │   └── organizer-store.ts  # Zustand global state
│   │   │   └── types/
│   │   │       └── organizer.ts        # TypeScript interfaces
│   │   ├── public/                    # Static assets
│   │   │   ├── file.svg
│   │   │   ├── globe.svg
│   │   │   ├── next.svg
│   │   │   ├── vercel.svg
│   │   │   └── window.svg
│   │   ├── package.json               # Next.js + React dependencies
│   │   ├── tsconfig.json              # TypeScript config
│   │   ├── next.config.ts             # Next.js config
│   │   ├── postcss.config.mjs         # PostCSS + Tailwind
│   │   └── eslint.config.mjs          # ESLint config
│   │
│   └── bridge/                        # Node.js file organizer server
│       ├── src/
│       │   ├── main.ts                # Entry point, starts server
│       │   ├── ipc/
│       │   │   ├── server.ts          # HTTP + WebSocket server
│       │   │   └── index.ts           # Barrel export
│       │   ├── scanner/
│       │   │   ├── walk.ts            # Recursive directory scanner
│       │   │   ├── classify.ts        # File extension → category mapper
│       │   │   └── index.ts           # Barrel export
│       │   ├── organizer/
│       │   │   ├── planner.ts         # Builds operation plan from scan
│       │   │   ├── executor.ts        # Executes plan, moves files, emits events
│       │   │   └── index.ts           # Barrel export
│       │   ├── utils/
│       │   │   ├── path-utils.ts      # Path traversal safety, relative paths
│       │   │   ├── fs-utils.ts        # Filesystem helpers (exists, move, ensure)
│       │   │   ├── name-utils.ts      # Duplicate filename resolution
│       │   │   └── index.ts           # Barrel export
│       │   ├── errors/
│       │   │   ├── organizer-error.ts # Typed error classes
│       │   │   └── index.ts           # Barrel export
│       │   ├── config/
│       │   │   ├── defaults.ts        # Port, WS path, CORS, max file size
│       │   │   └── index.ts           # Barrel export
│       │   └── models/
│       │       └── index.ts           # Model types
│       ├── dist/                      # Compiled output (committed)
│       ├── package.json               # Express, ws, zod dependencies
│       └── tsconfig.json              # TypeScript config (ES2022, commonjs)
│
├── packages/
│   └── shared/                        # Shared types + Zod schemas
│       ├── src/
│       │   └── index.ts              # All shared schemas and types
│       ├── package.json               # Zod dependency
│       └── tsconfig.json              # TypeScript config
│
├── start.bat                          # One-click launcher (auto-installs Node.js)
├── stop.bat                           # Server stopper
├── README.md                          # This file
└── .gitignore                         # Git ignore rules

---

🔌 API Endpoints (Bridge Server)

Method	Endpoint	Description	Request	Response
GET	/health	Health check	—	{ "status": "ok", "timestamp": ... }
GET	/list-dirs?path=	List drives, quick-access folders, or subdirectories	Query: path (or __root__)	{ currentPath, parentPath, isRoot, separator, drives, quickAccess, directories }
POST	/scan	Scan a folder recursively, classify files by extension	{ "folderPath": "..." }	{ folderPath, files[], categorySummary, totalFiles }
POST	/organize	Start organizing files (async, streams events via WS)	{ "folderPath": "..." }	202 { message, folderPath, totalFiles }
WS	ws://localhost:43125/events	Real-time organization events	—	Stream of OrganizerEvent objects

WebSocket Event Types

Event Type	Payload Fields	Description
job-started	folderPath, totalOperations	Organization job has begun
folder-created	path, folderName	A category folder was created
file-move-started	sourcePath, targetPath	File move operation began
file-move-completed	sourcePath, targetPath, fileName	File successfully moved
file-skipped	sourcePath, reason	File was skipped (already in correct folder)
duplicate-resolved	originalPath, resolvedPath, fileName	Duplicate filename resolved with (1), (2), etc.
job-completed	filesOrganized, foldersCreated, filesSkipped, duplicatesResolved, duration, errors	Job finished successfully
job-failed	error	Job failed with error

---

📂 Supported File Categories

Category	Destination Folder	Extensions
🎬 Videos	Videos/	.mp4 .mov .webm .avi .mkv .flv .wmv .m4v .mpg .mpeg
🎵 Audio	Audio/	.mp3 .wav .flac .ogg .aac .wma .m4a .opus
🖼️ Images	Images/	.png .jpg .jpeg .webp .gif .svg .bmp .tiff .tif .ico .heic .heif
📄 Documents	Documents/	.pdf .doc .docx .txt .rtf .odt .xls .xlsx .ppt .pptx .csv .md
📦 Archives	Archives/	.zip .rar .7z .tar .gz .bz2 .xz
❓ Other	Other/	Everything else

Total: 55+ file extensions recognized across 6 categories.

---

🧩 Frontend Components

Component	File	Description
OrganizerScreen	organize-screen.tsx	Main composition — assembles all UI sections, manages scan/organize flow, handles WebSocket subscription
FolderPickerModal	folder-picker-modal.tsx	File Explorer-style modal with drives sidebar, quick-access folders (Desktop, Downloads, Documents, Pictures, Music, Videos), visual directory navigation, path input bar, back/up/home buttons
FolderBrowser	folder-browser.tsx	Inline folder browser (alternative to modal) with drive detection and directory listing
ScanSummary	scan-summary.tsx	Displays file counts per category in a color-coded grid (blue=video, green=audio, purple=image, orange=document, red=archive, gray=other)
OrganizeButton	organize-button.tsx	Green action button with loading state — sends POST to bridge, triggers organization
EventTreeView	event-tree.tsx	Live folder tree visualization — shows folders being created and files being placed in real-time as WebSocket events arrive
ActivityFeed	activity-feed.tsx	Scrollable event log with timestamps — every action (create, move, skip, duplicate, complete) displayed in plain language
SummaryPanel	summary-panel.tsx	Completion statistics — status, duration, files organized, folders created, skipped, duplicates resolved, errors list

---

⚙️ Bridge Modules

Module	File	Responsibilities
Server	ipc/server.ts	HTTP server (Express-style), CORS handling, route dispatch, WebSocket upgrade, client broadcasting
Scanner	scanner/walk.ts	Recursive directory traversal, file stat collection, UUID generation, category summary building, skips .sortforge folder
Classifier	scanner/classify.ts	Extension-to-category mapping (55+ extensions), destination folder name resolution
Planner	organizer/planner.ts	Builds operation plan: determines folders to create, files to move, files to skip (already in correct folder)
Executor	organizer/executor.ts	3-phase execution: (1) create folders, (2) move files with duplicate resolution, (3) handle skips — emits events for every action
Path Utils	utils/path-utils.ts	Path traversal prevention (isInsideBase), relative path computation, extension extraction
FS Utils	utils/fs-utils.ts	Filesystem helpers: pathExists, isDirectory, isFile, ensureDir, moveFile, getFileSize, getFileTimestamps
Name Utils	utils/name-utils.ts	Duplicate filename resolution: appends (1), (2), etc. until unique
Errors	errors/organizer-error.ts	Typed error classes: invalidSession, bridgeUnavailable, folderAccessDenied, pathTraversalRejected, fileAlreadyExists, folderCreationFailed, fileMoveFailed, fileLocked
Config	config/defaults.ts	Port (43125), WebSocket path (/events), CORS origin (*), max file size (10GB)

---

🗃️ Shared Package (packages/shared)

Provides Zod schemas and TypeScript types used by both frontend and bridge:

Schema/Type	Purpose
FileCategorySchema	Enum: video, audio, image, document, archive, other
CATEGORY_FOLDER_NAMES	Maps categories to folder names (video → Videos, etc.)
FileNodeSchema	File metadata: id, name, extension, paths, category, size, timestamps, status
FolderNodeSchema	Recursive folder tree: id, name, path, children (folders + files), status
OrganizeOperationSchema	Operation: create-folder, move-file, rename-file, skip-file
OrganizerEventSchema	WebSocket event: type, jobId, timestamp, payload
ScanResultSchema	Scan output: folderPath, files[], categorySummary, totalFiles
OrganizeRequestSchema	Request body for /organize
ScanRequestSchema	Request body for /scan
JobStatusSchema	Job state: idle, scanning, organizing, completed, failed
JobResultSchema	Final result: jobId, status, filesOrganized, foldersCreated, filesSkipped, duplicatesResolved, errors, duration

---

🛡️ Security Model

Rule	Implementation
Path traversal prevention	isInsideBase() — normalized path comparison ensures target stays inside selected folder
No overwrites	resolveDuplicate() — appends (1), (2), etc. until unique filename found
No deletions	Version 1 only moves files, never deletes
Scope validation	Bridge only operates inside the selected folder tree
Hidden folder skip	Scanner skips .sortforge metadata directory
CORS enabled	Bridge allows all origins for local development
No network exposure	Bridge binds to localhost only (port 43125)

---

📊 Organization Pipeline

┌─────────────┐     ┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│  Select     │────▶│  Recursive  │────▶│  Classify    │────▶│  Build Plan  │
│  Folder     │     │  Scan       │     │  by Extension│     │  (operations)│
└─────────────┘     └─────────────┘     └──────────────┘     └──────┬───────┘
                                                                    │
                                                                    ▼
┌─────────────┐     ┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│  Job        │◀────│  Emit       │◀────│  Move Files  │◀────│  Create      │
│  Complete   │     │  Events     │     │  (dedup)     │     │  Folders     │
└─────────────┘     └──────┬──────┘     └──────────────┘     └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  Live UI     │
                    │  Update      │
                    └──────────────┘

Execution Phases

Phase	Action	Events Emitted
Phase 1	Create category folders (mkdir -p)	folder-created for each
Phase 2	Move files one-by-one (renameSync)	file-move-started, file-move-completed (or duplicate-resolved if conflict)
Phase 3	Skip already-correct files	file-skipped for each
Final	Emit completion	job-completed with stats

---

⚡ Frontend State Management

Zustand store (organizer-store.ts) manages:

State	Type	Description
folderPath	string	Currently selected folder
connected	boolean	Bridge health status
scanResult	ScanResult | null	Last scan results
jobStatus	JobStatus	idle → scanning → organizing → completed/failed
jobId	string | null	Active job identifier
events	OrganizerEvent[]	All received WebSocket events
tree	Map<string, FileNode>	File status tracking map
error	string | null	Current error message
duration	number	Job duration in ms

---

📜 Scripts

Command	Location	Description
start.bat	Root	One-click launcher — auto-installs Node.js, installs deps, starts servers, opens browser
stop.bat	Root	Kills processes on ports 43125 and 3000, stops named windows
npm run dev	apps/bridge	Start bridge in dev mode (tsx watch)
npm run build	apps/bridge	Compile TypeScript to dist/
npm start	apps/bridge	Run compiled bridge
npm test	apps/bridge	Run Jest tests
npm run typecheck	apps/bridge	TypeScript type checking (no emit)
npm run dev	apps/web	Start Next.js dev server
npm run build	apps/web	Production build
npm run lint	apps/web	ESLint checks
npm run build	packages/shared	Compile shared types
npm run typecheck	packages/shared	Type check shared package

---

🧪 Testing

Package	Framework	Test Files	What's Tested
apps/bridge	Jest 30 + ts-jest	*.test.ts	Scanner, classifier, planner, executor, path utils, name utils, server
apps/web	Vitest + @testing-library/react	—	Component rendering, store logic

Running Tests

# Bridge tests
cd apps/bridge
npm test

# Bridge type check
npm run typecheck

# Web lint
cd apps/web
npm run lint

---

🧠 Domain Model

FileCategory

type FileCategory = "video" | "audio" | "image" | "document" | "archive" | "other";

FileNode

interface FileNode {
  id: string;              // UUID
  name: string;            // filename with extension
  extension: string;       // .mp4, .pdf, etc.
  absolutePath: string;    // full path on disk
  relativePath: string;    // path relative to scan root
  category: FileCategory;
  size: number;            // bytes
  createdAt: string;       // ISO timestamp
  modifiedAt: string;      // ISO timestamp
  status: "pending" | "moving" | "done" | "skipped" | "error";
}

FolderNode

interface FolderNode {
  id: string;
  name: string;
  relativePath: string;
  children: Array<FolderNode | FileNode>;
  status: "pending" | "creating" | "created" | "error";
}

OrganizerEvent

interface OrganizerEvent {
  type:
    | "job-started"
    | "folder-created"
    | "file-move-started"
    | "file-move-completed"
    | "file-skipped"
    | "duplicate-resolved"
    | "job-completed"
    | "job-failed";
  jobId: string;
  timestamp: number;
  payload: Record<string, unknown>;
}

JobResult

interface JobResult {
  jobId: string;
  status: JobStatus;
  filesOrganized: number;
  foldersCreated: number;
  filesSkipped: number;
  duplicatesResolved: number;
  errors: string[];
  duration: number;          // milliseconds
}

---

🔧 Configuration

Bridge Config (config/defaults.ts)

Setting	Value	Description
PORT	43125	HTTP/WebSocket server port
WS_PATH	/events	WebSocket endpoint path
CORS_ORIGIN	*	CORS allowed origins
MAX_FILE_SIZE	10 GB	Maximum file size limit

TypeScript Configs

Package	Target	Module	Strict
apps/bridge	ES2022	CommonJS	Yes
apps/web	ES2017	ESNext	Yes
packages/shared	ES2022	CommonJS	Yes

---

🎨 UI Features

Feature	Implementation
Dark/Light mode	Tailwind dark: class variants on all components
Responsive layout	Mobile-first with sm: breakpoints
Visual folder picker	Drives sidebar, quick-access grid, folder list, path input
Quick Access icons	Custom SVG icons per folder type (Desktop, Downloads, Documents, Pictures, Music, Videos)
Color-coded categories	Blue (video), Green (audio), Purple (image), Orange (document), Red (archive), Gray (other)
Live tree animation	Folders and files appear in real-time as events arrive
Activity feed	Timestamped log with scroll, auto-scroll support
Loading states	Spinner during scan, button state changes during organize
Error display	Red alert box with error message
Back/Up navigation	Folder picker supports back button, up button, home button
Path input	Type any path and press Enter to navigate directly

---

🚧 Non-Goals (Version 1)

The following are intentionally out of scope:

• ❌ AI categorization / face detection / scene recognition
• ❌ Video editing / media conversion
• ❌ Timeline / project management
• ❌ Cloud synchronization / team collaboration
• ❌ Metadata editing / asset tagging
• ❌ Search engine / user accounts
• ❌ Duplicate cleanup (files are never deleted)
• ❌ Browser-only state as source of truth

---

🗺️ Future Vision

Potential features for future versions:

• ✅ Continuous folder monitoring (file watcher)
• ✅ Custom organization rules
• ✅ Project memory / manifest
• ✅ Smart media classification
• ✅ Metadata indexing
• ✅ Asset management dashboard
• ✅ Video editor integration
• ✅ Cross-device synchronization
• ✅ Plugin support

---

📋 Development Rules

1. Never mutate state outside the store or bridge command layer
2. Never move files without validating target scope
3. Never overwrite files silently
4. Never rely on browser memory as the source of truth
5. Never show fake progress when real events are available
6. Every action must be observable in logs or UI
7. Every module must have one responsibility

---

👥 Target Users

• Video editors
• Content creators
• YouTubers
• Freelancers
• Social media managers
• Photographers
• Students
• Anyone with messy folders

---

📄 License

ISC

---

Built with ❤️ using Next.js, Node.js, React, TypeScript, Tailwind CSS, Zustand, Express, WebSocket, and Zod.