🏗️ Tablio Architecture

Overview

Tablio is a Chrome extension built with vanilla JavaScript following Chrome Extension Manifest V3 architecture. The extension uses a service worker for background operations and provides both popup and options page interfaces.

Core Components

🔧 Service Worker (`background.js`)

Purpose: Handles workspace operations, storage management, and Chrome API interactions
Key Functions:
- saveWorkspace() - Captures current tabs and windows
- restoreWorkspace() - Opens saved tabs and groups
- cleanDuplicateWorkspaces() - Removes duplicate entries
- Tab group management and persistence
Storage: Uses chrome.storage.sync for cross-device synchronization
Error Handling: Comprehensive try-catch blocks with user notifications

🎨 Popup Interface (`popup.js` + `popup.html`)

Purpose: Primary user interface for quick workspace actions
Features:
- Collapsible workspace sections
- Context menus for workspace actions
- Recent workspaces with preview cards
- Theme switching (light/dark/auto)
- Quick actions (close all, remove duplicates)
Security: XSS-protected DOM manipulation using createElement and textContent

⚙️ Options Page (`options.js` + `options.html`)

Purpose: Advanced workspace management and settings
Features:
- Workspace editing with tab management
- Analytics dashboard with usage statistics
- Auto-clean settings configuration
- Import/export functionality
- Chrome-like tab grouping with visual color picker

🛡️ Custom Modal System (`modal.js` + `prompt.js`)

Purpose: Secure replacement for browser alerts/confirms
Security: XSS-safe DOM construction without innerHTML
Features: Custom styling, keyboard navigation, CSP compliance

Data Flow

User Action → Popup/Options → Background Service Worker → Chrome APIs → Storage
     ↓              ↓                    ↓                    ↓          ↓
UI Update ← DOM Update ← Message Response ← API Response ← Data Sync

Storage Schema

{
  workspaces: {
    "workspace-id": {
      name: "string",
      tabs: [{ url: "string", title: "string", groupId: number }],
      groups: [{ id: number, title: "string", color: "string" }],
      createdAt: timestamp,
      lastUsed: timestamp
    }
  },
  settings: {
    autoClean: boolean,
    theme: "light|dark|auto",
    autoSaveInterval: number
  },
  analytics: {
    workspacesCreated: number,
    workspacesRestored: number,
    lastUsed: timestamp
  }
}

Security Architecture

XSS Prevention

No use of innerHTML or eval()
All DOM manipulation uses createElement and textContent
CSP headers prevent inline scripts

Content Security Policy

{
  "content_security_policy": {
    "extension_pages": "script-src 'self'; object-src 'self'"
  }
}

Input Sanitization

All user inputs validated and sanitized
URL validation for tab restoration
Character limits enforced (workspace names: 20 chars, tab titles: 50 chars)

Performance Optimizations

Storage Efficiency

Aggressive limits: 3 workspaces max, 5 tabs each
Automatic cleanup of old/duplicate workspaces
Compressed data structures

UI Responsiveness

Debounced search and filter operations
Lazy loading of workspace previews
CSS animations with transform for GPU acceleration

Memory Management

Event listeners properly removed on cleanup
Chrome API calls wrapped in error handling
Background script optimized for minimal resource usage

Extension Permissions

{
  "permissions": [
    "tabs",           // Read/modify browser tabs
    "storage",        // Sync data across devices
    "windows",        // Manage browser windows
    "scripting",      // Execute scripts in tabs
    "activeTab",      // Access current active tab
    "tabGroups",      // Manage Chrome tab groups
    "notifications"   // Show system notifications
  ]
}

File Structure & Responsibilities

/tablio/
├── manifest.json          # Extension configuration & permissions
├── background.js          # Service worker - core business logic
├── popup.html/js          # Main UI - workspace switching
├── options.html/js        # Settings - advanced management
├── modal.js               # Secure modal system
├── prompt.js              # Secure prompt dialogs
├── css/style.css          # Comprehensive styling
└── icons/                 # Extension assets

API Integration

Chrome Extension APIs Used

chrome.tabs - Tab management and querying
chrome.windows - Window operations
chrome.storage.sync - Cross-device data synchronization
chrome.tabGroups - Tab grouping functionality
chrome.notifications - User notifications
chrome.scripting - Content script injection

Message Passing

// Popup → Background
chrome.runtime.sendMessage({
  action: 'saveWorkspace',
  data: { name: 'Work Session' }
});

// Background → Popup
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // Handle workspace operations
});

Error Handling Strategy

Background Service Worker

Try-catch blocks around all Chrome API calls
Graceful degradation for missing permissions
User notifications for critical errors

UI Components

Input validation with user feedback
Loading states for async operations
Fallback UI for failed operations

Storage Operations

Quota limit handling
Data corruption recovery
Sync conflict resolution

Testing Strategy

Manual Testing

Cross-browser compatibility (Chrome focus)
Permission scenarios
Storage quota limits
Network connectivity issues

Security Testing

XSS attack vectors
CSP compliance
Input sanitization
Permission escalation

Deployment Architecture

Development

Local unpacked extension loading
Developer mode testing
Hot reload for rapid iteration

Production

Chrome Web Store distribution
Automatic updates via Chrome
Analytics and crash reporting

Future Architecture Considerations

Scalability

Firefox WebExtension compatibility
Cloud backup API integration
Multi-browser sync protocols

Performance

IndexedDB for larger datasets
Web Workers for heavy computations
Service Worker caching strategies

Security

Enhanced CSP policies
Permission minimization
Encrypted storage options

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History