C4 Model - Level 2: Container Diagram

Overview

The Container diagram shows the high-level technology choices and communication between major components of Sasha Studio. Each container represents a separately deployable/runnable unit.

Container Diagram

Containers

1. Single-Page Application (SPA)

Technology: React 18.2, Vite 7.0, TailwindCSS 3.4

Responsibilities:

• User interface rendering
• Client-side routing
• Form validation
• WebSocket client
• Local state management
• File upload handling

Key Components:

src/
├── components/        # UI Components
│   ├── ChatInterface  # Main chat UI
│   ├── Sidebar        # Navigation
│   ├── FileTree       # File browser
│   └── Settings       # Configuration
├── contexts/          # React Context
│   ├── AuthContext    # Authentication
│   └── ThemeContext   # Dark/Light mode
├── utils/            
│   ├── api.js         # HTTP client
│   └── websocket.js   # WS client
└── App.jsx           # Root component

Communication:

• REST API calls to backend
• WebSocket for real-time updates
• LocalStorage for message caching
• File API for uploads

2. API Server

Technology: Node.js 20, Express 4.18, WebSocket (ws)

Responsibilities:

• REST API endpoints
• WebSocket server
• Authentication & authorization
• Session management
• Claude CLI orchestration
• File processing

Key Modules:

server/
├── routes/           # API Routes
│   ├── auth.js       # Login/Register
│   ├── files.js      # File operations
│   ├── git.js        # Git integration
│   ├── mcp.js        # MCP protocol
│   ├── profile.js    # User profile
│   └── setup.js      # Initial setup
├── services/         
│   ├── document-processor.js
│   ├── content-reader.js
│   └── workspace-manager.js
├── claude-cli.js     # Claude interface
├── projects.js       # Project management
└── index.js          # Server entry

API Endpoints:

• POST /api/auth/login - User authentication
• POST /api/auth/register - User registration
• GET /api/projects - List projects
• POST /api/files/upload - Document upload
• GET /api/git/status - Git status
• WS /ws - WebSocket connection

3. Database

Technology: SQLite, better-sqlite3

Schema:

-- Core Tables
users (
    id, username, password_hash, 
    created_at, updated_at
)

company_profiles (
    id, user_id, name, description,
    search_terms, created_at
)

onboarding_documents (
    id, profile_id, filename, 
    content, metadata, uploaded_at
)

research_documents (
    id, profile_id, title,
    content, created_at
)

Characteristics:

• Single-file database
• ACID compliance
• No network overhead
• Automatic migrations
• Foreign key constraints

4. Claude CLI Process

Technology: Child process, node-pty

Responsibilities:

• Spawn Claude CLI instances
• Manage stdin/stdout/stderr
• Handle tool permissions
• Process responses
• Session management

Integration Pattern:

// Spawning Claude with options
spawnClaude(command, {
    sessionId,
    projectPath,
    cwd,
    toolsSettings,
    permissionMode,
    images
})

Features:

• PTY support for terminal emulation
• Image handling via temp files
• Resume session capability
• Tool permission management
• Streaming response parsing

5. File Manager

Technology: Node.js fs module, multer

Responsibilities:

• Workspace file operations
• Document uploads
• File conversion
• Temporary file management
• Directory watching

File Structure:

workspace/
├── uploads/
│   └── onboarding/    # User documents
├── data/              # Database files
├── config/            # Configuration
├── docs/              # Knowledge base
└── .tmp/              # Temporary files

Container Interactions

HTTP/REST Communication

WebSocket Communication

File Processing Flow

Technology Stack Details

Frontend Stack

• React 18.2: UI framework
• Vite 7.0: Build tool
• TailwindCSS 3.4: Utility CSS
• CodeMirror 6: Code editing
• XTerm.js 5.3: Terminal UI
• React Markdown: MD rendering
• Phosphor Icons: Icon library

Backend Stack

• Node.js 20: Runtime
• Express 4.18: Web framework
• ws 8.14: WebSocket server
• better-sqlite3 12.2: Database
• bcrypt 6.0: Password hashing
• jsonwebtoken 9.0: JWT auth
• multer 2.0: File uploads
• node-pty 1.1: PTY support

Development Tools

• Concurrently: Parallel processes
• Docker: Containerization
• Docker Compose: Orchestration
• ESLint: Code linting
• Prettier: Code formatting

Deployment Configurations

Local Development

Frontend: http://localhost:5173
Backend: http://localhost:3005
Database: ./data/sasha.db
Uploads: ./uploads

Docker Production

Container: sasha-studio:latest
Port: 3005
Volumes:
  - sasha-data:/app/data
  - sasha-config:/app/config
  - sasha-uploads:/app/uploads
Environment:
  - NODE_ENV=production
  - RUNNING_IN_DOCKER=true

Cloud Deployment

Platform: GCP Cloud Run / Sliplane
Image: gcr.io/project/sasha-studio
Memory: 2Gi
CPU: 2
Min Instances: 0
Max Instances: 10

Security Considerations

Authentication Flow

1. User provides credentials
2. Server validates against database
3. JWT token generated with expiry
4. Token included in requests
5. WebSocket authenticated via token

Data Protection

• Passwords hashed with bcrypt
• JWT secrets in environment
• HTTPS/WSS encryption
• Input validation
• SQL injection prevention

Container Security

• Non-root user execution
• Read-only root filesystem
• Capability dropping
• Security headers
• Rate limiting

Performance Characteristics

SPA Performance

• Code splitting: ~200KB initial
• Lazy loading: Components on demand
• Caching: LocalStorage for messages
• Debouncing: Search and updates

API Performance

• Connection pooling: Database
• Stream processing: Large files
• Message batching: WebSocket
• Process pooling: Claude CLI

Database Performance

• In-memory caching
• Prepared statements
• Index optimization
• Transaction batching

Scalability Considerations

Current Limitations

• Single-user design
• SQLite concurrency
• Local file storage
• Process-based Claude

Future Scaling

• PostgreSQL migration
• Redis sessions
• S3 file storage
• Queue-based processing
• Horizontal scaling