Skip to content

docs.md

Latest commit

 

History

History
765 lines (623 loc) · 18.4 KB

docs.md

File metadata and controls

765 lines (623 loc) · 18.4 KB

📚 SketchIDE Technical Documentation

Technical Documentation MVVM Architecture Flutter Framework

Technical Reference: Comprehensive documentation covering frameworks, architecture, storage systems, offline SDK integration, and implementation details for SketchIDE.

🏗️ System Architecture Overview

graph TB
    subgraph "🎨 Presentation Layer"
        UI[UI Screens & Views]
        WIDGETS[Reusable Widgets]
        PROPS[Property Panels]
    end
    
    subgraph "🧠 Business Logic Layer"
        VM[ViewModels]
        SVC[Services]
        CTRL[Controllers]
    end
    
    subgraph "📊 Data Layer"
        MODELS[Data Models]
        STORAGE[Storage Systems]
        CACHE[Cache Management]
    end
    
    subgraph "🔧 Core Systems"
        TOUCH[Touch System]
        RENDER[Rendering Engine]
        CODEGEN[Code Generation]
    end
    
    UI --> VM
    WIDGETS --> VM
    PROPS --> VM
    
    VM --> SVC
    VM --> CTRL
    
    SVC --> MODELS
    CTRL --> MODELS
    
    MODELS --> STORAGE
    MODELS --> CACHE
    
    TOUCH --> CTRL
    RENDER --> SVC
    CODEGEN --> SVC
    
    style UI fill:#e3f2fd
    style VM fill:#f3e5f5
    style SVC fill:#e8f5e8
    style MODELS fill:#fff3e0
    style STORAGE fill:#fce4ec
    style TOUCH fill:#e0f2f1
Loading

🛠️ Technology Stack

🎨 Frontend 💾 Backend 🏗️ Build System

Framework

  • Flutter (Dart) 3.19+
  • Material Design 3
  • Custom Animations

UI Components

  • Drag & Drop System
  • Touch Controllers
  • Visual Editor
  • Property Panels

Storage Compliance

  • Scoped Storage (SAF)
  • Google Play Compliant
  • Secure File Handling

Local Storage

  • JSON Files (All Data)
  • File System (Organization)
  • Archive Package (Export/Import)

Data Management

  • Project Metadata (JSON)
  • Widget Persistence (JSON)
  • Layout Storage (JSON)
  • Code Generation Cache (Files)

Performance

  • Fast File I/O
  • Lightweight JSON Parsing
  • No Database Overhead

Android

  • Gradle Build System
  • APK/AAB Generation
  • Material Components

iOS

  • Xcode Integration
  • IPA Generation
  • Cupertino Components

Flutter Pipeline

  • Dart AOT Compilation
  • Platform Binaries
  • Asset Bundling

🎯 MVVM Architecture Implementation

classDiagram
    class View {
        +build() Widget
        +handleUserInput()
        +updateUI()
    }
    
    class ViewModel {
        +widgets List~FlutterWidgetBean~
        +selectedWidget FlutterWidgetBean
        +addWidget()
        +selectWidget()
        +deleteWidget()
        +notifyListeners()
    }
    
    class Model {
        +FlutterWidgetBean
        +SketchIDEProject
        +ViewInfo
        +PropertyData
    }
    
    class Service {
        +PropertyValidationService
        +CodeGenerationService
        +StorageService
        +SelectionService
    }
    
    View --> ViewModel : observes
    ViewModel --> Model : manages
    ViewModel --> Service : uses
    Service --> Model : operates on
    
    style View fill:#e3f2fd
    style ViewModel fill:#f3e5f5
    style Model fill:#e8f5e8
    style Service fill:#fff3e0
Loading

Pattern Benefits

  • ✅ Clean Separation: UI logic separated from business logic
  • ✅ Testability: ViewModels can be unit tested independently
  • ✅ Maintainability: Changes to UI don't affect business logic
  • ✅ Scalability: Easy to add new features and screens

🎨 Visual Editor System

Core Components

mindmap
  root((Visual Editor))
    Mobile Frame
      Fixed 360x640dp Device
      Status Bar Simulation
      Toolbar Integration
      Grid Background
    Widget System
      Drag & Drop Interface
      Property Panel Integration
      Selection Feedback
      Touch Handling
    Property Editor
      Color-coded Properties
      Real-time Validation
      Auto-completion
      Visual Controls
    Code Generation
      Live Flutter Output
      Real-time Sync
      File Management
      Template System
Loading

Widget Palette System

Widget Category Components Implementation
🏗️ Layout Column, Row, Stack, Center frame_column.dart, frame_row.dart
📝 Basic Text, Button, TextField frame_text.dart, frame_button.dart
🎨 Visual Image, Icon, Container frame_icon.dart, frame_container.dart
📱 Material AppBar, Scaffold, Card Material Design widgets
🔧 Input Checkbox, Switch, Slider Interactive components

🔄 Touch & Interaction System

sequenceDiagram
    participant User
    participant TouchController
    participant SelectionService
    participant ViewModel
    participant PropertyPanel
    
    User->>TouchController: Tap Widget
    TouchController->>SelectionService: selectWidget(widget)
    SelectionService->>ViewModel: setSelectedWidget(widget)
    ViewModel->>PropertyPanel: notifyListeners()
    PropertyPanel->>User: Show Properties
    
    User->>TouchController: Long Press Widget
    TouchController->>TouchController: startDragOperation()
    TouchController->>ViewModel: onWidgetDragStart()
    
    User->>TouchController: Drag Widget
    TouchController->>ViewModel: onWidgetDragUpdate(position)
    ViewModel->>User: Visual Feedback
    
    User->>TouchController: Drop Widget
    TouchController->>ViewModel: onWidgetDragEnd(position)
    ViewModel->>PropertyPanel: Update Selection
Loading

Touch System Features

  • 🎯 Native Touch Handling: Android-like touch behavior
  • ✋ Gesture Recognition: Tap, long press, drag, multi-touch
  • 🎨 Visual Feedback: Selection highlighting and animations
  • 📱 Multi-device Support: Responsive touch areas

📊 Pure JSON Storage Architecture

Storage Philosophy: SketchIDE uses a pure JSON file-based storage system for simplicity, portability, and developer transparency. No databases are used - all data is stored in human-readable JSON files.

Why JSON-Only Storage?

  • ✅ Human Readable: Easy to debug and inspect project data
  • ✅ Version Control Friendly: Git-friendly text files
  • ✅ Cross-Platform: Works on any device without database drivers
  • ✅ Simple: No schema migrations or database overhead
  • ✅ Portable: Projects can be easily moved between devices
graph LR
    subgraph "🏠 App Sandbox"
        subgraph "📁 Projects"
            P1[Project 1]
            P2[Project 2]
            PN[Project N]
        end
        
        subgraph "⚙️ SDK"
            FLUTTER[Flutter Engine]
            DART[Dart SDK]
            GRADLE[Gradle Tools]
        end
        
        subgraph "💾 Storage"
            JSON[JSON Files]
            LAYOUTS[Layout Files]
            METADATA[Project Metadata]
        end
    end
    
    subgraph "🔄 External"
        SAF[Storage Access Framework]
        EXPORT[Export/Import (.ide)]
    end
    
    P1 --> JSON
    P2 --> LAYOUTS
    PN --> METADATA
    
    JSON --> SAF
    LAYOUTS --> EXPORT
    
    style P1 fill:#e3f2fd
    style JSON fill:#f3e5f5
    style SAF fill:#e8f5e8
Loading

Storage Strategy

Storage Type Technology Use Case Benefits
📱 Project Data JSON Files Project metadata, settings, configuration Human-readable, easy debugging, portable
🎨 Widget Storage JSON Files Layout definitions, widget hierarchies Version control friendly, simple parsing
📁 File Organization File System Project folders, assets, generated code Native OS performance, standard structure
📦 Export/Import Archive (.ide) Project backup, sharing, distribution Compressed, complete project bundles

🛠️ Offline SDK Integration

Why Offline Development?

pie title Offline Development Benefits
    "No Internet Required" : 35
    "Instant Preview" : 25
    "Local Build Speed" : 20
    "Privacy & Security" : 12
    "Reliability" : 8
Loading

SDK Components & Optimization

Component Original Size Optimized Size Optimization Strategy
Flutter Engine ~2.5 GB ~500 MB ARM64 only, stripped debug symbols
Dart SDK ~800 MB ~200 MB JIT + AOT only, minimal tools
Build Tools ~1.2 GB ~300 MB Essential Gradle components only
Package Cache ~500 MB ~50 MB Core Flutter packages only
Total ~5 GB ~1 GB 80% size reduction

SDK Storage Structure

📁 /Android/data/com.sketchide.app/files/sdk/
├── 🔧 flutter_engine/
│   ├── libflutter.so (ARM64)
│   ├── flutter_assets/
│   └── version_info.json
├── 🎯 dart_sdk/
│   ├── bin/dart
│   ├── lib/core/
│   └── version
├── 🏗️ gradle/
│   ├── wrapper/
│   ├── cache/ (minimal)
│   └── gradle.properties
├── 📦 pub_cache/
│   ├── flutter/
│   ├── material_icons/
│   └── cupertino_icons/
└── 📋 sdk_manifest.json

🏗️ Project Structure & Organization

graph TD
    subgraph "📱 SketchIDE Project"
        META[📋 meta.json]
        ICON[🎨 icon.png]
        
        subgraph "📱 Flutter Structure"
            LIB[📁 lib/]
            ASSETS[📁 assets/]
            ANDROID[📁 android/]
            IOS[📁 ios/]
            PUBSPEC[📄 pubspec.yaml]
        end
        
        subgraph "🎨 SketchIDE Data"
            UI[📁 ui/ - Layout JSON]
            LOGIC[📁 logic/ - Block Data]
            WIDGETS[📁 widgets/ - Widget Cache]
        end
        
        subgraph "🏗️ Build Output"
            APK[📱 app-release.apk]
            AAB[📦 app-release.aab]
            IPA[🍎 app-release.ipa]
        end
    end
    
    META --> LIB
    ICON --> ANDROID
    ICON --> IOS
    
    UI --> LIB
    LOGIC --> LIB
    WIDGETS --> LIB
    
    LIB --> APK
    ANDROID --> APK
    IOS --> IPA
Loading

Project Metadata Example

{
  "appName": "MySketchApp",
  "packageName": "com.example.mysketchapp",
  "version": "1.0.0",
  "description": "Created with SketchIDE",
  "framework": "flutter",
  "targetSdk": {
    "android": "34",
    "ios": "17.0"
  },
  "features": [
    "material_design",
    "cupertino_design",
    "offline_build"
  ],
  "created": "2024-01-15T10:30:00Z",
  "lastModified": "2024-01-15T15:45:00Z",
  "buildNumber": 1
}

🔄 Code Generation Pipeline

flowchart LR
    subgraph "🎨 Visual Design"
        DRAG[Drag Widget]
        PROPS[Set Properties]
        LAYOUT[Arrange Layout]
    end
    
    subgraph "🔄 Processing"
        BEAN[Widget Bean]
        VALIDATE[Validation]
        TRANSFORM[Transform]
    end
    
    subgraph "📝 Code Output"
        DART[Dart Code]
        IMPORTS[Auto Imports]
        STRUCTURE[File Structure]
    end
    
    subgraph "🏗️ Build"
        COMPILE[Flutter Build]
        APK[APK Output]
        PREVIEW[Live Preview]
    end
    
    DRAG --> BEAN
    PROPS --> VALIDATE
    LAYOUT --> TRANSFORM
    
    BEAN --> DART
    VALIDATE --> IMPORTS
    TRANSFORM --> STRUCTURE
    
    DART --> COMPILE
    IMPORTS --> APK
    STRUCTURE --> PREVIEW
    
    style DRAG fill:#e3f2fd
    style BEAN fill:#f3e5f5
    style DART fill:#e8f5e8
    style COMPILE fill:#fff3e0
Loading

Generated Code Quality

  • ✅ Clean Dart Code: Properly formatted and structured
  • ✅ Best Practices: Follows Flutter conventions
  • ✅ Performance Optimized: Efficient widget trees
  • ✅ Maintainable: Human-readable output

🔐 Security & Compliance

Google Play Compliance

graph LR
    subgraph "🔒 Scoped Storage"
        SANDBOX[App Sandbox]
        SAF[Storage Access Framework]
        PRIVACY[Privacy Controls]
    end
    
    subgraph "📱 Permissions"
        MINIMAL[Minimal Permissions]
        RUNTIME[Runtime Requests]
        TRANSPARENT[User Transparency]
    end
    
    subgraph "✅ Play Store"
        REVIEW[Automated Review]
        POLICY[Policy Compliance]
        APPROVAL[Store Approval]
    end
    
    SANDBOX --> MINIMAL
    SAF --> RUNTIME
    PRIVACY --> TRANSPARENT
    
    MINIMAL --> REVIEW
    RUNTIME --> POLICY
    TRANSPARENT --> APPROVAL
    
    style SANDBOX fill:#e8f5e8
    style MINIMAL fill:#fff3e0
    style REVIEW fill:#e3f2fd
Loading

Security Features

  • 🔒 Sandboxed Storage: All data within app boundaries
  • 🛡️ No Legacy Permissions: Uses modern Android APIs
  • 🔐 Secure Export/Import: SAF for external file operations
  • ✅ Play Store Compliant: Passes automated security scans

🚀 Performance Optimization

Rendering Performance

Optimization Implementation Benefit
Widget Caching Cached widget trees 60% faster rendering
Touch Optimization Native touch handling Smooth 60fps interaction
Code Generation Incremental updates Real-time feedback
Memory Management Efficient disposal Reduced memory usage

Build Performance

gantt
    title Build Performance Timeline
    dateFormat X
    axisFormat %s
    
    section Optimized Build
    Parse Widgets    : 0, 2
    Generate Code    : 2, 4
    Compile Dart     : 4, 8
    Package APK      : 8, 12
    
    section Standard Build
    Parse Widgets    : 0, 3
    Generate Code    : 3, 8
    Compile Dart     : 8, 18
    Package APK      : 18, 25
Loading

🔮 Roadmap & Future Enhancements

Short Term (Next 3 Months)

  • 🧩 Block-based Logic Editor: Visual programming interface
  • ☁️ Cloud Sync: Project synchronization across devices
  • 📱 Multi-screen Support: Navigation and routing
  • 🎨 Advanced Animations: Transition and motion support

Medium Term (6 Months)

  • 🤖 AI Code Assistant: Smart suggestions and optimization
  • 🔌 Plugin System: Custom widget extensions
  • 📊 Analytics Integration: App usage insights
  • 🌐 Web Preview: Browser-based app testing

Long Term (12 Months)

  • 🖥️ Desktop Support: Windows, macOS, Linux apps
  • 🤝 Team Collaboration: Real-time multi-user editing
  • 📈 Performance Profiler: Built-in optimization tools
  • 🏪 Template Marketplace: Community-driven templates

📚 API Reference & Examples

Widget Bean Structure

class FlutterWidgetBean {
  final String id;
  final String type;
  final Map<String, dynamic> properties;
  final WidgetPosition position;
  final LayoutBean layout;
  final String? parentId;
  
  // Methods
  FlutterWidgetBean copyWith({...});
  Map<String, dynamic> toJson();
  static FlutterWidgetBean fromJson(Map<String, dynamic> json);
  static String generateId(String type, List<FlutterWidgetBean> existing);
}

Property Validation Example

// Text property validation
PropertyValidationResult validateTextProperty(String value) {
  if (value.isEmpty) {
    return PropertyValidationResult.error("Text cannot be empty");
  }
  if (value.length > 100) {
    return PropertyValidationResult.warning("Text is very long");
  }
  return PropertyValidationResult.success();
}

Touch Controller Integration

class MobileFrameTouchController {
  void setCallbacks({
    required Function(FlutterWidgetBean) onWidgetSelected,
    required Function(FlutterWidgetBean, Offset) onWidgetDragStart,
    required Function(FlutterWidgetBean, Offset) onWidgetDragUpdate,
    required Function(FlutterWidgetBean, Offset) onWidgetDragEnd,
  });
}

🛠️ Development Setup & Build Instructions

Prerequisites

  • Flutter SDK 3.19.0+
  • Dart SDK 3.2.0+
  • Android Studio / VS Code
  • Git for version control

Local Development

# Clone repository
git clone https://github.com/sketchide/SketchIDE.git

# Install dependencies
cd SketchIDE
flutter pub get

# Run development build
flutter run

# Generate production build
flutter build apk --release

Testing Strategy

  • Unit Tests: ViewModel and service testing
  • Widget Tests: UI component validation
  • Integration Tests: End-to-end user workflows
  • Performance Tests: Memory and rendering benchmarks

Clean Architecture Performance Optimized Security Compliant

📖 Technical documentation for building the future of visual app development

JSON Storage Organization

📁 /.sketchide/data/mysc/
├── 📁 project_001/
│   ├── 📄 project.json          # Project metadata
│   ├── 📁 layouts/
│   │   ├── 📄 main.json         # Main layout widgets
│   │   └── 📄 activity_page.json # Additional layouts
│   ├── 📁 lib/
│   │   ├── 📄 main.dart         # Generated Flutter code
│   │   └── 📄 custom_page.dart  # Additional Dart files
│   └── 📁 assets/
│       └── 📄 images/           # Project assets

Example JSON Structures

Project Metadata (project.json):

{
  "appName": "MySketchApp",
  "packageName": "com.example.myapp",
  "version": "1.0.0",
  "widgets": ["text", "button", "container"],
  "created": "2024-01-15T10:30:00Z"
}

Widget Layout (main.json):

{
  "layoutName": "main",
  "widgets": [
    {
      "id": "text1",
      "type": "Text",
      "properties": {
        "text": "Hello World",
        "fontSize": 16.0
      },
      "position": {"x": 10, "y": 20, "width": 200, "height": 50}
    }
  ],
  "timestamp": "2024-01-15T15:45:00Z"
}