# Architecture

## Why this shape

The project should not become a giant `main.go` that mixes rendering, key handling, filesystem I/O and business rules. The architecture is split so the UI remains reactive and file operations stay isolated.

## High-level modules

- `cmd/vcom`
  Entry point, config loading, program startup.
- `internal/config`
  Config schema, defaults, search paths and TOML parsing.
- `internal/fs`
  Filesystem model, directory scanning, previews and file operations.
- `internal/theme`
  Theme presets and style tokens.
- `internal/ui`
  Bubble Tea model, key map, pane rendering, modal flow and layout.

## State model

The Bubble Tea root model owns:

- terminal dimensions
- full config
- active browser pane
- left and right pane state
- center preview state
- transient modal state
- busy/status state for async work

This keeps the Elm-style update loop simple:

1. key or resize event arrives
2. model decides whether to mutate local state or start async work
3. async work returns a typed message
4. view renders from plain state

## Pane model

Each side pane stores:

- current path
- scanned entries
- cursor index
- scroll offset
- cached directory sizes for entries calculated on demand

This is intentionally independent from rendering details, so the pane can be unit-tested later without Lip Gloss.

## Preview pipeline

The center pane is driven only by the current selection from the active side pane.

Preview strategies:

- directory preview
  Shows child entries and summary data.
- text preview
  Reads up to a configured byte limit and displays text safely.
- image preview
  Detects dimensions and format through standard Go image decoders.
- binary fallback
  Avoids dumping junk bytes into the terminal.

Metadata shown above the preview:

- kind
- full path
- size
- created time
- modified time
- permissions

Directory size is expensive, so it is not calculated eagerly. Pressing `Space` starts an async scan and updates both:

- side-pane size column
- preview metadata widget

## Configuration design

TOML is used because:

- it is readable in terminal workflows
- comments are first-class
- optional settings can stay commented out for manual enable/disable

The example config enables only MC-like columns by default:

- `name`
- `size`
- `modified`

Additional columns are left commented out so users can literally uncomment them:

- `created`
- `permissions`
- `extension`

Other useful config areas:

- startup paths for left and right panes
- theme preset
- hidden file visibility
- sort field and reverse mode
- center pane width ratio
- confirmation behavior
- preview byte limits
- text wrapping in preview
- compact path display

## Rendering strategy

The side panes are custom-rendered rather than built on top of the generic table bubble.

Reasoning:

- MC-like directory panes are not just tables
- we need tight control over selection styling, truncation and empty states
- the center pane uses a different rendering model than the side panes

Bubble usage:

- `bubbletea`
  event loop and async commands
- `bubbles/key`
  declarative key bindings
- `bubbles/textinput`
  mkdir modal
- `bubbles/viewport`
  preview scrolling surface
- `lipgloss`
  all layout and styling

## Operations

The first operational slice is intentionally MC-core:

- copy selected entry to passive pane directory
- move selected entry to passive pane directory
- create directory in active pane
- delete selected entry
- refresh active pane

These operations are dispatched asynchronously to avoid freezing the TUI on large directories.

Overwrite handling is decided before the async operation begins:

- if the target does not exist, the operation runs directly
- if the target exists and overwrite confirmation is enabled, the UI opens a modal
- if overwrite confirmation is disabled, the operation replaces the target immediately

## Theme system

Themes are token-based rather than style-object based.

Each preset defines semantic colors:

- background
- panel
- panel inactive
- border
- border active
- text
- muted text
- accent
- selection
- warning
- danger
- footer key

This allows future user-defined themes without touching UI logic.

The current UI also supports runtime theme cycling, but config remains the source of truth for default startup appearance.

## Extension points

The architecture is designed to accept later additions without a rewrite:

- multi-select and batch operations
- file viewer/editor integration
- terminal image protocols
- tab history per pane
- bookmarks and quick-jump
- sort modes
- archive browsing
- search/filter overlay
- pluggable preview providers

## Constraints worth keeping

- never calculate directory sizes during normal navigation
- never read full large files into memory for preview
- keep filesystem code out of `View()`
- keep styling decisions out of `internal/fs`
- prefer typed Tea messages over stringly-typed status events