Last updated: Sep 1, 2025, 01:10 PM UTC

Sasha Studio - Claude Code Integration Architecture

Overview

This document defines the complete architecture for how Sasha Studio integrates with Claude Code, establishing clear separation between user projects, shared documentation, and Claude's metadata.

Core Philosophy

The Web UI is just a view of the Claude Code file system

Sasha Studio doesn't manage Claude Code - it leverages Claude Code's natural project and session management while providing a user-friendly interface and centralized documentation system.

Architecture Principles

1. Separation of Concerns

  • User Projects: Actual working directories in /home/nodejs/projects/ (e.g., company-search, legal)
  • Shared Documentation: Centralized in /home/nodejs/all-project-files/docs/
  • Claude Metadata: Automatically managed by Claude in /home/nodejs/.claude/projects/

2. Claude Code Integration

  • Claude Code works in directories we specify via cwd
  • Claude Code creates its own session metadata automatically
  • UI observes and displays what Claude has created

3. Multi-Project Architecture

Each user project has its own directory and Claude sessions. Project switching changes the current working directory for Claude Code to the specific project directory.

Directory Structure

/home/nodejs/                          # Persistent volume root
├── projects/                          # User Projects (WE manage)
│   ├── company-search/               # First project (from onboarding)
│   │   ├── docs/                     # Project-specific files
│   │   ├── CLAUDE.md                 # Project context
│   │   └── [user files]
│   └── [other-projects]/             # Additional user projects
│
├── all-project-files/                # Shared Documentation (WE manage)
│   ├── docs/                         # Central docs location
│   │   ├── guides/                   # User guides
│   │   ├── specialists/              # AI specialists/personas  
│   │   └── private/                  # System guides/specialists
│   ├── uploads/                      # User uploaded files
│   └── converted/                    # Converted documents
│
└── .claude/                          # Claude Code Metadata (CLAUDE manages)
    ├── projects/                     # Session storage
    │   ├── -home-nodejs-projects-company-search/    # Encoded project paths
    │   │   ├── session1.jsonl
    │   │   └── session2.jsonl
    │   └── -home-nodejs-projects-legal/
    └── config files...

Component Responsibilities

Projects Service (projects.js)

Purpose: Bridge between our project directories and Claude's metadata

Current Implementation :

  • Reads actual project directories from /home/nodejs/projects/
  • Maps each to Claude's encoded metadata path
  • Returns projects with both fullPath (actual) and path (encoded)

Key Functions:

  • getProjects(): Scans /home/nodejs/projects/ and matches to Claude sessions
  • encodeProjectPath(): Converts /home/nodejs/projects/foo → -home-nodejs-projects-foo

Workspace Manager (workspace-manager.js)

Purpose: Create initial project structure after onboarding

Current Status: Mostly correct

  • Creates projects in /home/nodejs/projects/
  • Generates initial CLAUDE.md with project context

Functions:

  • setupOrganizationWorkspace(): Creates company-search project directory
  • createDocumentIndex(): Manages uploaded document organization

Chat Interface (ChatInterface.jsx)

Purpose: Send messages to Claude with correct working directory

Current Implementation :

// When sending message to Claude
const options = {
  projectPath: selectedProject.path,     // Claude's encoded path
  cwd: selectedProject.fullPath,         // Actual directory path
  // ... other options
};

Key Insight: cwd parameter becomes the working directory for Claude CLI

Claude CLI Service (claude-cli.js)

Purpose: Execute Claude Code with specified working directory

Current Implementation :

let spawnOptions = {
  cwd: workingDir,        // This comes from the cwd parameter
  stdio: ['pipe', 'pipe', 'pipe'],
  env: { ...processEnv, PATH: process.env.PATH }
};

Content Reader (content-reader.js)

Purpose: Read guides and specialists for UI display

Current Status: COMPLETED

  • Reads from /home/nodejs/all-project-files/docs (correct)
  • Serves shared documentation to UI panels

Data Flow

Project Creation Flow

  1. User completes onboarding
  2. workspace-manager.js creates /home/nodejs/projects/company-search/
  3. Initial CLAUDE.md created with project context
  4. UI automatically shows new project

Message Sending Flow

  1. User types message in UI
  2. ChatInterface.jsx sends message with cwd: selectedProject.fullPath
  3. claude-cli.js spawns Claude CLI with that working directory
  4. Claude Code works in /home/nodejs/projects/company-search/
  5. Claude Code creates session metadata in .claude/projects/{encoded-path}/

Project Discovery Flow

  1. UI loads, calls /api/projects
  2. projects.js scans /home/nodejs/projects/ for directories
  3. For each directory, looks up Claude sessions using encoded path
  4. Returns combined project + session data to UI

Documentation Loading Flow

  1. UI requests guides/specialists
  2. content-reader.js reads from /home/nodejs/all-project-files/docs/
  3. Returns structured data to UI panels

Docker Integration

Volume Strategy

  • Single Volume: /home/nodejs mounted to persist all user data
  • Build-time Docs: /app/deployed-md-files/ copied during image build
  • Runtime Copy: On first startup, copy to /home/nodejs/all-project-files/

Docker Development (docker-dev.sh)

  • Named Volume: sasha-dev-home for development persistence
  • Clean Starts: Volume recreated each run for testing
  • Volume Mapping: Local development can map to different paths

Docker Entrypoint (docker-entrypoint.sh)

  • Create required directories (projects, all-project-files)
  • Copy documentation if not exists to central location
  • Set up Claude CLI symlinks for compatibility
  • Don't interfere with Claude's metadata

Implementation Changes COMPLETED

1. Legacy Workspace Code Removal

Files Updated: All workspace-related code removed

Key Changes Made:

  • Removed workspace directory creation from docker-entrypoint.sh
  • Removed workspace special cases from server/projects.js
  • Updated all file handling to use standard project extraction
  • Updated paths to use /home/nodejs/all-project-files/docs/ for shared content

2. Docker Configuration Cleanup COMPLETED

Files: claudecodeui/docker-entrypoint.sh, Dockerfile.sliplane

Changes Made:

  • Removed workspace directory and symlink creation
  • Removed redundant .claude directory copy from Dockerfile
  • Removed unused environment variables (UPLOAD_FOLDER)
  • Simplified entrypoint to basic directory setup only

3. JavaScript Code Updates COMPLETED

Files: Multiple server-side files

Changes Made:

  • Removed all workspace special case handling
  • Updated project resolution to use /home/nodejs/projects/
  • Updated shared documentation paths to /home/nodejs/all-project-files/
  • Simplified App.jsx project selection logic

4. Current Clean Architecture COMPLETED

Final Directory Structure:

/home/nodejs/
├── projects/                          # User Projects  
│   ├── company-search/               # Individual projects
│   └── legal/                        # Each with own sessions
├── all-project-files/                # Shared Documentation
│   ├── docs/                         # Centralized guides & specialists
│   │   ├── guides/
│   │   ├── specialists/
│   │   └── uploads/                  # File uploads
│   └── html-static/                  # Generated documentation
└── .claude/                          # Claude Metadata
    └── projects/                     # Session storage per project

Testing Strategy

1. Project Creation

  • Onboarding creates project in /home/nodejs/projects/company-search/
  • Project appears in UI sidebar
  • Can send messages in project context

2. Documentation Loading

  • Guides panel loads from /home/nodejs/all-project-files/docs/guides/
  • Specialists panel loads from /home/nodejs/all-project-files/docs/specialists/
  • File manager shows shared files

3. Session Management

  • Messages create Claude sessions automatically
  • Sessions appear in UI for correct project
  • Project switching changes Claude's working directory

4. Docker Testing

  • Fresh container startup works
  • Documentation copied to correct location
  • Volume persistence across restarts
  • Clean development starts

Migration Path

Phase 1: Fix Documentation Loading

  1. Update content-reader.js to read from correct location
  2. Update docker-entrypoint.sh to copy docs correctly
  3. Test guides/specialists panels

Phase 2: Clean Docker Development

  1. Update docker-dev.sh volume management
  2. Test fresh container starts
  3. Verify clean state between runs

Phase 3: Verification

  1. Full integration testing
  2. Documentation updates
  3. Team training

Success Criteria

Technical

  • All UI panels load correctly
  • Project switching works seamlessly
  • Claude Code sessions created in correct metadata locations
  • Documentation persists across container restarts
  • Development workflow is clean and reliable

User Experience

  • No visible changes to end users
  • Faster, more reliable operation
  • Clear separation between projects
  • Consistent behavior across environments

Rollback Plan

If issues arise:

  1. Revert content-reader.js changes
  2. Restore old docker-entrypoint.sh logic
  3. Use old volume mounting approach
  4. Document lessons learned

Future Considerations

Multiple Project Types

  • Support for different project templates
  • Project creation from UI
  • Import existing projects

Documentation Management

  • User-editable guides
  • Project-specific documentation
  • Documentation versioning

Advanced Claude Integration

  • Custom Claude configurations per project
  • Project-specific tools and permissions
  • Enhanced session management

Document Status: Draft
Last Updated: 2025-08-23
Next Review: After implementation