TunaCode Source Code Structure Tree
====================================

Generated: 2026-01-04
Depth: 0 (root-level analysis)
Source: /Users/tuna/Desktop/tunacode/src/tunacode/

Legend:
  →  Dependency direction
  *  Key integration point (seam)
  🔧  Tool implementation
  🎨  UI component
  🧠  Core logic
  ⚙️  Configuration
  📝  Documentation/template

src/tunacode/
│
├── 📦 Root Module
│   ├── __init__.py              # Package marker
│   ├── constants.py             # * Global constants, themes, limits
│   ├── exceptions.py            # * Exception hierarchy with recovery
│   └── py.typed                 # Type hint marker
│
├── 🎨 ui/                       # Presentation Layer
│   ├── app.py                   # * Main Textual application
│   ├── main.py                  # * REPL entry point & orchestration
│   ├── shell_runner.py          # TUI shell wrapper
│   ├── repl_support.py          # REPL utilities
│   ├── styles.py                # Style definitions
│   │
│   ├── commands/                # UI command handlers
│   │   ├── (slash commands)
│   │   └── (REPL commands)
│   │
│   ├── components/              # Reusable UI components
│   │   └── (composite widgets)
│   │
│   ├── screens/                 # Full-screen modals
│   │   ├── setup_screen.py      # Setup wizard
│   │   ├── model_picker.py      # Model selection
│   │   └── (other dialogs)
│   │
│   ├── widgets/                 # Custom Textual widgets
│   │   └── (specialized widgets)
│   │
│   ├── renderers/               # Output formatting
│   │   └── tools/               # Tool-specific renderers
│   │       ├── bash_renderer.py
│   │       ├── grep_renderer.py
│   │       ├── read_file_renderer.py
│   │       └── (other renderers)
│   │
│   ├── headless/                # Non-interactive execution
│   │   └── (headless mode)
│   │
│   └── styles/                  # CSS & themes
│       └── (.tcss files)
│
├── 🧠 core/                     # Business Logic Layer
│   ├── agents/                  # Agent system
│   │   ├── main.py              # * Primary agent orchestration
│   │   ├── research_agent.py    # * Codebase research specialist
│   │   ├── delegation_tools.py  # Agent tool delegation
│   │   └── agent_components/    # Agent building blocks
│   │       ├── (state modules)
│   │       ├── (planning modules)
│   │       └── (tool orchestrators)
│   │
│   ├── state/                   # State management
│   │   └── (application state models)
│   │
│   ├── prompting/               # Prompt construction
│   │   ├── (prompt builders)
│   │   └── (template system)
│   │
│   ├── setup/                   # Setup wizard logic
│   │   └── (setup components)
│   │
│   ├── background/              # Async task execution
│   │   └── (background jobs)
│   │
│   ├── token_usage/             # Cost tracking
│   │   ├── (usage calculation)
│   │   └── (pricing integration)
│   │
│   └── logging/                 # Structured logging
│       └── (log system)
│
├── 🔧 tools/                    # Capabilities Layer
│   ├── bash.py                  # * Shell command execution
│   ├── grep.py                  # * Content search (regex)
│   ├── glob.py                  # * File pattern matching
│   ├── read_file.py             # * File reading
│   ├── write_file.py            # * File creation
│   ├── update_file.py           # * File editing
│   ├── list_dir.py              # Directory listing
│   ├── web_fetch.py             # HTTP requests
│   ├── react.py                 # User input prompts
│   ├── todo.py                  # TODO list management
│   ├── decorators.py            # * Tool decorators (retry, logging)
│   ├── xml_helper.py            # XML parsing
│   │
│   ├── authorization/           # Permission system
│   │   └── (auth logic)
│   │
│   ├── grep_components/         # Search implementation
│   │   └── (grep internals)
│   │
│   ├── prompts/                 # Tool descriptions
│   │   └── (tool prompts)
│   │
│   └── utils/                   # Tool utilities
│       └── (helper functions)
│
├── ⚙️ configuration/            # Settings Layer
│   ├── __init__.py
│   ├── settings.py              # * User preferences
│   ├── models.py                # * Model definitions
│   ├── models_registry.json     # Model database
│   ├── pricing.py               # * Cost calculation
│   └── defaults.py              # Factory defaults
│
├── 📟 cli/                      # Command-Line Interface
│   ├── commands/
│   │   ├── implementations/     # Command handlers
│   │   │   └── (command logic)
│   │   └── slash/               # Slash command specs
│   │       └── (command definitions)
│   │
│   ├── repl_components/         # REPL building blocks
│   │   └── (reusable parts)
│   │
│
├── 📚 Supporting Modules
│
│   ├── indexing/                # Code search infrastructure
│   │   └── (index building)
│   │
│   ├── lsp/                     # Language Server Protocol
│   │   └── (LSP client)
│   │
│   ├── services/                # External integrations
│   │   ├── (git operations)
│   │   ├── (HTTP client)
│   │   └── (process management)
│   │
│   ├── types/                   # Type definitions
│   │   └── (common types)
│   │
│   ├── utils/                   # General utilities
│   │   ├── config/              # Config parsing
│   │   ├── messaging/           # Message formatting
│   │   ├── parsing/             # Text parsing
│   │   ├── system/              # System operations
│   │   └── ui/                  # UI utilities
│   │
│   ├── tutorial/                # Interactive tutorials
│   │   └── (tutorial content)
│   │
│   ├── prompts/                 # Prompt templates
│   │   ├── research/            # Research prompts
│   │   │   └── sections/        # Prompt components
│   │   └── sections/            # General prompts
│   │
│   ├── templates/               # Code generation
│   │   └── (code templates)
│   │
│   └── tools_utils/             # Shared tool utilities
│       └── (tool helpers)
│
└── 🗂️ Data Files (in configuration/)
    └── models_registry.json     # Model database

====================================
Architecture Layers (Bottom → Top)
====================================

┌─────────────────────────────────┐
│  📟 CLI / 🎨 UI (Presentation)  │  ← User interaction
├─────────────────────────────────┤
│  🧠 Core (Business Logic)       │  ← Agent orchestration
├─────────────────────────────────┤
│  🔧 Tools (Capabilities)        │  ← Agent actions
├─────────────────────────────────┤
│  ⚙️ Configuration (Settings)    │  ← App configuration
└─────────────────────────────────┘

====================================
Dependency Flow
====================================

UI → Core → Tools → Configuration
 ↓
All modules → Types → Exceptions → Constants

====================================
Key Integration Points (Seams)
====================================

Root Module:
  • constants.py    → Constants used everywhere
  • exceptions.py   → Exception base for all modules
  • types/          → Type definitions used everywhere

UI Module:
  • app.py          → Main application entry
  • main.py         → REPL orchestration
  • renderers/      → Tool output display

Core Module:
  • agents/main.py  → Primary agent logic
  • state/          → Application state
  • prompting/      → Prompt construction

Tools Module:
  • decorators.py   → Tool wrapping
  • Individual tools → Tool implementations

Configuration Module:
  • settings.py     → User preferences
  • models.py       → Model definitions
  • pricing.py      → Cost tracking

CLI Module:
  • commands/       → Command implementations
  • repl_components/ → REPL building blocks

====================================
File Counts by Module
====================================

Root Module:        3 Python files
UI:                 ~20+ Python files + CSS
Core:               ~15+ Python files
Tools:              ~13 Python files
Configuration:      5 Python files + 1 JSON
CLI:                ~10+ Python files + CSS
Supporting Modules: ~30+ Python files

Total:              ~100+ Python files

====================================
Naming Conventions
====================================

Directories/Files:  snake_case
Classes:             CamelCase
Functions/Methods:   snake_case
Constants:           UPPER_SNAKE_CASE
Enums:               CamelCase (class), UPPER_SNAKE_CASE (values)

====================================
Analysis Complete
====================================

Depth: 0 (root-level)
Documentation: 7 MD files generated
Output: /Users/tuna/Desktop/tunacode/docs/codebase-map/structure/

Next: Proceed to depth 1 analysis for detailed subdirectory examination
