# Architecture

## Overview

`git-tui` is a single executable Python script that provides a terminal UI for common Git commands.

## Module Responsibilities

- `git-tui`:
  - Initializes and runs the curses application loop.
  - Handles startup bootstrap for non-repository directories.
  - Handles startup onboarding for repositories without configured remotes.
  - Renders a menu-driven UI with keyboard navigation.
  - Executes Git subprocess commands and displays command output.
  - Executes provider-specific publication for new remote repositories:
    - GitHub via `gh` CLI.
    - Gitea via HTTPS API, followed by an SSH or token-authenticated HTTPS push.
  - Executes provider-specific connection to existing remote repositories:
    - GitHub by resolving owner or URL input to `origin`.
    - Gitea by preserving a full clone URL or retrieving exact SSH/HTTPS clone endpoints through the repository API.
  - Synchronizes Gitea connections by inspecting ancestry, fast-forwarding the
    side that is behind, or asking the user how to resolve divergent histories.
  - Preserves local history on a backup branch before a user-confirmed local
    replacement and uses `--force-with-lease` for remote replacement.
  - Removes local remote configuration through a conditional disconnect action.
  - Implements file selection for staged and unstaged operations.

## Public API and Contracts

- Command entry point: `git-tui` executable script.
- Runtime contract:
  - Must be executed in a terminal that supports curses.
  - Must be run from a writable project directory.
  - Requires `git` to be installed and available in `PATH`.
  - Requires `gh` in `PATH` only for GitHub publication.
  - Requires Gitea API token for Gitea publication.
  - Temporarily suspends curses for network Git subprocesses so terminal authentication and credential helpers remain available.

## Data Model

- `ChangedFile`:
  - `index_status`: index status marker from `git status --short`.
  - `worktree_status`: worktree status marker from `git status --short`.
  - `path`: repository-relative file path.

## Build and Deployment Rules

- No build step is required.
- Deployment is a direct executable file install (copy or symlink).

## Cross References

- Usage and install details: [`doc/usage.md`](usage.md)
- Change tracking: [`CHANGELOG.md`](../CHANGELOG.md)