Sniffly Project Summary

Status: Planning Complete ✅ Date: 2025-11-04 Next Step: Begin Phase 1 Development

---

What We're Building

Sniffly is a pure Fortran GUI application that visualizes disk space usage with interactive treemap diagrams. It's a near 1:1 clone of SpaceSniffer (a popular Windows tool) but for Unix systems (macOS and Linux).

The Big Idea

Prove that Fortran isn't just for scientific computing—it can build beautiful, modern GUI applications that rival commercial software written in C++/C#.

---

Technology Stack (Final Decision)

Component	Technology	Why
Language	Fortran 2008+	Pure Fortran philosophy, performance
GUI Framework	GTK4	Modern, cross-platform, has Fortran bindings
Bindings	gtk-fortran 3.24.41+	Only mature Fortran GUI library
Graphics	Cairo 1.18+	Hardware-accelerated 2D drawing
Text	Pango	Font rendering, ellipsization
Build System	Meson (primary)	GTK standard, handles dependencies
Platforms	macOS, Linux	Priority targets (no Windows)

---

Core Features

Must-Have (v1.0)

1. Real-time Treemap Visualization

   • Animated growth during scanning
   • Nested rectangles proportional to file sizes
   • Smooth layout transitions

2. Two Layout Algorithms

   • Squarified treemap (already implemented in sniffert)
   • Cushioned treemap (3D shading effect like SpaceSniffer)

3. Interactive Navigation

   • Click to zoom into directories
   • Breadcrumb navigation bar
   • Context menus (right-click)
   • Keyboard shortcuts (same as sniffert: q, c, d, arrows)

4. Search and Filter

   • Search by filename (regex support)
   • Filter by file type, size, date
   • Highlight matching files

5. Safe File Deletion

   • Delete with confirmation dialog
   • Show full path and size
   • Large deletions require typing name

6. Visual Customization

   • Multiple color schemes (Light, Dark, High Contrast)
   • Color by file type, age, or custom
   • Configurable fonts and sizes

7. High Performance

   • Handle 1M+ files
   • 60fps rendering
   • Background scanning without blocking UI

Nice-to-Have (Post-v1.0)

• Export treemap as PNG/SVG
• Compare two directory snapshots
• Bookmarks for frequent directories
• Hidden files toggle
• Multiple tabs

---

Architecture Overview

┌─────────────────────────────────────────┐
│         GTK4 Main Window                │
│  ┌───────────────────────────────────┐  │
│  │ Toolbar: Scan | Layout | Search   │  │
│  ├───────────────────────────────────┤  │
│  │                                   │  │
│  │   Treemap Widget (Custom)        │  │
│  │   ┌───────────────────────────┐  │  │
│  │   │  Cairo Drawing Surface    │  │  │
│  │   │  (Rectangles, gradients)  │  │  │
│  │   └───────────────────────────┘  │  │
│  │                                   │  │
│  ├───────────────────────────────────┤  │
│  │ Status: Scanning /foo/bar        │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
           │
           ↓
┌─────────────────────────────────────────┐
│      Application State Manager          │
│  • Directory tree (file_node)           │
│  • Layout cache                         │
│  • Selection state                      │
│  • Scan progress                        │
└─────────────────────────────────────────┘
           │
    ┌──────┴───────┐
    ↓              ↓
┌────────┐    ┌────────┐
│Scanner │    │Renderer│
│(thread)│    │(Cairo) │
└────────┘    └────────┘

Module Organization

src/
├── core/          # Reused from sniffert
│   ├── types.f90
│   ├── file_system.f90
│   ├── disk_scanner.f90
│   └── utils.f90
│
├── layout/        # Treemap algorithms
│   ├── squarified.f90  (port from sniffert)
│   ├── cushioned.f90   (new implementation)
│   └── layout_manager.f90
│
├── gui/           # GTK4 interface
│   ├── gtk_app.f90
│   ├── main_window.f90
│   ├── treemap_widget.f90
│   └── dialogs.f90
│
├── rendering/     # Cairo drawing
│   ├── cairo_renderer.f90
│   ├── colors.f90
│   └── effects.f90
│
└── state/         # App state
    ├── app_state.f90
    ├── selection.f90
    └── scan_manager.f90

---

Development Timeline

Total Duration: 12-14 weeks to v1.0

Phase	Weeks	Goal	Key Deliverables
Phase 1	1-2	Foundation & GTK Setup	Basic GTK window, Cairo drawing
Phase 2	3-4	Core Data & Scanning	Background scanning, state management
Phase 3	5-6	Layout Algorithms	Squarified + Cushioned layouts
Phase 4	7-8	Cairo Rendering	Beautiful rendering, cushion effects
Phase 5	9-10	Interactivity	Navigation, context menus, keyboard
Phase 6	11	Search & Filter	Search box, filtering UI
Phase 7	12	Polish & Config	Settings, animations, accessibility
Phase 8	13-14	Testing & Packaging	Packages for macOS/Linux

Current Status

✅ Planning Complete (Week 0)

• All documentation written
• Architecture designed
• Stack chosen and validated

🚧 Phase 1 Starting (Week 1)

• Install dependencies
• Build hello world GTK app
• Set up project structure

---

Key Technical Decisions

1. Pure Fortran (No C++/Python hybrid)

Decision: Use ONLY Fortran via gtk-fortran Rationale: Proves the point that Fortran can do GUIs Trade-off: Steeper learning curve, less examples Mitigation: gtk-fortran is mature and well-documented

2. GTK4 (Not Qt, wxWidgets, or custom OpenGL)

Decision: GTK4 via gtk-fortran Rationale:

• Only mature Fortran GUI bindings exist
• Native on Linux, good on macOS (Cocoa backend)
• Cairo integration for custom drawing

Trade-off: Not as native-looking on macOS as Qt Mitigation: GTK4 is much better than GTK3 on macOS

3. Cushioned Treemap (Not Spiral)

Decision: Implement cushioned treemap (like SpaceSniffer) Rationale: Research shows SpaceSniffer uses cushioned, not spiral Implementation: Van Wijk algorithm with Cairo gradients Benefit: More visually appealing than flat squarified

4. Meson Build System (Not Make or pure FPM)

Decision: Meson primary, FPM fallback Rationale:

• Meson is GTK standard
• Handles pkg-config dependencies elegantly
• Cross-platform without pain

Trade-off: Fortran community less familiar with Meson Mitigation: Provide clear build instructions

5. Package Manager Distribution (Not just GitHub releases)

Decision: Target Homebrew, apt, pacman Rationale: Users expect brew install sniffly, not "build from source" Implementation: Create packages in Phase 8 Benefit: Wider adoption, professional image

---

Success Metrics

Technical Success

• ✅ Builds on macOS and Linux without errors
• ✅ Handles 1M+ files in < 10 seconds scan time
• ✅ Renders at 60fps with 1000s of visible nodes
• ✅ Uses < 1GB RAM for 1M files
• ✅ No memory leaks (valgrind clean)

Community Success

• 🎯 1,000 GitHub stars in first 3 months
• 🎯 10,000 downloads in first 6 months
• 🎯 Accepted into Homebrew and major Linux repos
• 🎯 5+ external contributors
• 🎯 Featured on Hacker News or /r/programming

Philosophy Success

• 🎯 Proves Fortran can build modern GUIs
• 🎯 Becomes showcase example for gtk-fortran
• 🎯 Inspires other Fortran GUI projects
• 🎯 Mentioned in "Fortran can do that?!" articles

---

Risk Assessment

Risk	Probability	Impact	Mitigation
gtk-fortran bugs/limitations	Medium	High	Join community early, contribute fixes
Performance insufficient	Low	High	Profile early, optimize, viewport culling
GTK4 not native on macOS	Low	Medium	Accept "good enough", focus on functionality
Build complexity scares users	Medium	Medium	Package managers, pre-built binaries
Cushion algorithm too complex	Low	Low	Well-documented (Van Wijk paper), examples exist
Timeline slips	Medium	Low	Phases are independent, can adjust scope

---

Documentation Created

All planning documents are complete and ready:

1. README.md - Project overview, status, quick links
2. SNIFFLY_MASTER_PLAN.md - Complete 14-week roadmap (comprehensive!)
3. TECHNICAL_STACK.md - Deep dive on all technology choices
4. QUICKSTART.md - 30-minute setup guide with examples
5. GETTING_STARTED.md - Contributor guide, workflow, style
6. PROJECT_SUMMARY.md - This document
7. LICENSE - MIT License
8. meson.build - Build configuration
9. .gitignore - Git ignore rules

Total Documentation: ~15,000 words across 9 files

---

Project Structure Created

sniffly/
├── README.md
├── SNIFFLY_MASTER_PLAN.md
├── TECHNICAL_STACK.md
├── QUICKSTART.md
├── GETTING_STARTED.md
├── PROJECT_SUMMARY.md
├── LICENSE
├── meson.build
├── .gitignore
│
├── app/                 # (empty, ready for main.f90)
├── src/
│   ├── core/            # (empty, ready for modules)
│   ├── layout/
│   ├── gui/
│   ├── rendering/
│   └── state/
├── test/                # (empty, ready for tests)
├── docs/                # (empty, ready for docs)
└── examples/            # (empty, ready for examples)

---

Next Steps (Immediate)

Week 1: Environment Setup

1. Install Dependencies

   # macOS
   brew install gtk4 gfortran meson ninja
   
   # Ubuntu
   sudo apt install libgtk-4-dev gfortran meson ninja-build
   

2. Build gtk-fortran

   git clone https://github.com/vmagnin/gtk-fortran.git
   cd gtk-fortran
   cmake -B build && cmake --build build
   sudo cmake --install build
   

3. Test GTK4 Works

   • Follow QUICKSTART.md hello world example
   • Verify window opens
   • Verify Cairo drawing works

4. Create First Modules

   • Port src/types.f90 from sniffert
   • Port src/file_system.f90 from sniffert
   • Create app/main.f90 with basic GTK app

Week 2: Basic UI

1. Create gtk_app Module

   • Initialize GTK application
   • Create main window
   • Add menu bar skeleton

2. Create treemap_widget Module

   • Custom GtkDrawingArea
   • Connect draw signal
   • Draw static rectangles (test)

3. Test Build System

   • Update meson.build with sources
   • Build and run
   • Verify end-to-end compilation

---

Long-term Vision

Version 1.0 (Week 14)

• ✅ Feature parity with terminal sniffert
• ✅ Beautiful GUI with cushion effects
• ✅ Packages for macOS and Linux
• ✅ Documentation complete

Version 1.x (Months 2-6)

• Multiple tabs for different scans
• Export treemap as images
• Compare directory snapshots
• Cloud storage integration (?)

Version 2.0 (6+ months)

• Plugin system for custom layouts
• Network drive scanning
• Advanced filtering (by owner, permissions)
• Duplicate file detection

---

Relationship to sniffert

Sniffly is the GUI companion to sniffert:

Feature	sniffert (terminal)	sniffly (GUI)
Interface	Terminal (ncurses)	Native window (GTK4)
Input	Keyboard only	Mouse + keyboard
Visual	ASCII art	Beautiful cushion maps
Performance	Lightweight	More resource-intensive
Use Case	SSH, servers	Desktop workstations
Shared Code	Types, scanning, layout algorithms

Both prove Fortran can do modern UIs!

---

Why This Will Succeed

1. Solid Foundation

   • Proven algorithms from sniffert
   • gtk-fortran is mature and maintained
   • GTK4 is modern and well-documented

2. Clear Plan

   • 8 phases with specific deliverables
   • Each phase builds on previous
   • Realistic timeline with buffer

3. Technical Excellence

   • Performance targets defined
   • Testing strategy planned
   • Package distribution planned

4. Community Appeal

   • "Fortran can do that?!" factor
   • Useful tool people actually need
   • Open source, easy to contribute

5. Proven Demand

   • SpaceSniffer is popular on Windows
   • Unix users want equivalent
   • No good open-source alternative exists

---

Quotes to Remember

"Why Fortran?" "Why not? It's fast, proven, and this proves it can do anything."

"Is gtk-fortran mature enough?" "Yes! It's been around since 2011, actively maintained, and production-ready."

"Can Fortran really do GUIs?" "Watch us. We're building a SpaceSniffer clone that will blow your mind."

---

Final Checklist

Planning Phase Complete:

• ✅ Research SpaceSniffer features
• ✅ Research gtk-fortran capabilities
• ✅ Choose technology stack
• ✅ Design architecture
• ✅ Create module structure
• ✅ Write comprehensive documentation
• ✅ Create project structure
• ✅ Define success metrics
• ✅ Assess risks
• ✅ Create timeline

Status: Ready to Begin Development! 🚀

---

Contact & Links

• Project Location: /Users/matthewwolffe/Documents/GithubOrgs/FortranGoingOnForty/sniffly
• Related Project: ../sniffert (terminal version)
• Main Documentation: SNIFFLY_MASTER_PLAN.md
• Quick Start: QUICKSTART.md

---

Sniffly: Proving Fortran Can Build Beautiful GUIs

Created: 2025-11-04 Planning Phase: Complete ✅ Next Phase: Development Begins 🚀