TFE CLAUDE.md

TFE Architecture & Development Guide

This document is a concise index to TFE's architecture and development documentation. For detailed information, follow the links to specific guides.

---

Quick Start: When to Read What

Before starting ANY task, check this decision tree:

• 🎨 Working on UI/rendering/width calculations? → Read docs/LESSONS_LEARNED.md FIRST (critical!)
• 📦 Adding a new feature? → Read "Where Does My Code Go?" below
• 🔧 Need to know what a module does? → See Module Quick Reference below or docs/MODULE_DETAILS.md
• 📝 Adding keyboard shortcuts or display modes? → Read docs/DEVELOPMENT_PATTERNS.md
• 🔒 Questions about "security issues"? → Read docs/THREAT_MODEL.md
• 📚 Managing documentation? → Read docs/DOCUMENTATION_GUIDE.md
• 🏗️ Want architectural history? → Read docs/REFACTORING_HISTORY.md

After making code changes:

• ⚠️ ALWAYS run: go test ./... to verify tests pass (see Testing Strategy)
• ⚠️ ALWAYS run: ./build.sh OR manually update both ~/bin/tfe and ~/.local/bin/tfe (see Building and Installing)

---

Architecture Overview

TFE follows a modular architecture where each file has a single, clear responsibility. This organization was established through a comprehensive refactoring that reduced main.go from 1668 lines to just 21 lines, distributing functionality across 19 focused modules.

Core Principle

When adding new features, always maintain this modular architecture by creating new files or extending existing modules rather than adding everything to main.go.

---

File Structure

tfe/
├── main.go                    # Entry point ONLY (21 lines)
├── types.go                   # Type definitions & enums
├── styles.go                  # Lipgloss style definitions
├── model.go                   # Model initialization & layout
├── update.go                  # Main update dispatcher
├── update_keyboard.go         # Keyboard event handling
├── update_mouse.go            # Mouse event handling
├── view.go                    # View dispatcher
├── menu.go                    # Menu bar rendering
├── render_preview.go          # Preview rendering
├── render_file_list.go        # File list views
├── file_operations.go         # File operations (load, preview, CRUD)
├── file_icons.go              # File type detection & icons
├── text_wrapping.go           # Width calculations & text wrapping
├── editor.go                  # External tool integration
├── command.go                 # Command execution
├── git_operations.go          # Git operations & status queries
├── dialog.go                  # Dialog system
├── context_menu.go            # Context menu
├── favorites.go               # Favorites/bookmarks
├── trash.go                   # Trash/recycle bin
├── prompt_parser.go           # Prompt template parsing
├── fuzzy_search.go            # Fuzzy file search
├── terminal_graphics.go       # HD image preview
├── helpers.go                 # Helper functions
├── file_watcher.go            # fsnotify file watcher & debouncing
├── theme.go                   # Configurable theme system (TOML)
├── agent_awareness.go         # AI agent session detection & conversation viewer
├── render_jsonl.go            # JSONL conversation file rendering
├── render_layout.go           # Layout rendering & tab bar
├── render_prompts.go          # Prompt template rendering
├── tmux.go                    # Tmux integration
├── actions.go                 # Shared action helpers for state mutations
└── ghost_text.go              # AI command suggestions via ? prefix