Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
94 lines (87 loc) · 4.66 KB

ARCHITECTURE.md

File metadata and controls

94 lines (87 loc) · 4.66 KB

GitNapse Architecture

Contents

High-Level Design

  • src/main.rs: CLI entrypoint, auth commands, and file-download command.
  • src/app/mod.rs: TUI state machine, event loop, key/mouse dispatch.
  • src/app/render.rs: layout and widget rendering, pane detection, modal rendering.
  • src/app/theme.rs: color palette strategy and responsive navigation hints.
  • src/cache.rs: local preview cache with TTL and disk persistence.
  • src/github.rs: GitHub API client for search/branches/tree/content/auth-user.
  • src/auth.rs: token loading, secure storage, token CLI subcommands.
  • src/oauth.rs: OAuth device-flow login powered by octocrab.
  • src/oauth_session.rs: secure OAuth session persistence, expiry metadata, and refresh attempt path.
  • src/config.rs: persisted account preferences (account.json).
  • src/models.rs: DTO/domain models for GitHub responses and internal tree nodes.
  • src/syntax.rs: preview syntax-aware formatting.

Execution Flow

  1. App resolves token from environment or local secure file.
  2. GitHub client initializes headers and optional bearer auth.
  3. TUI starts with default query and paginated repository search.
  4. User opens repository and selects branch when needed.
  5. Tree is loaded and lazily revealed for large repositories.
  6. File preview is loaded from cache or API and can be scrolled/focused.
  7. User can clone repo, download current previewed file, or switch back to search list.

Authentication Strategy

  • Preferred source: GITHUB_TOKEN.
  • Fallback source: local stored token under user config directory.
  • OAuth device flow is available via gitnapse auth oauth login using octocrab.
  • OAuth session metadata is persisted to support token lifecycle handling and optional refresh.
  • UNIX permissions are restricted for token file (0600).
  • Token can be updated inside TUI via modal and validated against /user.

Account Configuration Strategy

  • Persisted file: account.json in project config directory.
  • Stored keys include:
    • preferred_clone_dir
    • last_branch_by_repo
  • Design remains extensible for future account-wide API preferences.

Terminal UX Strategy

  • Keyboard-first navigation with mouse augmentation.
  • Responsive split view: horizontal on wide terminals, vertical on narrow terminals.
  • Preview pane is independently focusable and scrollable.
  • Mouse behaviors:
    • single click selects
    • double click opens repo/file
    • wheel scrolls tree/preview by pointer location
  • Navigation bar wraps across lines based on terminal width.
  • Selection colors use full references.md palette with contrast-safe foreground.

Network and Integration Notes

  • HTTP layer: reqwest blocking client for deterministic TUI loop behavior.
  • OAuth device flow exchange uses octocrab against https://github.com/login/* routes.
  • GitHub endpoints:
    • /search/repositories
    • /repos/{full_name}/branches?per_page=100
    • /repos/{full_name}/git/trees/{branch}?recursive=1
    • /repos/{full_name}/contents/{path}
    • /user
  • Clone integration uses local git executable.
  • Single-file download writes content directly to user-selected local path.