Architecture and Technical Details
This document provides a comprehensive technical overview of Terminal Jarvis's architecture, design patterns, and internal structure.
Project Structure
The project follows a domain-based modular architecture designed for maintainability, extensibility, and clear separation of concerns:
src/
├── main.rs # Entry point - minimal code, delegates to CLI
├── lib.rs # Library entry point for module organization
├── cli.rs # Clean, expressive CLI interface definitions
├── installation_arguments.rs # Installation commands and NPM validation
├── progress_utils.rs # Theme-integrated messaging and progress indicators
│
├── cli_logic/ # Business logic domain (9 focused modules)
│ ├── mod.rs # Module coordination and re-exports
│ ├── cli_logic_entry_point.rs # Main CLI logic entry point
│ ├── cli_logic_interactive.rs # Interactive T.JARVIS interface
│ ├── cli_logic_tool_execution.rs # Tool execution workflows
│ ├── cli_logic_update_operations.rs # Tool update management
│ ├── cli_logic_list_operations.rs # Tool listing operations
│ ├── cli_logic_info_operations.rs # Tool information display
│ ├── cli_logic_config_management.rs # Configuration management
│ ├── cli_logic_template_operations.rs # Template system operations
│ └── cli_logic_utilities.rs # Shared utility functions
│
├── auth_manager/ # Authentication domain (5 focused modules)
│ ├── mod.rs # Module coordination and re-exports
│ ├── auth_entry_point.rs # Authentication system entry point
│ ├── auth_environment_detection.rs # Environment detection logic
│ ├── auth_environment_setup.rs # Environment configuration
│ ├── auth_api_key_management.rs # API key handling
│ └── auth_warning_system.rs # Browser prevention warnings
│
├── config/ # Configuration domain (5 focused modules)
│ ├── mod.rs # Module coordination and re-exports
│ ├── config_entry_point.rs # Configuration system entry point
│ ├── config_structures.rs # TOML configuration structures
│ ├── config_file_operations.rs # File I/O operations
│ ├── config_manager.rs # Configuration management logic
│ └── config_version_cache.rs # Version caching system
│
├── services/ # External integrations domain (5 focused modules)
│ ├── mod.rs # Module coordination and re-exports
│ ├── services_entry_point.rs # Service layer entry point
│ ├── services_package_operations.rs # Package management operations
│ ├── services_npm_operations.rs # NPM-specific operations
│ ├── services_github_integration.rs # GitHub CLI integration
│ └── services_tool_configuration.rs # Tool configuration mapping
│
├── theme/ # UI theming domain (7 focused modules)
│ ├── mod.rs # Module coordination and re-exports
│ ├── theme_entry_point.rs # Theme system entry point
│ ├── theme_definitions.rs # Theme color definitions
│ ├── theme_config.rs # Theme configuration management
│ ├── theme_global_config.rs # Global theme state
│ ├── theme_background_layout.rs # Background and layout styling
│ ├── theme_text_formatting.rs # Text formatting utilities
│ └── theme_utilities.rs # Theme utility functions
│
├── tools/ # Tool management domain (6 focused modules)
│ ├── mod.rs # Module coordination and re-exports
│ ├── tools_entry_point.rs # Tool system entry point
│ ├── tools_detection.rs # Tool detection and verification
│ ├── tools_command_mapping.rs # Command-to-tool mapping
│ ├── tools_execution_engine.rs # Tool execution engine
│ ├── tools_process_management.rs # Process lifecycle management
│ └── tools_startup_guidance.rs # Tool startup guidance system
│
└── api/ # API framework domain (4 focused modules)
├── mod.rs # Module coordination and re-exports
├── api_base.rs # Base API route configurations
├── api_client.rs # HTTP client abstraction layer
└── api_tool_operations.rs # API tool operation endpoints
Architecture Philosophy
Domain Architecture
main.rs
&lib.rs
: Minimal entry points that delegate to domain modulescli.rs
: Expressive command definitions with optional subcommands (defaults to interactive mode)cli_logic/
: Complete business logic domain including the interactive T.JARVIS interface, tool execution workflows, and operation managementauth_manager/
: Authentication domain with environment detection, browser prevention, and API key managementconfig/
: Configuration domain handling TOML file operations, structure management, and version cachingservices/
: External integrations domain for package management, NPM operations, and GitHub CLI integrationtheme/
: UI theming domain with color definitions, global state management, and formatting utilitiestools/
: Tool management domain covering detection, command mapping, execution, and process lifecycleapi/
: API framework domain for future web integrations (currently unused)
Design Principles
- Domain-Driven Design: Each module represents a distinct business domain
- Single Responsibility: Modules handle one aspect of functionality
- Clear Dependencies: Explicit imports, minimal coupling
- Testability: Pure functions, dependency injection patterns
- Maintainability: Small, focused files (~200-300 lines each)
Configuration System
Terminal Jarvis uses a modular configuration system stored in config/tools/
:
config/
├── tools/
│ ├── claude.toml # Anthropic Claude configuration
│ ├── gemini.toml # Google Gemini configuration
│ ├── qwen.toml # Qwen coding assistant configuration
│ ├── opencode.toml
│ ├── llxprt.toml
│ ├── codex.toml
│ ├── crush.toml
│ ├── goose.toml
│ ├── amp.toml
│ └── aider.toml
└── config.toml # Global Terminal Jarvis settings
Tool Configuration Structure
Each tool configuration file contains:
[tool]
display_name = "Tool Name"
config_key = "tool-key"
description = "Tool description"
cli_command = "tool-command"
requires_npm = true
status = "stable"
[tool.install]
command = "npm"
args = ["install", "-g", "package-name"]
verify_command = "tool --version"
[tool.auth]
env_vars = ["TOOL_API_KEY"]
setup_url = "https://tool-setup-url"
auth_instructions = "Setup instructions"
Benefits of Modular Configuration
- Automatic Discovery: New tools added to
config/tools/
are automatically available - Clear Separation: Per-tool install/auth/feature metadata
- Reduced Drift: Documentation and implementation stay in sync
- Database Ready: Structure supports future database integration
NPM Package Structure
npm/terminal-jarvis/
├── package.json # NPM package configuration
├── bin/
│ └── terminal-jarvis # Binary wrapper
├── src/
│ └── index.ts # TypeScript entry point
├── dist/ # Compiled JavaScript
└── biome.json # Biome linting configuration
Package Architecture
- Rust Binary: Pre-compiled for immediate functionality
- TypeScript Wrapper: NPM integration layer
- Zero Dependencies: Self-contained, no runtime dependencies
Theme System Architecture (v0.0.56+)
Core Theme Components
theme.rs
: Theme definitions with complete ANSI color palettes
- T.JARVIS Theme: Professional blue-based corporate theme with cyan accents
- Classic Theme: Traditional grayscale terminal aesthetic
- Matrix Theme: Green-on-black retro computing style
- Color Management: Comprehensive ANSI escape code handling
theme_config.rs
: Global theme state and configuration management
- Runtime Theme Switching: Dynamic theme changes without restart
- Theme Persistence: User preferences maintained across sessions
- Global State: Centralized theme state accessible throughout application
progress_utils.rs
: Theme-integrated messaging system
- Consistent Colors: All messages use current theme's color palette
- Professional Presentation: Success, warning, and error messages with themed colors
- T.JARVIS Branding: Integrated T.JARVIS advisory system
Authentication System
Environment Detection
The authentication manager detects various environments:
- CI/CD Systems: GitHub Actions, GitLab CI, CircleCI, Travis CI
- Cloud Environments: Codespaces, Gitpod, Cloud9
- SSH Sessions: Remote terminal sessions
- Containers: Docker, Podman environments
- Headless Systems: No display server available
Browser Prevention
When headless environments are detected:
- Sets
NO_BROWSER
environment variables - Displays clear warnings about authentication requirements
- Provides API key setup instructions
- Prevents hanging on browser-based auth flows
API Key Management
- Validates environment variables before tool launch
- Provides setup URLs and instructions
- Graceful handling of missing credentials
- Integration with tool-specific auth flows
Tool Execution Engine
Execution Flow
- Pre-flight Checks: Verify tool installation and authentication
- Environment Setup: Configure NO_BROWSER flags if needed
- Process Spawn: Launch tool with proper stdio handling
- Session Management: Track tool state and handle signals
- Continuation Support: Seamlessly resume after auth flows
- Cleanup: Proper process termination and resource cleanup
Special Tool Handling
OpenCode: Requires initial delay for terminal state preparation
// OpenCode-specific initialization
if tool == "opencode" {
tokio::time::sleep(Duration::from_millis(500)).await;
}
Gemini: API key validation before execution
Qwen: Dashboard/scope detection and API key management
Installation System
Multi-Method Installation Support
Terminal Jarvis supports three installation methods:
- NPM-based: Standard npm install commands
- curl-based: Publisher-provided installation scripts (Goose)
- uv-based: Python package installation (Aider)
Installation Flow
1. Check prerequisites (npm, curl, uv availability)
2. Execute installation command
3. Verify installation success
4. Cache tool status
5. Provide next steps
Validation
- Verifies package existence on NPM registry
- Checks binary availability post-install
- Tests version commands
- Updates internal tool state
Adding New Tools
Steps to Add a Tool
- Create tool configuration in
config/tools/
:
[tool]
display_name = "New Tool"
config_key = "newtool"
description = "New AI coding tool"
cli_command = "newtool"
requires_npm = true
status = "testing"
[tool.install]
command = "npm"
args = ["install", "-g", "newtool-package"]
verify_command = "newtool --version"
[tool.auth]
env_vars = ["NEWTOOL_API_KEY"]
setup_url = "https://example.com/newtool/setup"
auth_instructions = "Visit setup URL to get API key"
-
Tool automatically discovered: No code changes needed!
-
Test the integration:
terminal-jarvis list # Should show new tool
terminal-jarvis info newtool
terminal-jarvis install newtool
This modular approach ensures new tools integrate cleanly with detection, info display, and execution while keeping changes isolated.
Testing Strategy
Test Coverage
Terminal Jarvis has 33 comprehensive tests covering:
- Tool Management: Installation, updates, detection
- Configuration System: TOML parsing, validation
- CLI Interface: Command parsing, help output
- Authentication: Environment detection, browser prevention
- Package Management: NPM operations, version checks
Test Scripts
smoke-test.sh
: Quick validation of core functionalitytest-core-functionality.sh
: Comprehensive test suitelocal-ci.sh
: Full CI pipeline validation
Performance Considerations
Caching
- Tool Status: Cached after first detection
- Version Information: Cached with configurable TTL
- Configuration: Loaded once and cached in memory
Concurrent Operations
- Tool Updates: Parallel updates for multiple tools
- Installation: Concurrent prerequisite checks
- Detection: Parallel tool verification
Resource Management
- Process Cleanup: Proper signal handling and termination
- File Descriptors: Careful stdio management
- Memory: Efficient data structures, minimal allocations
Future Architecture Plans
Database Integration
- Move from TOML files to database storage
- Support for tool usage analytics
- User preference storage
- Session history tracking
API Layer
The api/
domain is prepared for:
- RESTful API endpoints
- Tool management via HTTP
- Remote tool execution
- Web dashboard integration
Plugin System
Future support for:
- Custom tool definitions
- User-contributed integrations
- Dynamic tool loading
- Extension marketplace
Development Guidelines
Module Organization
- Keep files focused and small (200-300 lines)
- Use
mod.rs
for module coordination - Clear re-exports from
mod.rs
- Consistent naming:
{module}_{domain}_{operation}.rs
Error Handling
- Use
anyhow::Result
for error propagation - Provide context with
.context()
- User-friendly error messages
- Graceful degradation where possible
Code Style
- Run
cargo fmt
before commits - Pass
cargo clippy
with no warnings - Add doc comments for public APIs
- Follow Rust naming conventions
Next Steps
- Testing Guide - Testing strategies and workflows
- Contributing Guide - How to contribute to Terminal Jarvis
- Configuration Guide - Customize Terminal Jarvis