Sasha Studio Implementation Guide

Generated: 2025-01-03 UTC
Updated: 2025-01-03 UTC
Purpose: Complete implementation blueprint for Sasha Studio AI Knowledge Management Platform
Target Users: Development team, project stakeholders, technical architects
Status: Implementation Ready - v2.0 with LLxprt Integration

Executive Summary

Transform organizational knowledge into intelligent, actionable insights through a web-based AI platform that leverages LLxprt Code CLI for unified multi-model support, enterprise security, intelligent guide management, automated publishing, and complete operational visibility. Sasha Studio provides a business-friendly interface for AI-powered research, analysis, and knowledge sharing with comprehensive monitoring and compliance capabilities.

Key Value Propositions

Success Metrics

• Time to First Value: < 5 minutes
• Task Success Rate: > 90%
• Output Quality Consistency: > 95%
• Cost Reduction: 60-80% vs traditional methods
• User Satisfaction: > 4.5/5 stars
• System Uptime: > 99.9%
• Audit Compliance: 100%

System Architecture

Single Container Architecture with LLxprt Integration

LLxprt Code CLI Integration Flow

Technology Stack

Core Features Implementation

Web-Based Claude Interface

Chat Interface Architecture

Key Features

1. Real-Time Streaming

// WebSocket streaming implementation
class ChatStreamHandler {
  async streamResponse(
    message: string,
    context: ChatContext
  ): AsyncGenerator<ChatToken> {
    const model = await this.selectModel(context);
    const stream = await model.generate({
      messages: context.history.concat({ role: 'user', content: message }),
      stream: true,
      temperature: 0.7,
      max_tokens: 4000
    });
    
    for await (const chunk of stream) {
      yield {
        token: chunk.text,
        metadata: {
          model: model.id,
          timestamp: Date.now()
        }
      };
    }
  }
}

2. Business Safety Rails

• Command whitelisting
• File operation restrictions
• Automatic backups before modifications
• Rate limiting per user/role
• Content filtering for PII/secrets

3. File Context Management

• Drag & drop file upload
• Automatic file type detection
• Context window optimization
• Cross-file relationship mapping

LLM Routing & OpenRouter Integration

Dynamic Model Selection

interface ModelRoutingConfig {
  providers: {
    anthropic: {
      models: ['claude-3-opus', 'claude-3-sonnet'];
      apiKey: string;
    };
    openrouter: {
      endpoint: 'https://openrouter.ai/api/v1';
      apiKey: string;
      availableModels: ModelInfo[];
    };
    local: {
      ollama: {
        endpoint: 'http://localhost:11434';
        models: ['llama3:70b', 'mixtral:8x7b'];
      };
    };
  };
  
  routingRules: RoutingRule[];
  fallbackChain: string[];
}

Model Selection UI Component

// Model selector component with improved spacing
export function ModelSelector({ currentModel, onSelect }) {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="outline" className="min-w-[200px]">
          <Bot className="h-4 w-4 mr-2" />
          <span className="flex-1 text-left">{currentModel.name}</span>
          <ChevronDown className="h-4 w-4 ml-2" />
        </Button>
      </PopoverTrigger>
      <PopoverContent className="w-[420px] p-3">
        <div className="space-y-2">
          <div className="text-sm font-medium text-muted-foreground px-2 py-1">
            Select AI Model
          </div>
          
          {/* Cloud Models Section */}
          <div className="space-y-1">
            <div className="text-xs font-medium text-muted-foreground px-2 py-1">
              Cloud Models
            </div>
            
            <ModelOption
              model={{
                id: 'claude-3-opus',
                name: 'Claude 3 Opus',
                provider: 'Anthropic',
                description: 'Best for complex analysis and reasoning',
                badge: 'Cloud',
                pricing: '$15/1M tokens',
                icon: '🟣'
              }}
              onSelect={onSelect}
            />
            
            <ModelOption
              model={{
                id: 'gpt-4-turbo',
                name: 'GPT-4 Turbo',
                provider: 'OpenAI',
                description: 'Versatile and fast responses',
                badge: 'Cloud',
                pricing: '$10/1M tokens',
                icon: '🟢'
              }}
              onSelect={onSelect}
            />
          </div>
          
          {/* Local Models Section */}
          <div className="space-y-1 pt-2 border-t">
            <div className="text-xs font-medium text-muted-foreground px-2 py-1">
              Local Models
            </div>
            
            <ModelOption
              model={{
                id: 'llama-3-70b',
                name: 'Llama 3 70B',
                provider: 'Meta',
                description: 'Secure on-premise processing',
                badge: 'Local',
                pricing: 'Free',
                icon: '🟠',
                requiresGPU: true
              }}
              onSelect={onSelect}
            />
            
            <ModelOption
              model={{
                id: 'mistral-7b',
                name: 'Mistral 7B',
                provider: 'Mistral AI',
                description: 'Fast and efficient',
                badge: 'Local',
                pricing: 'Free',
                icon: '🔵'
              }}
              onSelect={onSelect}
            />
          </div>
        </div>
      </PopoverContent>
    </Popover>
  );
}

// Individual model option component
function ModelOption({ model, onSelect }) {
  return (
    <button
      className="w-full flex items-start gap-3 p-3 rounded-lg hover:bg-muted/50 transition-colors text-left"
      onClick={() => onSelect(model)}
    >
      {/* Model Icon */}
      <div className="text-2xl">{model.icon}</div>
      
      {/* Model Info */}
      <div className="flex-1 min-w-0">
        <div className="flex items-center gap-2 mb-1">
          <span className="font-medium">{model.name}</span>
          <Badge variant={model.badge === 'Local' ? 'secondary' : 'default'} className="text-xs">
            {model.badge}
          </Badge>
          {model.requiresGPU && (
            <Badge variant="outline" className="text-xs">
              GPU
            </Badge>
          )}
        </div>
        <p className="text-sm text-muted-foreground line-clamp-2">
          {model.description}
        </p>
        <div className="flex items-center gap-3 mt-1 text-xs text-muted-foreground">
          <span>{model.provider}</span>
          <span>•</span>
          <span className="font-medium">{model.pricing}</span>
        </div>
      </div>
    </button>
  );
}

Guide Intelligence System

Knowledge Library Architecture

Guide Management Structure

/guides/
├── knowledge-management/
│   ├── _meta.yaml                          # Category metadata
│   ├── beautiful-documentation-design.md    # Visual design standards
│   ├── excel-to-markdown-conversion.md     # Data transformation
│   └── web-publishing-guide.md             # Publishing workflow
├── research/
│   ├── competitor-analysis-framework.md     # Market research
│   ├── digital-investigation-guide.md       # Online research
│   └── problem-validation-guide.md          # Problem discovery
├── development/
│   ├── ai-standards.md                      # AI implementation
│   ├── coding-standards.md                  # Code quality
│   └── docker-setup-guide.md               # Infrastructure
└── _index/
    ├── guide-index.json                     # Searchable index
    └── usage-analytics.json                 # Performance metrics

Publishing Pipeline

Doc-Builder Integration Flow

Publishing Configuration

interface PublishingConfig {
  workspace: {
    structure: {
      'docs/': 'Markdown content',
      'doc-builder.config.js': 'Site configuration',
      '_images/': 'Assets and media'
    }
  };
  
  docBuilder: {
    siteName: string;
    features: {
      authentication: boolean;
      darkMode: boolean;
      mermaid: boolean;
      search: boolean;
    };
    deployment: {
      platform: 'vercel' | 'netlify' | 'custom';
      customDomain?: string;
    };
  };
  
  accessControl: {
    visibility: 'public' | 'private' | 'password';
    allowedEmails?: string[];
    expirationDate?: Date;
  };
}

UI/UX Implementation

Design System Architecture

Component Hierarchy

Design Tokens

:root {
  /* Colors */
  --primary: #2563eb;
  --primary-foreground: #ffffff;
  --secondary: #7c3aed;
  --secondary-foreground: #ffffff;
  --success: #10b981;
  --warning: #f59e0b;
  --error: #ef4444;
  
  /* Typography */
  --font-sans: 'Inter', -apple-system, system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;
  
  /* Spacing */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
  
  /* Radii */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
  --radius-full: 9999px;
}

Onboarding Experience

Interactive Tour Flow

Onboarding Components

interface OnboardingStep {
  id: string;
  title: string;
  description: string;
  target: string; // CSS selector
  action?: {
    type: 'next' | 'highlight' | 'interact';
    delay?: number;
  };
}

const onboardingSteps: OnboardingStep[] = [
  {
    id: 'welcome',
    title: 'Welcome to Sasha Studio! 👋',
    description: 'Your AI-powered knowledge assistant',
    target: 'body',
    action: { type: 'next', delay: 3000 }
  },
  {
    id: 'chat',
    title: 'Chat with Sasha',
    description: 'Type questions or upload files to analyze',
    target: '.chat-input',
    action: { type: 'highlight' }
  }
  // ... more steps
];

Operational Visibility & Monitoring

Note: For V1 deployment, we use a simplified monitoring dashboard instead of the full Prometheus/Grafana stack. See the Local LLM Integration Guide for the lightweight monitoring implementation.

Real-Time Dashboard Architecture

Key Monitoring Features

1. Executive Dashboard

• Active sessions in real-time
• Task completion metrics
• System health indicators
• Resource utilization graphs
• Cost tracking by model usage

2. Operational Metrics

interface OperationalMetrics {
  sessions: {
    active: number;
    total24h: number;
    avgDuration: number;
    byUser: Map<string, SessionMetrics>;
  };
  
  tasks: {
    inProgress: TaskProgress[];
    completed24h: number;
    successRate: number;
    avgResponseTime: number;
  };
  
  mounts: {
    health: MountHealth[];
    syncStatus: SyncOperation[];
    lastSync: Map<string, Date>;
  };
  
  models: {
    usage: Map<string, ModelUsage>;
    costs: Map<string, number>;
    performance: Map<string, PerformanceMetrics>;
  };
}

3. Mount Health Monitoring

• Real-time connection status
• Sync operation progress
• File change detection
• Error tracking and alerts
• Bandwidth utilization

4. Audit & Compliance

• Comprehensive action logging
• User attribution for all operations
• Data access tracking
• Export capabilities for SIEM
• Automated compliance reports

SIEM Integration

siem_integration:
  supported_platforms:
    - splunk:
        protocol: HEC
        format: JSON
        endpoint: ${SPLUNK_HEC_URL}
    - elastic:
        protocol: Beats
        format: ECS
        endpoint: ${ELASTIC_URL}
    - syslog:
        protocol: RFC5424
        format: CEF
        endpoint: ${SYSLOG_SERVER}
  
  event_types:
    - authentication
    - data_access
    - model_usage
    - configuration_change
    - security_alert

Grafana Dashboard Configuration

dashboards:
  - name: "Sasha Studio Overview"
    refresh: "5s"
    panels:
      - title: "Active Sessions"
        type: stat
        query: "sasha_active_sessions_total"
        
      - title: "Task Success Rate"
        type: gauge
        query: "rate(sasha_task_success[5m])"
        
      - title: "Model Usage Distribution"
        type: piechart
        query: "sum by (model) (sasha_model_requests_total)"
        
      - title: "Response Time Trends"
        type: graph
        query: "histogram_quantile(0.95, sasha_response_duration)"
        
      - title: "Mount Health Status"
        type: table
        query: "sasha_mount_health_status"

Security Architecture

Important: See the V1 Security Essentials Guide for comprehensive security hardening procedures including container security, secrets management, and monitoring.

Authentication & Authorization

Complete Implementation Guide: See JWT Authentication Flow Guide for comprehensive implementation details including Supabase Auth integration and licensing model.

Supabase Auth Integration with Licensing Model

Sasha Studio uses Supabase Auth as the primary authentication service with integrated subscription licensing for feature access control.

Subscription Tiers & Feature Matrix

RBAC Matrix

Data Protection

Encryption Strategy

interface SecurityConfig {
  encryption: {
    atRest: {
      algorithm: 'AES-256-GCM';
      keyRotation: '90 days';
    };
    inTransit: {
      protocol: 'TLS 1.3';
      cipherSuites: string[];
    };
  };
  
  piiHandling: {
    detection: boolean;
    masking: boolean;
    retention: '365 days';
  };
  
  auditLogging: {
    events: ['auth', 'data_access', 'admin_actions'];
    retention: '2 years';
    storage: 'immutable';
  };
}

Deployment Architecture

Single Container Deployment

Simplified Architecture

Single Container Dockerfile

FROM ubuntu:22.04

# Install all required services
RUN apt-get update && apt-get install -y \
    nodejs npm \
    postgresql-14 \
    redis-server \
    nginx \
    supervisor \
    prometheus \
    grafana \
    curl git \
    && rm -rf /var/lib/apt/lists/*

# Install LLxprt CLI
COPY --from=llxprt-builder /build/llxprt /usr/local/bin/

# Copy application code
COPY frontend/dist /app/frontend
COPY backend /app/backend
COPY doc-builder /app/doc-builder
COPY guides /app/guides

# Copy configuration files
COPY docker/nginx.conf /etc/nginx/nginx.conf
COPY docker/supervisord.conf /etc/supervisor/conf.d/
COPY docker/prometheus.yml /etc/prometheus/
COPY docker/init.sh /init.sh

# Create directories
RUN mkdir -p /data /config /models /logs

# Expose only main port
EXPOSE 80

# Health check
HEALTHCHECK --interval=30s --timeout=10s \
    CMD curl -f http://localhost/health || exit 1

# Start all services
CMD ["/init.sh"]

Docker Compose (Single Container)

version: '3.8'

services:
  sasha:
    build: .
    image: sasha/studio:latest
    container_name: sasha-studio
    ports:
      - "80:80"        # Main web interface
      - "3001:3001"    # Grafana dashboards (optional)
    volumes:
      - sasha-data:/data
      - sasha-config:/config
      - sasha-models:/models
      - sasha-logs:/logs
      - ./guides:/app/guides  # Mount local guides
    environment:
      # LLM Configuration
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ENABLE_LOCAL_MODELS=true
      
      # Admin Configuration
      - ADMIN_EMAIL=admin@example.com
      - INITIAL_PASSWORD=changeme
      
      # Monitoring Configuration
      - ENABLE_MONITORING=true
      - SIEM_ENDPOINT=${SIEM_ENDPOINT}
      
    restart: unless-stopped
    
volumes:
  sasha-data:
  sasha-config:
  sasha-models:
  sasha-logs:

GCP Production Architecture

Cloud Infrastructure

Deployment Configuration

# cloudbuild.yaml
steps:
  # Build and test
  - name: 'node:20'
    entrypoint: 'npm'
    args: ['ci']
    
  - name: 'node:20'
    entrypoint: 'npm'
    args: ['test']
  
  # Build Docker images
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'gcr.io/$PROJECT_ID/sasha-api', './backend']
    
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'gcr.io/$PROJECT_ID/sasha-web', './frontend']
  
  # Push to Container Registry
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'gcr.io/$PROJECT_ID/sasha-api']
    
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'gcr.io/$PROJECT_ID/sasha-web']
  
  # Deploy to Cloud Run
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk'
    entrypoint: 'gcloud'
    args:
      - 'run'
      - 'deploy'
      - 'sasha-api'
      - '--image=gcr.io/$PROJECT_ID/sasha-api'
      - '--region=us-central1'
      - '--platform=managed'
      - '--memory=4Gi'
      - '--cpu=4'
      - '--min-instances=2'
      - '--max-instances=100'

Implementation Roadmap

Phase 0: Documentation & Planning

Duration: 1 week
Status: Complete

• Requirements analysis
• Architecture design
• Technology selection
• Resource planning
• Documentation creation

Phase 1: Core Infrastructure

Duration: 2 weeks
Sprint 1: Foundation Setup

• Docker environment setup
• Database schema design
• API framework initialization
• Authentication system

Sprint 2: Core Services

• WebSocket server
• File management service
• Basic LLM integration
• Redis caching

Phase 2: Feature Development

Duration: 3 weeks
Sprint 3: Chat Interface

• React UI setup
• Chat component development
• File upload system
• Streaming implementation

Sprint 4: Intelligence Layer

• Guide library setup
• Context analyzer
• LLM router
• OpenRouter integration

Sprint 5: Publishing & Admin

• Doc-builder integration
• Publishing pipeline
• Admin dashboard
• User management

Phase 3: Integration & Testing

Duration: 2 weeks
Sprint 6: Integration

• End-to-end testing
• Performance optimization
• Security audit
• Load testing

Sprint 7: Polish

• UI/UX refinements
• Onboarding flow
• Documentation updates
• Bug fixes

Phase 4: Deployment

Duration: 1 week
Sprint 8: Production Launch

• GCP project setup
• CI/CD pipeline
• Production deployment
• Monitoring setup
• Launch preparation

Technical Specifications

API Endpoints

Core Chat API

File Management API

Publishing API

Database Schema

Environment Configuration

# .env.example
# Application
NODE_ENV=development
PORT=8000
APP_URL=http://localhost:3000

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/sasha
REDIS_URL=redis://localhost:6379

# Supabase Configuration
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Authentication & JWT
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=15m
REFRESH_TOKEN_EXPIRES_IN=7d

# Licensing & Subscriptions
STRIPE_SECRET_KEY=sk_test_your-stripe-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret
ENABLE_USAGE_TRACKING=true

# AI/LLM
ANTHROPIC_API_KEY=your-claude-key
OPENROUTER_API_KEY=your-openrouter-key
OLLAMA_HOST=http://localhost:11434

# Storage
STORAGE_TYPE=local # or gcs
GCS_BUCKET=sasha-storage
GOOGLE_APPLICATION_CREDENTIALS=./service-account.json

# Publishing
DOC_BUILDER_URL=http://localhost:8080
VERCEL_TOKEN=your-vercel-token

# Security
ENCRYPTION_KEY=your-encryption-key
RATE_LIMIT_WINDOW=15m
RATE_LIMIT_MAX=100

V1 Security Essentials

Critical Security Measures for Production

For V1 deployment, implement these essential security measures without adding complexity:

Quick Security Checklist

• Container Security: Run as non-root user, remove unnecessary tools
• Secrets Management: Use file-based secrets, not environment variables
• Network Security: HTTPS only with security headers
• Application Security: Rate limiting, input sanitization, session security
• Data Protection: Automated backups, PII scanning, audit logging
• Monitoring: Health checks, security event logging, disk space alerts

Essential Configuration Changes

# Generate secrets
./scripts/generate-secrets.sh

# Set up automated backups (add to crontab)
0 2 * * * /app/scripts/backup.sh

# Create security audit log
mkdir -p /logs && touch /logs/security.log

Security-Enhanced Start Script

#!/bin/bash
# /init.sh - Secure initialization

# Check for required secrets
for secret in jwt_secret session_secret encryption_key database_url; do
  if [ ! -f "/run/secrets/$secret" ]; then
    echo "ERROR: Missing required secret: $secret"
    exit 1
  fi
done

# Initialize with security checks
echo "🔒 Starting Sasha Studio with security hardening..."

# Start services with proper permissions
exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf

Full Guide: See the comprehensive V1 Security Essentials Guide for detailed implementation instructions.

Getting Started

Prerequisites Checklist

• Docker Desktop installed (v24.0+)
• Node.js installed (v20+)
• Git configured
• VS Code with recommended extensions
• GCP Account (for production)
• API Keys:
  • Anthropic (Claude)
  • OpenRouter (optional)
  • Google Cloud credentials

Quick Start Commands

# 1. Clone the repository
git clone https://github.com/your-org/sasha-studio.git
cd sasha-studio

# 2. Copy environment template
cp .env.example .env
# Edit .env with your configuration

# 3. Install dependencies
npm install

# 4. Start Docker services
docker-compose up -d

# 5. Run database migrations
npm run db:migrate

# 6. Seed initial data
npm run db:seed

# 7. Start development servers
npm run dev

# 8. Open in browser
# Frontend: http://localhost:3000
# API: http://localhost:8000
# Doc-Builder: http://localhost:8080

Verification Steps

1. Test Chat Interface

   • Open http://localhost:3000
   • Send a test message
   • Verify streaming response

2. Test File Upload

   • Drag a document to chat
   • Verify file processing
   • Check context integration

3. Test Publishing

   • Create a simple analysis
   • Click publish button
   • Verify preview generation

Appendices

A. Glossary

B. Reference Architecture

• Claude API Documentation
• OpenRouter API
• shadcn/ui Components
• GCP Cloud Run

Security References

• V1 Security Essentials Guide
• Local LLM Integration Guide
• PII Scanning and Removal Guide
• OWASP Security Guidelines
• Docker Security Best Practices

C. Troubleshooting Guide

Common Issues

Docker containers won't start

# Check logs
docker-compose logs -f

# Reset volumes
docker-compose down -v
docker-compose up -d

Database connection errors

# Verify PostgreSQL is running
docker ps | grep postgres

# Test connection
psql -h localhost -U postgres -d sasha

LLM routing failures

• Verify API keys in .env
• Check rate limits
• Ensure models are available
• Review fallback configuration

Success Criteria

Performance Benchmarks

• Response Time: < 100ms first token
• Streaming Rate: > 50 tokens/second
• File Processing: < 5s for 10MB files
• Publishing Time: < 30s for standard site

Quality Metrics

• Guide Compliance: > 95%
• Output Accuracy: > 90%
• User Satisfaction: > 4.5/5
• System Uptime: > 99.9%

Business Impact

• Time Savings: 60-80% vs manual
• Cost Reduction: 70% vs consultants
• Knowledge Capture: 100% retention
• Team Productivity: 3x improvement

This implementation guide serves as the single source of truth for building Sasha Studio. For questions or clarifications, consult the project team or refer to the detailed guides in the appendices.