Sasha Studio (ClaudeCodeUI) Architecture Overview

Executive Summary

Sasha Studio is a sophisticated AI-powered knowledge management platform built as a web-based interface for Claude CLI. It provides a comprehensive chat interface, file management, and real-time collaboration features while maintaining a secure, single-user architecture suitable for both local and cloud deployments.

System Architecture

Sasha Studio follows a modern three-tier architecture pattern with clear separation of concerns:

Technology Stack

Frontend

• Framework: React 18.2 with React Router for SPA navigation
• Build Tool: Vite 7.0 for fast development and optimized production builds
• Styling: TailwindCSS 3.4 with custom component library
• UI Components:
  • Custom icon system using Phosphor Icons
  • CodeMirror for code editing
  • XTerm.js for terminal emulation
  • React Markdown for content rendering
• State Management: React Context API for auth and theme
• Real-time: WebSocket client for live updates

Backend

• Runtime: Node.js 20 Alpine (Docker) or native
• Framework: Express.js 4.18 for REST API
• WebSocket: ws library for real-time bidirectional communication
• Database: SQLite with better-sqlite3 for single-user persistence
• Authentication: JWT tokens with bcrypt password hashing
• Process Management: node-pty for terminal emulation, child_process for Claude CLI
• File Processing: Multer for uploads, custom document processors

Infrastructure

• Containerization: Multi-stage Docker builds with security hardening
• Deployment Platforms:
  • Local development (npm/Docker)
  • Docker Compose for production
  • Google Cloud Run
  • Sliplane PaaS
  • GitHub Container Registry
• Volumes: Persistent storage for data, config, uploads

Key Architectural Patterns

1. Session Protection System

Prevents UI disruption during active conversations by tracking session states and pausing automatic updates.

2. Real-time Communication

WebSocket-based architecture for:

• Live message streaming from Claude
• Project updates monitoring
• Session state synchronization

3. Single-User Security Model

• Initial setup flow for first user
• JWT-based authentication
• Session management with secure tokens
• No multi-tenancy complexity

4. Document Processing Pipeline

• Multi-format support (PDF, DOCX, MD, TXT)
• Automatic markdown conversion
• Organization knowledge base creation
• Structured document storage

5. Claude CLI Integration

• Child process spawning with PTY support
• Tool permission management
• Image handling through temporary files
• Resume session capability

Deployment Architecture

Local Development

Developer Machine
├── Vite Dev Server (Port 5173/5175/5176)
├── Node.js API Server (Port 3005)
├── SQLite Database (./data/sasha.db)
└── Claude CLI (native installation)

Docker Production

Docker Host
└── Docker Compose Stack
    ├── Sasha Studio Container
    │   ├── Node.js Server
    │   ├── Static Assets (Vite build)
    │   └── Claude CLI (npm global)
    └── Volumes
        ├── sasha-data (database)
        ├── sasha-config (settings)
        ├── sasha-uploads (files)
        └── claude-config (CLI config)

Cloud Deployment

Cloud Platform (GCP/Sliplane)
└── Container Instance
    ├── Environment Variables
    ├── Persistent Storage
    ├── Health Checks
    └── Auto-scaling Rules

Security Architecture

Authentication Flow

1. User registration (first-time setup only)
2. Login with username/password
3. JWT token generation
4. Token validation on API requests
5. WebSocket authentication via token

Security Measures

• Password hashing with bcrypt (12 rounds)
• JWT tokens with expiration
• CORS configuration
• Rate limiting
• Input validation
• SQL injection prevention
• XSS protection through React
• Secure WebSocket upgrade

Data Architecture

Database Schema

• users: Authentication and profile
• company_profiles: Organization settings
• onboarding_documents: Uploaded knowledge base
• research_documents: Claude-generated research

File System Structure

/app (or project root)
├── data/           # SQLite database
├── uploads/        # User uploaded files
│   └── onboarding/ # Organization documents
├── config/         # .env and settings
├── docs/           # Knowledge base
└── .tmp/           # Temporary files

Performance Considerations

Frontend Optimization

• Code splitting with React.lazy
• Memoization for expensive renders
• Virtual scrolling for large lists
• Debounced search and updates
• LocalStorage for message caching

Backend Optimization

• Connection pooling for database
• Stream processing for large files
• Efficient WebSocket message batching
• Child process management
• Memory-limited Docker containers

Monitoring & Observability

Health Checks

• /api/health endpoint
• Docker health check configuration
• Process monitoring for Claude CLI
• WebSocket connection status

Logging

• Structured JSON logging
• Log rotation in Docker
• Error tracking and reporting
• Performance metrics

Development Workflow

Local Setup

1. Install dependencies: npm install
2. Configure environment: .env file
3. Initialize database: automatic on first run
4. Start development: npm run dev

Docker Development

1. Build image: docker-compose build
2. Start services: docker-compose up
3. Access UI: http://localhost:3005

Production Build

1. Build frontend: npm run build
2. Build Docker image: Multi-stage Dockerfile
3. Deploy to platform: Platform-specific scripts

Architecture Documentation

This architecture is documented using the C4 model across multiple levels:

1. System Context - External interactions
2. Container Diagram - High-level components
3. Component Diagram - Internal structure
4. Architecture Decisions - Key design choices

Future Architecture Considerations

Scalability Path

• PostgreSQL migration for multi-user
• Redis for session management
• Kubernetes for orchestration
• CDN for static assets

Feature Extensions

• Plugin architecture for tools
• Multi-model AI support
• Collaborative editing
• Advanced analytics

Security Enhancements

• OAuth2/SAML integration
• End-to-end encryption
• Audit logging
• Compliance certifications