SuperCharged-Claude-Code-Upgrade/ENHANCED_ARCHITECTURE.md

# Claude Code IDE - Enhanced Architecture

## Integration with Dyad Patterns

### Key Adaptations from Dyad

1. **Custom XML Tag System**
   - `<claude-write>` - Write files
   - `<claude-edit>` - Edit existing files
   - `<claude-command>` - Execute terminal commands
   - `<claude-dependency>` - Add dependencies
   - `<claude-preview>` - Update preview

2. **Streaming Response Architecture**
   - Real-time Claude response streaming
   - Incremental UI updates
   - Token usage tracking
   - Interrupt handling

3. **Project Template System**
   - Pre-built project scaffolds
   - AI_RULES.md for project-specific instructions
   - Component libraries
   - One-click project generation

4. **Enhanced File Management**
   - CRUD operations on all files
   - Git integration
   - File attachments in chat
   - Drag-and-drop support

5. **Preview Panel**
   - Live preview iframe
   - Code view
   - Console output
   - Multiple preview modes

## Implementation Plan

### Phase 1: Core Enhancements (Current)
- [x] Basic session management
- [x] WebSocket communication
- [x] File browser and editor
- [ ] Custom XML tag parser
- [ ] Streaming response display
- [ ] Project templates

### Phase 2: Advanced Features
- [ ] Preview panel with iframe
- [ ] Multi-file editing
- [ ] Git integration
- [ ] Dependency management
- [ ] Project generation wizard

### Phase 3: Polish & UX
- [ ] Theme customization
- [ ] Keyboard shortcuts
- [ ] Command palette
- [ ] Collaborative features
- [ ] Mobile optimization

## Technical Specifications

### Custom XML Tag Format

```xml
<!-- Write a new file -->
<claude-write path="src/components/Header.tsx">
import React from 'react';
export default function Header() {
  return <h1>My App</h1>;
}
</claude-write>

<!-- Edit existing file -->
<claude-edit path="src/App.tsx" mode="replace">
<search>
export default function App() {
  return <div>Old Content</div>;
}
</search>
<replace>
export default function App() {
  return <div>New Content</div>;
}
</replace>
</claude-edit>

<!-- Execute command -->
<claude-command working-dir="/path/to/project">
npm run dev
</claude-command>

<!-- Add dependency -->
<claude-dependency package="react-query">
npm install @tanstack/react-query
</claude-dependency>

<!-- Update preview -->
<claude-preview url="http://localhost:3000" />
```

### Response Processor

```javascript
class ClaudeResponseProcessor {
  process(response, appPath) {
    // Extract and execute XML tags
    const writeTags = this.extractClaudeWriteTags(response);
    const editTags = this.extractClaudeEditTags(response);
    const commandTags = this.extractClaudeCommandTags(response);

    // Execute operations
    writeTags.forEach(tag => this.writeFile(tag, appPath));
    editTags.forEach(tag => this.editFile(tag, appPath));
    commandTags.forEach(tag => this.executeCommand(tag));

    return {
      filesWritten: writeTags.length,
      filesEdited: editTags.length,
      commandsExecuted: commandTags.length
    };
  }
}
```

### Streaming Architecture

```javascript
async function streamClaudeResponse(sessionId, prompt, onUpdate) {
  const response = await fetch('/claude/api/claude/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ sessionId, prompt })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let fullResponse = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value);
    fullResponse += chunk;

    // Parse and execute tags incrementally
    const partialResult = processor.processIncremental(fullResponse);
    onUpdate(partialResult);
  }

  return fullResponse;
}
```

## Project Templates

### Available Templates

```javascript
const templates = [
  {
    id: 'nextjs',
    name: 'Next.js App',
    description: 'Modern React framework with SSR',
    stack: ['Next.js 14', 'TypeScript', 'Tailwind CSS', 'shadcn/ui'],
    files: {
      'package.json': { ... },
      'next.config.js': { ... },
      'AI_RULES.md': 'Use App Router, TypeScript strict mode, shadcn/ui components...'
    }
  },
  {
    id: 'express-api',
    name: 'Express API',
    description: 'RESTful API with Express',
    stack: ['Express', 'TypeScript', 'Prisma', 'PostgreSQL'],
    files: { ... }
  },
  {
    id: 'python-fastapi',
    name: 'FastAPI Backend',
    description: 'Modern Python async API',
    stack: ['FastAPI', 'SQLAlchemy', 'Pydantic', 'PostgreSQL'],
    files: { ... }
  }
];
```

### Template Generation Process

1. User selects template
2. System generates project structure
3. Creates AI_RULES.md with project guidelines
4. Initializes git repository
5. Installs dependencies
6. Opens in IDE

## File Operations API

```javascript
// Enhanced file operations
const fileOps = {
  // Write file
  write: (path, content) => {
    fs.writeFileSync(path, content);
    gitCommit(path, `Create ${path}`);
  },

  // Edit file with search/replace
  edit: (path, search, replace) => {
    const content = fs.readFileSync(path, 'utf-8');
    const newContent = content.replace(search, replace);
    fs.writeFileSync(path, newContent);
    gitCommit(path, `Update ${path}`);
  },

  // Delete file
  delete: (path) => {
    fs.unlinkSync(path);
    gitCommit(path, `Delete ${path}`);
  },

  // Create directory
  mkdir: (path) => {
    fs.mkdirSync(path, { recursive: true });
  },

  // List directory
  ls: (path) => {
    return fs.readdirSync(path, { withFileTypes: true });
  }
};
```

## Enhanced Chat Interface

### Features
- **Rich Text Input** - Multi-line with syntax highlighting
- **File Attachments** - Drag and drop files
- **Context Picker** - Select files to include as context
- **Action Suggestions** - Quick actions (Rebuild, Restart, etc.)
- **Token Counter** - Real-time token usage display
- **Response Streaming** - Character-by-character updates

### Message Types

```javascript
const messageTypes = {
  USER: 'user',
  ASSISTANT: 'assistant',
  SYSTEM: 'system',
  FILE_WRITE: 'file_write',
  FILE_EDIT: 'file_edit',
  COMMAND: 'command',
  ERROR: 'error'
};
```

## Preview Panel

### Modes
1. **Preview** - Live rendered application
2. **Code** - Source code view with syntax highlighting
3. **Console** - Browser console output
4. **Network** - Network requests

### Implementation
```javascript
function PreviewPanel({ url, mode }) {
  return (
    <div className="preview-panel">
      <PreviewToolbar mode={mode} />
      <div className="preview-content">
        {mode === 'preview' && <iframe src={url} />}
        {mode === 'code' && <CodeView />}
        {mode === 'console' && <ConsoleView />}
      </div>
    </div>
  );
}
```

## Claude Code Integration

### System Prompt Enhancement

```javascript
const ENHANCED_SYSTEM_PROMPT = `
<role>You are an expert software developer and architect.</role>

<instructions>
1. Use <claude-write> tags to create new files
2. Use <claude-edit> tags to modify existing files
3. Use <claude-command> tags to execute terminal commands
4. Use <claude-dependency> tags to add dependencies
5. Always explain your actions before executing them
6. Follow the project's AI_RULES.md if present
7. Test your code before marking tasks complete
</instructions>

<output_format>
When writing code:
- Use TypeScript for JavaScript projects
- Follow existing code style and patterns
- Include error handling
- Add comments for complex logic

When editing files:
- Use <claude-edit> with search/replace
- Preserve existing code structure
- Don't rewrite entire files unless necessary
</output_format>
`;
```

## State Management

### Using Maps for Per-Chat State

```javascript
// Chat messages
const chatMessagesAtom = atom<Map<number, Message[]>>(new Map());

// Streaming status
const isStreamingAtom = atom<Map<number, boolean>>(new Map());

// File trees
const fileTreesAtom = atom<Map<number, FileTree>>(new Map());

// Preview URLs
const previewUrlsAtom = atom<Map<number, string>>(new Map());
```

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                        Frontend                              │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Chat      │  │   Files     │  │  Preview    │        │
│  │  Interface  │  │   Browser   │  │   Panel     │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│         │                │                │                 │
│         └────────────────┴────────────────┘                 │
│                         │                                   │
│                  ┌──────▼──────┐                             │
│                  │   State     │                             │
│                  │  Manager    │                             │
│                  └──────┬──────┘                             │
└─────────────────────────┼───────────────────────────────────┘
                          │
                    ┌─────▼─────┐
                    │ WebSocket │
                    └─────┬─────┘
                          │
┌─────────────────────────┼───────────────────────────────────┐
│                    Backend  │                               │
├─────────────────────────┼───────────────────────────────────┤
│                  ┌──────▼──────┐                             │
│                  │   Express   │                             │
│                  │   Server    │                             │
│                  └──────┬──────┘                             │
│                         │                                    │
│           ┌─────────────┼─────────────┐                     │
│           │             │             │                     │
│      ┌────▼────┐  ┌────▼────┐  ┌────▼────┐                │
│      │ Session │  │  File   │  │ Project │                │
│      │ Manager │  │ Manager │  │ Manager │                │
│      └────┬────┘  └────┬────┘  └────┬────┘                │
│           │            │            │                       │
│           └────────────┴────────────┘                       │
│                         │                                    │
│                  ┌──────▼──────┐                             │
│                  │  Claude    │                             │
│                  │   Code     │                             │
│                  │   Service  │                             │
│                  └─────────────┘                             │
└─────────────────────────────────────────────────────────────┘
                          │
                  ┌──────▼──────┐
                  │   File     │
                  │  System    │
                  └─────────────┘
```

## Next Steps

1. **Implement Custom XML Parser** - Parse and execute Claude's tags
2. **Add Streaming Support** - Real-time response display
3. **Create Template System** - Project scaffolding
4. **Build Preview Panel** - Live preview functionality
5. **Enhance File Operations** - Git integration
6. **Add Dependency Management** - Package management
7. **Implement Project Wizard** - Guided project creation

## Success Metrics

- ✅ Create new project in under 30 seconds
- ✅ Real-time response streaming < 100ms latency
- ✅ Preview updates within 2 seconds of code changes
- ✅ Support for 5+ project templates
- ✅ Manage projects with 100+ files
- ✅ Concurrent editing of 10+ files