Termigo Development

Development guidance for working with Termigo, a modern terminal client management tool built with Tauri (Rust backend) and React (TypeScript frontend). Enables cross-platform SSH connection management, terminal sessions, port forwarding, and credential storage.

Project Architecture

Frontend (React + TypeScript)

**Main Layout:**

`routes/__root.tsx` - Root layout with sidebar navigation and conditional terminal/page rendering

App switches between terminal view and management pages based on `activeTerminal` state

**Core Features:**

Hosts Management (`/hosts`) - SSH host configuration and connection

Identities Management (`/identities`) - SSH identity/credential storage

Private Keys Management (`/private-keys`) - SSH key management

Settings (`/settings`) - Application configuration and updates

Terminals - Full-screen terminal sessions with xterm.js

**State Management:**

Zustand stores with Immer middleware for terminal and port forwarding state

**Backend Communication:**

All Rust backend calls through `core/invoker.ts`

Services provide typed interfaces for each feature

Uses Tauri's `invoke()` API with custom error handling

Backend (Rust/Tauri)

Located in `src-tauri/` directory

Handles SSH connections, terminal streams, credential storage

Commands invoked from frontend via `invoker.ts`

UI Components (Shadcn/ui)

Dark mode only (hardcoded in `__root.tsx`)

Components in `components/ui/` follow shadcn patterns

Feature-specific components in `components/pages/`

Reusable shared components in `components/shared/`

Development Workflow

When working on Termigo:

1. **Always use semantic color variables** (never hardcoded colors):

- Backgrounds: `bg-background`, `bg-card`, `bg-muted`, `bg-primary`, `bg-secondary`, `bg-destructive`

- Text: `text-foreground`, `text-card-foreground`, `text-muted-foreground`, `text-primary-foreground`

- Borders: `border-border`, `border-input`

- Pair backgrounds with corresponding foreground colors for proper contrast

2. **Follow component patterns**:

- Card-based layouts for management pages

- Sidebar pattern for create/edit forms

- React Hook Form with Zod validation

- TanStack Query for server state management

3. **Backend integration**:

- Call all Tauri commands through `invoker.ts`

- Use services layer for typed backend communication

- Handle `InvokerError` for user-friendly error messages

4. **Run appropriate commands**:

- Frontend dev: `npm run dev`

- Tauri dev mode: `npm run tauri dev` (runs both frontend and backend)

- Linting: `npm run lint` or `npm run lint:fix`

- Formatting: `npm run format`

- Build: `npm run tauri build`

5. **Code quality checks**:

- Pre-commit hooks automatically run linting and formatting

- Run `cargo fmt --check` and `cargo clippy` for Rust code

6. **Routing**:

- Uses TanStack Router with file-based routing

- App navigates to `/hosts` on start

- Terminal overlay system for switching between management and terminal views

Color System

The app uses a comprehensive dark theme color system with CSS variables. Key semantic colors:

`--background` (222.2 84% 4.9%) - Main app background

`--card` (222.2 84% 4.9%) - Card backgrounds

`--primary` (210 40% 98%) - Primary buttons

`--secondary` (217.2 32.6% 17.5%) - Secondary elements

`--muted` (217.2 32.6% 17.5%) - Muted backgrounds

`--destructive` (0 62.8% 30.6%) - Destructive actions

`--border` (217.2 32.6% 17.5%) - Borders

**Always use semantic classes based on meaning, not appearance.**

Key Files

`routes/__root.tsx` - Root layout

`core/invoker.ts` - Backend communication layer

`interfaces/` - TypeScript interfaces

`services/` - Typed backend service wrappers

`stores/` - Zustand state stores

`src-tauri/` - Rust backend code

termigo-development