Widgets

Widgets are modular tools that extend the functionality of your Flowstate canvas. They’re like apps you can install, configure, and use directly within your workspace.

What Are Widgets?

A widget is a self-contained piece of functionality that adds capabilities to Flowstate. Widgets can:

• Display information (dashboards, charts, feeds)
• Provide tools (calculators, timers, note-taking)
• Integrate with external services (GitHub, Slack, analytics)
• Automate workflows (notifications, data sync, reporting)

Widgets appear as tiles on your canvas. Click a widget tile to open the full interactive view in an expanded modal.

Widget Architecture

Tile View vs. Expanded View

Widgets have two distinct modes:

Tile View (Read-Only Preview)

The tile on your canvas shows a compact preview:

• Widget name and icon
• Key metrics or status
• Visual summary of widget state
• Quick access to expand

Important: The tile view is read-only. You can see information, but you can’t interact with controls or modify data.

Expanded View (Full Interaction)

Click the tile to open the widget in a modal. The expanded view provides:

• Full interactive interface
• All widget features and controls
• Settings and configuration
• Data entry and manipulation

All interaction happens in the expanded view. This keeps the canvas clean while providing full functionality when you need it.

Widget Settings

Each widget has configurable settings:

• Display options: How the widget appears
• Data sources: What information the widget uses
• Behavior: How the widget responds to events
• Permissions: What the widget can access

Settings are accessed from the expanded view and persist across sessions.

Installing Widgets

Widget Store

Widgets are installed from the Widget Store, which appears as a special tile on your canvas:

1. Open the Widget Store tile
2. Browse available widgets
3. Read widget descriptions and reviews
4. Click “Install” on the widget you want
5. Configure initial settings
6. The widget appears on your canvas

Widget Discovery

The Widget Store helps you find widgets:

• Categories: Browse by type (productivity, communication, analytics, etc.)
• Search: Find widgets by name or functionality
• Featured: Curated selections of popular or new widgets
• Recommendations: Suggestions based on your usage

Widget Information

Before installing, review:

• Description: What the widget does
• Trust level: Security and verification status (see below)
• Hosting mode: Where the widget runs (see below)
• Permissions: What the widget can access
• Reviews: Feedback from other users
• Developer: Who created the widget

This information helps you make informed decisions about what to install.

Widget Trust Levels

Flowstate uses a five-level trust system to help you understand widget security:

Level 1: Unverified

• No verification or review
• Use at your own risk
• May request broad permissions
• Not recommended for sensitive data

Level 2: Community Reviewed

• Reviewed by community members
• Basic security checks passed
• Permissions are reasonable
• Safe for general use

Level 3: Flowstate Verified

• Reviewed by Flowstate team
• Code audited for security
• Follows best practices
• Recommended for most users

Level 4: Flowstate Certified

• Extensive security audit
• Regular updates and maintenance
• Strong privacy protections
• Safe for sensitive data

Level 5: Flowstate Official

• Created by Flowstate team
• Highest security standards
• Full support and updates
• Safe for all use cases

Recommendation: Stick to Level 3 and above for important workflows. Use Level 1-2 widgets only for experimentation.

Widget Hosting Modes

Widgets can run in three different hosting modes:

Client-Side (Browser)

The widget runs entirely in your browser:

• Pros: Fast, no server costs, works offline
• Cons: Limited to browser capabilities, can’t run background tasks

Use for: Simple tools, calculators, timers, local data visualization

Server-Side (Flowstate)

The widget runs on Flowstate’s servers:

• Pros: More powerful, can run background tasks, access server resources
• Cons: Requires server resources, may have usage limits

Use for: Data processing, integrations, automation, complex workflows

External (Third-Party)

The widget runs on the developer’s servers:

• Pros: Developer controls infrastructure, can offer advanced features
• Cons: Requires trusting third-party servers, may have costs

Use for: Specialized integrations, proprietary services, advanced analytics

Security note: External widgets send data to third-party servers. Only install external widgets from trusted developers.

Widget Approval Process

Before appearing in the Widget Store, widgets go through an approval process:

Submission

Developers submit widgets with:

• Widget code and assets
• Description and documentation
• Requested permissions
• Hosting mode
• Privacy policy

Review

Flowstate team reviews:

• Code quality and security
• Permission appropriateness
• User experience
• Documentation completeness
• Privacy practices

Testing

Widgets are tested for:

• Functionality
• Performance
• Security vulnerabilities
• Compatibility
• Error handling

Approval or Rejection

Widgets are either:

• Approved: Published to Widget Store with appropriate trust level
• Rejected: Returned to developer with feedback for improvement

Ongoing Monitoring

Approved widgets are monitored for:

• Security issues
• Performance problems
• User complaints
• Policy violations

Widgets can be removed from the store if issues arise.

Managing Installed Widgets

Viewing Installed Widgets

See all your installed widgets:

1. Open the Widget Store
2. Go to “My Widgets” tab
3. See list of installed widgets with status

Configuring Widgets

Change widget settings:

1. Open the widget in expanded view
2. Click the settings icon
3. Modify configuration options
4. Save changes

Settings are applied immediately.

Updating Widgets

When widget updates are available:

1. You’ll see an update notification on the widget tile
2. Open the widget
3. Click “Update” to install the latest version
4. Review any new permissions or changes

Updates are installed without losing your data or settings.

Uninstalling Widgets

Remove widgets you no longer need:

1. Open the widget in expanded view
2. Click the settings icon
3. Select “Uninstall”
4. Confirm the action

Warning: Uninstalling a widget deletes all its data. Export important information first.

Example Widget: Transcript Widget

The Transcript Widget demonstrates the power of Flowstate widgets:

Features

• Live transcription: Real-time speech-to-text during calls and meetings
• Multi-language support: Transcribe in multiple languages
• Search: Find specific words or phrases in transcripts
• Export: Download transcripts as text or PDF
• Timestamps: See when each line was spoken
• Speaker identification: Track who said what (when available)

Tile View

The tile shows:

• Current transcription status (active, paused, stopped)
• Word count of current transcript
• Language being transcribed

Expanded View

The expanded view provides:

• Full transcript with timestamps
• Search bar to find specific content
• Language selector
• Export options (TXT, PDF, JSON)
• Settings for speaker identification and formatting

Use Cases

• Meeting notes and minutes
• Interview transcription
• Lecture and presentation capture
• Accessibility for hearing-impaired participants
• Content creation and documentation

The Transcript Widget shows how widgets can add sophisticated functionality to Flowstate without cluttering the core interface.

Widget Permissions

Widgets request permissions to access Flowstate features:

Common Permissions

• Canvas access: Read or modify canvas elements
• User data: Access your profile information
• Room access: Read or participate in Rooms
• Office access: Access Office data
• Network access: Make external API calls
• Storage: Store data locally or on servers
• Notifications: Send you alerts

Reviewing Permissions

Before installing, review what the widget can access:

1. Read the permissions list
2. Understand why each permission is needed
3. Decide if you’re comfortable granting access
4. Install only if permissions are appropriate

Revoking Permissions

You can revoke permissions after installation:

1. Open widget settings
2. Go to permissions tab
3. Disable specific permissions
4. Save changes

Note: Revoking permissions may break widget functionality.

Building Your Own Widgets

Flowstate provides a widget development framework:

Getting Started

1. Review the widget development documentation
2. Set up the development environment
3. Create a widget template
4. Implement your functionality
5. Test locally
6. Submit for review

Widget SDK

The SDK provides:

• Canvas API for interacting with Flowstate
• UI components for consistent design
• Authentication and permissions handling
• Storage APIs for persisting data
• Testing tools and utilities

Best Practices

• Request only necessary permissions
• Handle errors gracefully
• Provide clear documentation
• Follow Flowstate design guidelines
• Test thoroughly before submission
• Respond to user feedback

Publishing

Once your widget is ready:

1. Submit to Widget Store
2. Wait for review (typically 3-5 business days)
3. Address any feedback
4. Widget is published with appropriate trust level

Best Practices for Using Widgets

Install Selectively

Don’t install every widget you see. Choose widgets that solve real problems or add meaningful value.

Review Permissions

Always review permissions before installing. If a simple widget requests extensive access, be cautious.

Keep Widgets Updated

Install updates when available. Updates often include security fixes and new features.

Monitor Performance

If widgets slow down your canvas, consider uninstalling less-used widgets or using them less frequently.

Provide Feedback

Rate and review widgets you use. Your feedback helps other users and improves the ecosystem.

Report Issues

If a widget misbehaves, report it. This helps protect the community and improve widget quality.

Technical Details

Data Model

Each widget installation includes:

• Unique installation ID
• Widget ID (references the widget definition)
• User ID (who installed it)
• Position on canvas (x, y coordinates)
• Settings (widget-specific configuration)
• State (widget-specific data)
• Permissions granted
• Installation date
• Last updated date

Widget Lifecycle

1. Installation: Widget is added to canvas with default settings
2. Configuration: User customizes settings
3. Active use: Widget runs and provides functionality
4. Updates: New versions are installed
5. Uninstallation: Widget is removed and data is deleted

Storage

Widget data is stored separately from core Flowstate data:

• Widget metadata: MongoDB
• Widget state: MongoDB or widget-specific storage
• Widget assets: CDN or widget-specific hosting

This isolation ensures widget issues don’t affect core functionality.

Security

Widgets run in sandboxed environments:

• Limited access to Flowstate APIs
• Permissions enforced at runtime
• Network requests monitored
• Resource usage limited

This protects your data and ensures platform stability.

Integration with Other Features

Widgets integrate with Flowstate features:

Canvas

Widgets appear as tiles and can be positioned anywhere on your canvas.

Offices

Widgets can be installed on Office canvases, providing shared tools for teams.

Rooms

Widgets can interact with Rooms (with appropriate permissions), enhancing collaboration.

Passport

Widget usage and achievements can appear in your Passport.

Future Enhancements

Planned improvements to widgets include:

• Widget marketplace with paid widgets
• Widget collections and bundles
• Advanced permission controls
• Widget-to-widget communication
• Custom widget categories
• Widget analytics for developers
• Improved discovery and recommendations
• Widget templates for common use cases

Widgets make Flowstate extensible and adaptable to your needs. By providing a secure, flexible framework for adding functionality, they ensure Flowstate can grow with you.