# Claude Code Web IDE - System Architecture

## Overview
Transform Obsidian Web Interface into a full-featured remote web IDE for Claude Code with project management, session tracking, context memory management, and real-time chat capabilities.

## System Components

### 1. Backend Services (`/services/`)

#### Claude Code Service (`claude-service.js`)
- Spawn and manage Claude Code CLI processes
- Handle stdin/stdout/stderr streams
- Session lifecycle management
- Command execution and response capture

#### Session Manager (`session-manager.js`)
- Track active sessions
- Store session history in Obsidian vault
- Session state persistence
- Multi-session support

#### Context Manager (`context-manager.js`)
- Track context memory usage
- Visualize context tokens
- Allow context pruning/editing
- Context optimization suggestions

#### Project Service (`project-service.js`)
- Create new project structures
- Trigger Claude Code planning
- Track project execution
- Project state management

### 2. API Routes (`/routes/`)

#### Session Routes
- `GET /api/claude/sessions` - List all sessions
- `POST /api/claude/sessions` - Create new session
- `GET /api/claude/sessions/:id` - Get session details
- `DELETE /api/claude/sessions/:id` - Terminate session
- `POST /api/claude/sessions/:id/command` - Send command to session
- `GET /api/claude/sessions/:id/output` - Get session output

#### Context Routes
- `GET /api/claude/context` - Get current context state
- `POST /api/claude/context/prune` - Prune context
- `GET /api/claude/context/history` - Context usage history
- `POST /api/claude/context/reset` - Reset context

#### Project Routes
- `GET /api/claude/projects` - List all projects
- `POST /api/claude/projects` - Create new project
- `GET /api/claude/projects/:id` - Get project details
- `POST /api/claude/projects/:id/plan` - Trigger planning
- `POST /api/claude/projects/:id/execute` - Trigger execution
- `GET /api/claude/projects/:id/status` - Get execution status

#### Chat Routes (WebSocket)
- `WS /api/claude/chat` - Real-time chat with Claude Code

### 3. Frontend Components (`/public/`)

#### Dashboard (`/public/dashboard.html`)
- Active sessions overview
- Context memory usage
- Recent projects
- Quick actions

#### Session Manager (`/public/sessions.html`)
- Session list (active/historical)
- Session detail view
- Real-time output stream
- Command input

#### Context Browser (`/public/context.html`)
- Context visualization
- Token usage breakdown
- Context editing interface
- Pruning controls

#### Project Manager (`/public/projects.html`)
- Project list
- Project creation wizard
- Planning trigger
- Execution monitoring

#### Chat Interface (`/public/chat.html`)
- Chat message display
- Command input
- File attachment
- Code block highlighting

#### Enhanced File Browser
- Tree view with filters
- File preview
- Inline editing
- Syntax highlighting

### 4. Data Storage (Obsidian Vault)

```
obsidian-vault/
├── .claude-ide/                    # IDE configuration
│   ├── config.json
│   └── settings.json
├── Claude Sessions/                # Session storage
│   ├── 2026-01-19-session-001.md
│   ├── 2026-01-19-session-002.md
│   └── session-index.md
├── Claude Context/                 # Context tracking
│   ├── context-history.md
│   └── context-analytics.md
└── Claude Projects/                # Project management
    ├── active-projects.md
    ├── project-templates.md
    └── [project-folders]/
```

## Technical Implementation Details

### Claude Code Process Management
```javascript
// Spawn claude process
const { spawn } = require('child_process');

const claudeSession = spawn('claude', [], {
  cwd: workingDir,
  env: { ...process.env, CLAUDE_SESSION_ID: sessionId }
});

// Handle streams
claudeSession.stdout.on('data', (data) => {
  // Parse and emit events
});

claudeSession.stderr.on('data', (data) => {
  // Handle errors
});

claudeSession.stdin.write(command + '\n');
```

### WebSocket Chat Server
```javascript
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 3011 });

wss.on('connection', (ws) => {
  ws.on('message', async (message) => {
    // Send to Claude Code
    const response = await executeClaudeCommand(message);
    ws.send(JSON.stringify(response));
  });
});
```

### Context Token Tracking
- Parse Claude Code responses for token usage
- Track cumulative token usage
- Visualize context breakdown
- Suggest context optimizations

## Security Considerations

1. **Authentication Required**
   - All API endpoints protected
   - Session tokens for WebSocket
   - API key for Claude Code

2. **Input Validation**
   - Sanitize all commands
   - Validate file paths
   - Prevent command injection

3. **Rate Limiting**
   - Limit command frequency
   - Prevent resource exhaustion
   - Session timeout

4. **Audit Logging**
   - Log all commands
   - Track session activity
   - Store in Obsidian vault

## Integration Points

### With Existing Obsidian Web Interface
- Extend current authentication
- Share file management APIs
- Use existing Obsidian vault storage
- Integrate with daily notes

### With Claude Code CLI
- Use standard CLI interface
- Capture all output formats
- Handle tool use events
- Track task completion

## Implementation Phases

### Phase 1: Core Backend (Current)
- Claude Code service
- Session manager
- Basic API routes

### Phase 2: Frontend UI
- Dashboard
- Session manager
- Context browser

### Phase 3: Project Management
- Project service
- Planning integration
- Execution monitoring

### Phase 4: Chat Interface
- WebSocket server
- Real-time chat UI
- File attachment

### Phase 5: Advanced Features
- Context optimization
- Multi-project management
- Analytics and reporting

## Success Metrics

- ✓ Create and manage Claude Code sessions
- ✓ View and control context memory
- ✓ Create projects and trigger planning
- ✓ Real-time chat with Claude Code
- ✓ Edit files in web interface
- ✓ Track session history and analytics