headquarter/docs/architecture/frontend.md

# Frontend Architecture

## Overview

The Headquarter frontend is a React-based single-page application (SPA) built with modern tooling and designed for modularity and maintainability.

## Tech Stack

| Layer | Technology | Version |
|-------|-----------|---------|
| Framework | React | ^18.2.0 |
| Router | React Router | ^6.20.0 |
| Bundler | Vite | ^5.0.0 |
| Language | TypeScript | ^5.3.0 |
| Styling | CSS3 with CSS Variables | - |
| Testing | Vitest + React Testing Library | ^4.1.6 |

## Directory Structure

```
apps/web/src/
├── api/                  # API clients
│   ├── auth.ts          # Authentication API
│   ├── projects.ts      # Project API
│   ├── git_repositories.ts  # Repository API
│   ├── ssh_keys.ts      # SSH key API
│   ├── tool_types.ts    # Tool type API
│   ├── users.ts         # User API
│   ├── sessions.ts      # Tool instance sessions API
│   └── settings.ts      # Settings API
├── components/           # Reusable components
│   ├── app-shell.tsx    # Main app layout
│   ├── terminal.tsx     # xterm.js terminal component
│   ├── protected-route.tsx  # Auth guard
│   └── [more...]
├── context/             # React contexts
│   └── auth.tsx         # Auth state management
├── hooks/               # Custom hooks
│   ├── use-auth.ts      # Auth hook
│   ├── use-theme.ts     # Theme hook
│   └── use-terminal-connection.ts  # Terminal WebSocket lifecycle
├── pages/               # Page components (routes)
│   ├── dashboard.tsx    # Dashboard
│   ├── projects.tsx     # Project list
│   ├── repo-workspace.tsx   # Repository workspace
│   ├── git-history.tsx  # Git history
│   ├── git-repositories.tsx # Repository management
│   ├── terminal.tsx     # Web terminal
│   ├── profile.tsx      # User profile
│   ├── settings.tsx     # User settings
│   ├── tool-types.tsx   # Tool types
│   ├── ssh-keys.tsx     # SSH keys
│   └── [more...]
├── styles/              # Global styles
│   ├── index.css        # Main stylesheet
│   └── [more...]
├── types.ts             # Shared TypeScript types
├── router.tsx           # Route definitions
└── main.tsx             # Entry point
```

## Architecture Patterns

### 1. Component Architecture

**Page Components**: Top-level components mapped to routes
- Own data fetching
- Manage page-level state
- Compose reusable components

**Reusable Components**: Shared UI elements
- No data fetching
- Receive data via props
- Emit events via callbacks

**Example**:
```typescript
// Page component
const RepoWorkspace = () => {
  const [files, setFiles] = useState([]);
  // ... fetch data, manage state
  return (
    <div className="workspace">
      <FileTree files={files} onFileClick={handleFileClick} />
      <FileViewer content={content} />
    </div>
  );
};

// Reusable component
const FileTree = ({ files, onFileClick }: FileTreeProps) => {
  return (
    <ul>
      {files.map(file => (
        <li onClick={() => onFileClick(file)}>{file.name}</li>
      ))}
    </ul>
  );
};
```

### 2. State Management

**URL State**: Shareable, bookmarkable state
```typescript
// Sync selections to URL
const [searchParams, setSearchParams] = useSearchParams();
// ?repo=123&branch=main&path=src/main.py
```

**React Context**: Global auth state
```typescript
// Auth context provides user, login, logout
const { user, isAuthenticated } = useAuth();
```

**Local State**: Component-specific state
```typescript
const [isEditing, setIsEditing] = useState(false);
```

### 3. API Client Pattern

Centralized API clients with type safety:

```typescript
// api/git_repositories.ts
export const getRepositories = async (projectId: string) => {
  const response = await fetch(`${API_BASE_URL}/projects/${projectId}/repositories`, {
    credentials: 'include',
  });
  return response.json();
};

// Usage in component
const repos = await getRepositories(projectId);
```

### 4. Authentication Flow

```
User clicks Login
  → Redirect to /auth/login (backend)
  → Backend redirects to Authentik OAuth
  → User authenticates with Authentik
  → Authentik redirects to /auth/callback
  → Backend creates session cookie
  → Backend redirects to frontend
  → Frontend checks /auth/me
  → User is authenticated!
```

**Auth State**:
```typescript
interface AuthState {
  user: User | null;
  isAuthenticated: boolean;
  isLoading: boolean;
}
```

### 5. Routing Structure

```typescript
// router.tsx
<Route path="/" element={<Dashboard />} />
<Route path="/projects" element={<ProjectsPage />} />
<Route path="/projects/:projectId" element={<RepoWorkspace />} />
<Route path="/projects/:projectId/repositories" element={<GitRepositories />} />
<Route path="/projects/:projectId/repositories/:repoId/history" element={<GitHistory />} />
<Route path="/terminal/:instanceId" element={<TerminalPage />} />
<Route path="/profile" element={<ProfilePage />} />
<Route path="/settings" element={<SettingsPage />} />
<Route path="/ssh-keys" element={<SSHKeysPage />} />
<Route path="/tool-types" element={<ToolTypesPage />} />
```

## Data Flow

### Repository Workspace Example

```
1. User clicks project
   → Navigate to /projects/:id
   
2. RepoWorkspace mounts
   → Fetch project repositories
   → Select first repo (or from URL)
   
3. Repo selected
   → Fetch branches
   → Fetch file tree (default branch)
   
4. User clicks file
   → Fetch file content
   → Display in viewer
   → Update URL: ?path=src/main.py
   
5. User switches branch
   → Fetch file tree for branch
   → Re-fetch current file if viewing
   → Update URL: ?branch=develop
```

## Component Communication

```
┌─────────────────────────────────────┐
│           RepoWorkspace              │
│  ┌──────────┐    ┌──────────────┐  │
│  │ FileTree │───▶│  FileViewer  │  │
│  │          │    │              │  │
│  │ onFileClick  │  content     │  │
│  │          │    │  onEdit      │  │
│  └──────────┘    └──────────────┘  │
│       ▲                              │
│       │                              │
│  ┌──────────┐                       │
│  │ Branch   │───▶ fetch tree        │
│  │ Selector │                       │
│  └──────────┘                       │
└─────────────────────────────────────┘
```

## Styling Strategy

### CSS Variables (Design Tokens)
```css
:root {
  --color-primary: #007bff;
  --color-bg: #ffffff;
  --color-text: #333333;
  --sidebar-width: 250px;
  --border-radius: 4px;
}

[data-theme="dark"] {
  --color-bg: #1a1a1a;
  --color-text: #e0e0e0;
}
```

### Component Styles
- Each page/component has scoped CSS
- Global utilities in `styles/index.css`
- No CSS-in-JS library (keep it simple)

## Testing Strategy

### Unit Tests (Vitest)
```typescript
// Component test
import { render, screen } from '@testing-library/react';
import { FileTree } from './file-tree';

test('renders file list', () => {
  const files = [{ name: 'test.py', type: 'file' }];
  render(<FileTree files={files} onFileClick={() => {}} />);
  expect(screen.getByText('test.py')).toBeInTheDocument();
});
```

### Test Coverage
- Component rendering
- User interactions
- Auth state changes
- API mocking

## Performance Considerations

1. **Code Splitting**: Vite handles automatic chunking
2. **Lazy Loading**: React.lazy() for heavy pages
3. **Debouncing**: URL updates debounced (300ms)
4. **Caching**: Browser caches API responses (ETags)
5. **Optimistic UI**: Immediate feedback before API response

## Terminal Architecture

The web terminal is the most complex component in the frontend. It bridges a browser-based terminal emulator with a server-side PTY session.

### Component Stack

```
TerminalPage (route)
└── TerminalComponent
    ├── Status bar (connection state, latency, actions)
    ├── Session-ended overlay (reconnect / go back)
    ├── Reconnect banner (spinner + countdown)
    └── xterm.js (terminal emulator)
        ├── FitAddon (auto-resize to container)
        ├── SerializeAddon (scrollback serialization)
        └── WebLinksAddon (clickable URLs)
```

### Connection Hook

`useTerminalConnection` manages the full WebSocket lifecycle:

```
CONNECTING
  → onopen → CONNECTED → heartbeat every 15s
  → onclose (unexpected) → RECONNECTING
    → backoff: 1s → 2s → 4s → 8s → 16s → 30s max
    → up to 10 attempts
    → onopen → restore scrollback → CONNECTED
  → onclose (expected) → DISCONNECTED
```

**Key behaviors:**
- **Local echo**: Printable ASCII chars appear instantly; server echo is deduplicated
- **Resize**: Debounced 200ms, throttled to 1 message per 500ms
- **Scrollback**: Serialized to `sessionStorage` on disconnect, restored on reconnect
- **Keyboard**: `Ctrl+Shift+R` triggers manual reconnect

### Data Flow

```
User types 'a'
  → xterm onData event
  → useTerminalConnection.sendInput('a')
  → local echo writes 'a' to xterm immediately
  → WebSocket sends 'a' to server
  → server PTY echoes 'a' back
  → client receives 'a' via binary frame
  → deduplicates against pending echo buffer
  → (no-op if matched, or writes remaining chars)
```

## Future Improvements

- [ ] Add React Query for server state management
- [ ] Implement virtual scrolling for large file trees
- [ ] Add service worker for offline support
- [x] Implement real-time updates (WebSocket) — Terminal done
- [ ] Add error boundary components

## Development Workflow

```bash
# Start dev server
cd apps/web && npm run dev

# Run tests
npm run test

# Type check
npm run typecheck

# Lint
npm run lint

# Build for production
npm run build
```