# cd-browser Architecture

Author: Saky

This document describes the architecture of the `cd-browser` terminal
navigation tool.

------------------------------------------------------------------------

# 1. Purpose

`cd-browser` provides a keyboard‑driven terminal interface to explore
directories and return a selected path to the shell.

It solves a limitation of shells:

A program cannot directly change the parent shell directory.

Instead:

1.  The application returns a path
2.  A shell wrapper performs `cd`

------------------------------------------------------------------------

# 2. High Level Architecture

The project follows a layered architecture:

CLI Layer ↓ UI Layer ↓ Navigator Layer ↓ Filesystem Layer

History is used by the navigator.

------------------------------------------------------------------------

# 3. Modules

## filesystem.py

Responsibilities:

-   inspect filesystem
-   list directories
-   detect children directories

Core structures:

DirectoryEntry

Functions:

list_directories() has_subdirectories()

------------------------------------------------------------------------

## history.py

Handles navigation history.

Features:

-   visit(path)
-   back()
-   forward()
-   select()

Used by navigator.

------------------------------------------------------------------------

## navigator.py

Core state machine of the application.

Tracks:

-   current_path
-   visible directory entries
-   selected index
-   expanded nodes

Handles:

-   entering directories
-   parent navigation
-   tree expansion
-   history integration

------------------------------------------------------------------------

## ui.py

Terminal interface using curses.

Responsibilities:

-   render directory list
-   highlight selection
-   process keyboard input

Keys used:

↑ ↓ navigation → expand ← collapse ESC exit

------------------------------------------------------------------------

## cli.py

Application orchestrator.

Responsibilities:

-   create navigator
-   start terminal UI
-   capture resulting path

------------------------------------------------------------------------

## main.py

Entrypoint.

Responsibilities:

-   initialize logging
-   start CLI flow
-   print final path

------------------------------------------------------------------------

# 4. Shell Integration

Shell wrapper function:

cd\_() { local target target="$(cd_browser)"
  if [ -n "$target" \] && \[ -d "$target" ]; then
    cd "$target" fi }

This enables:

cd\_

to change the working directory.

------------------------------------------------------------------------

# 5. Terminal Handling

The application attaches its UI to:

/dev/tty

This allows the UI to function even when stdout is captured by shell
substitution.

stdout is reserved for:

final directory path

stderr is used for logging.

------------------------------------------------------------------------

# 6. Validation

Quality tools ensure correctness:

black -- formatting\
ruff -- linting\
mypy -- type checking\
pytest -- testing

Commands:

make fix make quality make ci

------------------------------------------------------------------------

# 7. Extensibility

Future improvements:

-   enhanced navigation model
-   fuzzy search
-   bookmark directories
-   persistent history
-   configuration file

------------------------------------------------------------------------

# End