Requirements source of truth

Full PRD v10 as provided. Use ⌘F to search.

Falcon Flowmira Ultimate Master PRD v10

Falcon Flowmira AI canvas for diagrams, workflows, and knowledge. Powered by Talk to Rafa.

Full Comprehensive Lovable Build Blueprint with Six Sprints, Talk to Rafa, Agentic AI, RAG, Semantic Search, Import/Export, Community, Analytics, Plugins and Data Persistence

Product Name: Falcon Flowmira
Product Type: Direct-to-consumer SaaS for diagramming, AI canvas workflows, RAG, templates, and visual productivity
Primary Owner / Platform Admin: joseph.ferdinand@falconveritas.com
Business Model: Free plan + ₹499/year Pro plan
Tenant Administration: Not required and must not be built
AI Policy: Bring Your Own LLM Key only. No Lovable AI, no Lovable Gateway, no Lovable-managed AI providers.

1. Product Vision

Build a world-class direct-to-consumer visual productivity platform that combines the best of Microsoft Visio, draw.io, Lucidchart, Miro, Canva-style template browsing, and AI-native agentic workflow builders.

The app must be simple for consumers, but powerful enough for advanced creators, developers, consultants, architects, students, founders, and workflow builders.

The product must include:

Beautiful pure canvas mode
Professional diagrams
AI-generated diagrams using user-owned LLM keys
Agentic workflow builder
RAG and Learning RAG
Template marketplace
User analytics
AI usage analytics
App usage analytics
Revenue analytics
Cost analytics
AI governance
Security and secret governance
Platform owner administration

This is a B2C SaaS app, not an enterprise tenant admin platform.

2. Explicit Non-Scope: No Tenant Administration

Do not build:

Tenant admin portal
Organization hierarchy management
Enterprise tenant provisioning
SCIM provisioning
SAML tenant administration
Department-level governance
Complex multi-tenant admin experiences
Enterprise workspace administration as a primary product experience

Still required:

Normal SaaS user isolation
Secure authentication
Platform owner/admin console
User management
Subscription management
Marketplace moderation
App analytics
AI governance controls
Cost and revenue analytics

3. Authentication and Account Management

Supported Account Options

The app must support:

Email and password signup
Email and password login
Magic link login
Google sign-in
Apple sign-in
Microsoft sign-in

Provider Enable/Disable Controls

The platform owner/admin must be able to enable or disable:

Email/password
Magic link
Google
Apple
Microsoft

User Account Features

Users must be able to:

Create account
Verify email
Login
Logout
Reset password
Change password
Update profile
Manage sessions
Delete account according to product policy
Manage connected AI providers
Manage subscription
Manage invoices and receipts

Recommended Consumer Security Features

Optional MFA
Passkeys/WebAuthn
Login alerts
Suspicious login detection
Device/session list
Rate limiting
Bot protection

4. Subscription Model

Only two subscription plans are required initially.

Free Plan

Free plan includes:

Limited diagrams
Limited projects
Limited RAG storage
Basic templates
Basic exports
BYOK AI support with limited app-side AI tools if needed
Community marketplace browsing

Pro Plan

Price: ₹499/year

Pro plan includes:

Unlimited diagrams subject to fair usage
Full pure canvas mode
Full agentic AI builder
Full RAG and Learning RAG
Full template library
Template cloning
Advanced exports
Diagram version history
Advanced analytics for personal usage
Whiteboard Mode access

Pro Plus Plan

Price: Configurable later by platform owner/admin

Pro Plus plan includes everything in Pro, plus:

Advanced Whiteboard Mode
Larger whiteboard object limits
Advanced workshop/facilitation tools
Advanced whiteboard exports
Advanced AI whiteboard generation using BYOK
Advanced whiteboard-to-diagram conversion
Higher RAG and semantic search limits
Higher file upload and image asset limits
Advanced analytics for personal usage
Priority access to future premium templates and plugins

Payment Providers

The app must support platform owner configuration for:

Stripe
Razorpay

Rules:

Payment keys configured later inside the app
No hardcoded keys
No Lovable secrets
Support test/live mode
Support webhook secret configuration
Support payment status sync
Support failed payment handling
Support refund tracking
Support invoice/receipt records

5. Strict AI Provider and Secret Policy

Mandatory AI Policy

The app must never use:

Lovable AI
Lovable Gateway
Lovable-hosted AI providers
Lovable-managed AI keys
Hidden default AI providers

BYOK Only

Users must connect their own AI provider keys.

Supported providers:

OpenAI
Azure OpenAI
Anthropic
Google Gemini
OpenRouter
Mistral
DeepSeek
Groq
Together AI
Perplexity API where applicable
Ollama local endpoint
LM Studio local endpoint
Custom OpenAI-compatible endpoint

Secure Secret Storage

All AI, payment, OAuth, and webhook secrets must be:

Encrypted before storage
Fingerprinted
Masked in UI
Hashed where lookup/verification is needed
Never displayed in plaintext after save
Never committed to code
Never stored in Lovable secrets
Audited on create/update/delete

Secret Metadata

For each secret, store:

Provider name
User owner or platform owner
Masked value
Fingerprint
Last four characters if safe
Created date
Updated date
Last used date
Rotation status
Test status
Audit log reference

6. AI Usage Cost Management

Even though users bring their own LLM keys, the product must help users understand AI usage, estimated cost, quality, and risk.

User-Level AI Usage Dashboard

Each user should see:

Total AI requests
Requests by provider
Requests by model
Input token usage
Output token usage
Estimated cost by model
Estimated cost by day/week/month
Average cost per diagram
Average cost per agent run
Average cost per RAG answer
Failed AI calls
Slow AI calls
Most expensive workflows
Most used prompts
Most used agents

AI Cost Estimation

The app should support:

Provider/model pricing configuration
Default pricing table editable by platform owner
User override pricing for custom providers
Estimated INR and USD cost display
Token-based estimated spend
Request-based estimated spend where provider pricing is not token based
Warning when costs exceed configured thresholds

AI Budgets

Users should be able to set:

Daily estimated AI budget
Monthly estimated AI budget
Per-agent-run budget warning
Per-workflow budget warning
Model-specific budget warnings

AI Cost Alerts

The app should notify users when:

Estimated daily budget is near limit
Estimated monthly budget is near limit
A workflow becomes unusually expensive
A provider/model has high failure rate
A model appears misconfigured

Platform-Level AI Analytics

Platform owner should see aggregate non-secret analytics:

Most connected provider types
Most popular model names
Total AI requests across app
AI feature adoption
Prompt-to-diagram usage
RAG usage
Agent workflow usage
Failure rates by provider type
Slowest provider types
Most used agents

Important privacy rule: The platform owner must not see user API keys or private prompt contents unless explicit support/debug mode is enabled by the user.

7. AI Governance

The app must include AI governance without enterprise tenant administration.

User AI Governance

Users should control:

Which provider is default
Which model is default
Whether RAG can use their uploaded files
Whether Learning RAG is enabled
Whether their diagrams can be used for personal memory
Whether prompt history is saved
Whether agent run traces are saved
Whether citations are required
Whether generated content needs confirmation before insertion

Platform AI Governance

Platform owner/admin should control:

Allowed provider types
Disabled provider types
Allowed custom endpoint support
Default model pricing table
AI feature availability by plan
Max file upload size for RAG
Max RAG sources per plan
Max agent steps per run by plan
Prompt abuse protections
Rate limits
Safety disclaimers
AI audit logs

AI Audit Logs

Log the following without storing secrets:

User ID
Feature used
Provider type
Model name
Token estimate
Cost estimate
Status success/failure
Latency
Timestamp
Agent/workflow ID where applicable
RAG source IDs used where applicable

AI Safety and Reliability

Add:

Prompt injection detection for RAG sources
Unsafe file detection where feasible
Source citation requirement for RAG answers
Human approval checkpoints for agentic workflows
Versioning for generated diagrams
Rollback after AI edits
Model fallback option chosen by user
Clear AI-generated content labels

8. App People Analytics

The platform must include product analytics focused on B2C growth and engagement.

User Acquisition Analytics

Track:

Signups per day/week/month
Signup method: email, magic link, Google, Apple, Microsoft
Landing page source where available
Referral source where available
Conversion from visitor to signup
Conversion from signup to first diagram

Activation Analytics

Track:

First diagram created
First template copied
First AI provider connected
First AI diagram generated
First RAG source uploaded
First workflow created
First export
First share link created

Engagement Analytics

Track:

Daily active users
Weekly active users
Monthly active users
Diagrams created per user
Workflows created per user
Templates copied per user
Average session length
Return frequency
Feature adoption
Canvas usage time
AI usage frequency

Retention Analytics

Track:

Day 1 retention
Day 7 retention
Day 30 retention
Monthly retention
Cohort retention
Churned users
Dormant users
Re-activated users

User Segmentation

Segment users by:

Free vs Pro
Signup method
AI connected vs not connected
Template users vs blank canvas users
RAG users vs non-RAG users
Heavy creators
Occasional users
Churn risk users

9. Revenue Analytics

The platform owner/admin must have a revenue dashboard.

Revenue Dashboard Metrics

Show:

Total revenue
Monthly recurring revenue equivalent
Annual recurring revenue equivalent
Pro subscriptions sold
Free-to-Pro conversion rate
Trial-to-paid conversion if trials are added later
Payment provider split: Stripe vs Razorpay
Revenue by month
Revenue by country/currency where available
Failed payments
Refunds
Net revenue
Churned subscriptions
Renewal rate

Subscription Analytics

Track:

Active Free users
Active Pro users
New Pro subscriptions
Cancelled Pro subscriptions
Expiring subscriptions
Renewed subscriptions
Grace period users
Payment failed users

Unit Economics

Estimate:

Average revenue per user
Average revenue per paying user
Customer acquisition source if available
Conversion rate by signup method
Revenue per feature cohort
Revenue per template category
Revenue per AI usage cohort

10. App Cost Analytics

The platform owner/admin must be able to estimate and monitor application operating costs.

Cost Categories

Track or manually configure:

Supabase database cost
Supabase storage cost
Supabase bandwidth cost
Supabase edge function cost
Email delivery cost
File storage cost
CDN/bandwidth cost
Payment processing fees
Marketplace payout cost if added later
Error monitoring/logging cost
Analytics infrastructure cost

Cost Dashboard

Show:

Estimated monthly infrastructure cost
Cost per active user
Cost per paying user
Storage usage growth
Database row growth
File upload volume
RAG storage usage
Diagram storage usage
Bandwidth usage
Payment processing fees
Gross margin estimate

Cost Alerts

Notify platform owner when:

Storage grows unusually fast
Bandwidth exceeds threshold
Database usage exceeds threshold
Edge functions fail or spike
Payment provider fees exceed estimate
Free users create abnormal resource load

11. Growth, Marketing and Virality Features

To make the B2C product stronger, add growth loops.

Public diagram share links
Private links
Password-protected share links
Expiring share links
Embed diagrams in websites
Export for LinkedIn, X, Instagram, YouTube thumbnails
Presentation mode

Referral Features

Referral code
Invite friends
Bonus templates for referrals
Pro discount campaigns later

Community Features

Public template gallery
Featured creators
Public creator profiles
Remix template button
Like/save templates
Report template

SEO Features

Public template pages
Public diagram example pages
Category landing pages
AI diagram generator landing pages
Sitemap generation
Open Graph previews

12. Canvas and Diagram Features

Pure Canvas Mode

Required:

Infinite canvas
Smooth pan and zoom
Snap-to-grid
Smart guides
Minimal UI chrome
Floating toolbar
Right-click context menus
Command palette
Dark mode
Light mode
Presentation mode
Frames and sections
Pages
Layers
Grouping
Lock/unlock
Comments
Version history

Diagram Types

Support:

Flowcharts
Swimlanes
BPMN 2.0
UML
ER diagrams
Data flow diagrams
Cloud architecture
Azure/AWS/GCP diagrams
Kubernetes diagrams
Network diagrams
Org charts
Mind maps
Wireframes
Floor plans
Customer journeys
Value stream maps
AI agent workflow diagrams
RAG pipeline diagrams
Automation workflows

Compatibility

Support:

draw.io import/export
XML diagram import/export
SVG export
PNG export
PDF export
Mermaid import/export
PlantUML import/export later
VSDX import where feasible
VSDX export as advanced future feature

13. Templates and Marketplace

Built-In Templates

Launch target: 100+ templates.

Template categories:

Flowcharts
Business processes
Startup planning
Product strategy
Software architecture
Cloud architecture
Database design
UML
BPMN
AI workflows
RAG pipelines
Agentic workflows
Education
Marketing
Personal productivity
Mind maps
Security diagrams

Marketplace Functions

Users can:

Browse templates
Preview templates
Copy templates
Clone templates
Save custom templates
Publish templates if creator mode is enabled
Like templates
Report templates

Marketplace Analytics

Platform owner can see:

Most copied templates
Most viewed templates
Conversion by template category
Templates driving Pro upgrades
Creator activity if creator mode is enabled

14. Platform Owner Administration

This is platform-level administration only, not tenant administration.

Permanent Owner

The initial platform owner must be:

joseph.ferdinand@falconveritas.com

Rules:

Seed automatically as Platform Owner
Unrevokable owner role
Cannot be deleted by other users
Cannot be downgraded by other users
Cannot be locked out by normal admin action
Owner transfer requires explicit secure owner-transfer workflow

Platform Admin Console Modules

Include:

Users
Subscriptions
Payments
Revenue analytics
Product analytics
AI usage analytics
AI governance
Cost analytics
Templates
Marketplace moderation
Authentication provider settings
Stripe settings
Razorpay settings
Feature flags
App settings
Email settings
Security settings
Audit logs
System health

15. Analytics Data Privacy

Analytics must be privacy-conscious.

Rules:

Do not expose user secrets
Do not expose full private prompts by default
Do not expose private document contents
Aggregate metrics where possible
Allow users to delete account data
Allow users to clear AI history
Allow users to clear RAG memory
Keep billing records as required by law/payment policy
Use audit logs for security-sensitive events

16. Database Modules

Recommended core tables/modules:

profiles
auth_provider_settings
app_settings
feature_flags
diagrams
diagram_versions
canvases
canvas_objects
templates
template_categories
marketplace_items
subscriptions
payment_events
payment_provider_settings
ai_providers
ai_provider_keys
ai_usage_events
ai_cost_estimates
ai_governance_settings
rag_sources
rag_chunks
rag_queries
agent_runs
agent_steps
workflows
workflow_steps
product_events
user_sessions
engagement_events
user_engagement_scores
user_funnels
cohort_snapshots
retention_snapshots
revenue_metrics_snapshots
cost_metrics_snapshots
audit_logs
system_health_events
retention_policies
deletion_jobs
trash_items
image_assets
annotations
plugin_manifests
plugin_installations
plugin_audit_logs
offline_sync_events

17. MVP Scope v2

Must Build in MVP

B2C user authentication
Email/password
Magic link
Google sign-in
Apple sign-in
Microsoft sign-in
Provider enable/disable controls
Free plan
₹499/year Pro plan
Stripe setup screen
Razorpay setup screen
BYOK AI provider setup
Encrypted key storage
No Lovable AI or Lovable Gateway
Pure canvas mode
Basic flowchart builder
Templates library target 100+
Template copy/clone
AI prompt-to-diagram using user key
Basic RAG upload and query
Agentic workflow builder MVP
AI usage analytics for users
AI governance settings
Product analytics dashboard for platform owner
Revenue analytics dashboard
Cost analytics dashboard
SEO public template pages
Community gallery MVP
Public share links
User engagement tracking
Acquisition, activation, retention, and conversion funnels
Expanded import/export and download formats
draw.io micro-feature parity checklist
draw.io import/export compatibility
Native project bundle export
Platform admin console
Joseph seeded as unrevokable platform owner

Post-MVP

Advanced Visio compatibility
Full marketplace creator economy
Paid templates
Referral system
Public gallery
Mobile apps
Desktop apps
Plugin SDK
Public API
Advanced agent orchestration
Advanced Learning RAG

18. Lovable Build Instructions

Mandatory instructions for Lovable build:

Build as a direct-to-consumer SaaS app.
Do not build tenant administration.
Do not build enterprise tenant hierarchy.
Do not use Lovable AI.
Do not use Lovable Gateway.
Do not use Lovable-managed provider keys.
Do not use hardcoded secrets.
Do not store payment keys in code.
Do not store AI keys in code.
All AI must be BYOK.
All secrets must be encrypted, fingerprinted, hashed where needed, masked, and audited.
Build Stripe and Razorpay configuration inside the app.
Build platform owner admin controls.
Seed joseph.ferdinand@falconveritas.com as unrevokable owner.
Include AI usage analytics.
Include AI cost estimation.
Include AI governance.
Include app people analytics.
Include revenue analytics.
Include infrastructure cost analytics.
Include SEO pages and sitemap generation.
Include community gallery and template discovery features.
Include user engagement tracking, funnels, retention, cohort analytics, and churn-risk indicators.
Include advanced import/export/download support matching and exceeding draw.io.
Include draw.io parity micro-features such as panels, scratchpad, custom libraries, layers, tags, tooltips, links, waypoints, connection points, containers, shortcut workflows, and auto-layout.
Build a beautiful, modern, pure canvas experience.
Make the app functional end-to-end, not only a mockup.

19. Definition of Success

A user can:

Sign up using any enabled authentication method.
Use Free or upgrade to ₹499/year Pro.
Add their own LLM key securely.
Create diagrams on a beautiful canvas.
Generate diagrams using AI.
Upload files for RAG.
Build AI workflows using agents.
Copy templates from the marketplace.
Understand their AI usage and estimated cost.
Control their AI memory and RAG learning.
Export and share diagrams.

The platform owner can:

Manage users and subscriptions.
Configure Stripe and Razorpay.
Configure auth provider availability.
Monitor product usage.
Monitor revenue.
Monitor app infrastructure cost.
Monitor AI feature usage.
Configure AI governance.
Moderate templates and marketplace items.
Retain unrevokable owner access.

21. SEO and Community Growth Features

The product must include strong SEO and community features to support organic growth, public discovery, creator growth, template distribution, and viral sharing. These features must be built for a direct-to-consumer product and must not introduce tenant administration.

21.1 SEO Strategy

The app should include SEO-friendly public pages for discoverable templates, examples, use cases, and AI diagram generators.

Required SEO Pages

Build indexable public pages for:

Public template gallery
Template category pages
Individual public template pages
Public example diagram pages
Use case landing pages
AI diagram generator landing pages
Flowchart maker landing page
BPMN diagram maker landing page
UML diagram maker landing page
ER diagram maker landing page
Network diagram maker landing page
Cloud architecture diagram maker landing page
Mind map maker landing page
Workflow builder landing page
RAG workflow builder landing page
Agentic AI workflow builder landing page
draw.io alternative landing page
Visio alternative landing page
Lucidchart alternative landing page
Miro alternative landing page

SEO Technical Requirements

The app must support:

Server-rendered or pre-rendered public SEO pages where feasible
Search-friendly URLs
Dynamic meta titles
Dynamic meta descriptions
Open Graph metadata
Twitter/X card metadata
Canonical URLs
Sitemap generation
Robots.txt configuration
Structured data/schema markup for templates and software pages
Fast page loading
Mobile-friendly pages
Image alt text
Clean heading hierarchy
Internal linking between templates, categories, and use cases
Public preview pages that do not expose private user data

The platform should include content sections for:

What the template is used for
How to use the template
Who the template is for
Related templates
Related diagram types
Popular use cases
FAQ sections
Comparison content for alternatives
Example workflows

Programmatic SEO

The product should support generating SEO-friendly pages from structured template metadata, including:

Template title
Template description
Category
Tags
Industry
Diagram type
Difficulty level
Preview image
Use cases
Related templates
Creator attribution if public creator mode is enabled

SEO Analytics

Platform owner/admin should be able to track:

Organic visitors
Landing pages by traffic
Template page views
Category page views
Search impressions if integrated later
Click-through rate if integrated later
Visitor-to-signup conversion
Visitor-to-template-copy conversion
Visitor-to-Pro conversion
Public page performance

21.2 Community Features

The product should include community features that allow users to discover, copy, remix, share, and optionally publish templates and diagrams.

Public Community Gallery

Build a public community gallery where users can browse:

Featured templates
Popular templates
Recently added templates
Staff picks
Trending diagrams
AI workflow templates
RAG pipeline templates
Flowchart templates
Startup templates
Developer templates
Business process templates
Education templates
Productivity templates

Template Discovery Features

Users should be able to:

Search templates
Filter by category
Filter by diagram type
Filter by popularity
Filter by newest
Filter by free/pro
Filter by creator
Filter by tags
Preview templates before copying
Copy templates into their own account
Remix templates
Save templates to favorites
Like templates
Share template links

Creator Profiles

If creator mode is enabled, users should have public creator profiles with:

Display name
Profile photo/avatar
Bio
Public templates
Public diagrams if enabled
Total template copies
Total likes
Featured templates
Social links if allowed
Report profile option

Template Publishing

Users should be able to publish templates if enabled by platform settings.

Publishing workflow should include:

Draft state
Preview state
Submit for review if moderation is enabled
Published state
Unlisted state
Archived state
Reported state

Community Moderation

Platform owner/admin must be able to:

Review published templates
Feature templates
Unfeature templates
Remove templates
Hide reported templates
Ban abusive users
Review reported content
Manage categories
Manage tags
Manage public gallery settings

Community Safety

Community features must include:

Report template
Report user/profile
Block user if user-to-user interaction is added
Content moderation queue
Spam prevention
Rate limits for publishing
Public content takedown workflow
Abuse audit logs

Community Engagement

Add engagement features:

Likes
Saves
Copy count
Remix count
Featured badges
Trending badges
New template badges
Staff pick badges
Creator leaderboard later
Weekly featured templates later

Community Notifications

Users should receive notifications for:

Template copied
Template liked
Template featured
Template reported
Template approved
Template rejected
New templates in followed category later

The app should include viral loops that encourage users to share diagrams and templates.

Users should be able to create:

Public share links
Private share links
Unlisted share links
Password-protected share links
Expiring share links
View-only diagram links
Template copy links

Embed Features

Users should be able to:

Embed public diagrams on websites
Embed public templates on websites
Generate iframe embed code
Control embed permissions
Show or hide branding based on plan

Support social-friendly exports and previews for:

LinkedIn
X/Twitter
Facebook
WhatsApp
Instagram image export
YouTube thumbnail export
Blog image export

Referral and Invite Features

Add:

Invite friends
Referral link
Referral code
Referral analytics
Bonus templates for referrals
Pro discount campaign support later

21.4 Public Template and Diagram Privacy

Community and SEO must respect privacy.

Rules:

Private diagrams must never be indexed.
Private templates must never appear in public galleries.
Public publishing must require explicit user action.
Public links must clearly show visibility status.
Users must be able to unpublish public items.
Deleted public items must be removed from public pages.
Public pages must not expose hidden private metadata.
Public previews must not expose API keys, secrets, RAG documents, private prompts, or private notes.

21.5 SEO and Community MVP Requirements

Include in MVP if possible:

Public template gallery
Template category pages
Individual public template pages
Template preview
Template copy/clone
Template likes/saves
Public share links
Open Graph previews
Sitemap generation
SEO metadata management
Platform owner moderation controls

Post-MVP:

Creator profiles
Paid creator marketplace
Creator revenue sharing
Public community diagrams
Leaderboards
Referral rewards
Embed widgets
Programmatic SEO for all use cases
Advanced SEO analytics

22. User Engagement Tracking and Behavioral Analytics

The product must include detailed user engagement tracking so the platform owner can understand usage, improve retention, identify conversion opportunities, and optimize the product experience. This must be designed for a direct-to-consumer app and must not introduce tenant administration.

22.1 Engagement Tracking Goals

User engagement tracking should help answer:

Are users reaching activation quickly?
Which features are used most?
Which features drive Pro upgrades?
Which templates drive repeat usage?
Which AI tools create the most value?
Where do users drop off?
Which users are likely to churn?
Which users are becoming power users?
Which onboarding steps need improvement?
Which acquisition channels bring high-quality users?

22.2 Core User Event Tracking

Track product events for each user, including:

Account Events

Signup started
Signup completed
Email verified
Login completed
Login failed
Logout completed
Password reset requested
Password changed
Magic link requested
OAuth login provider used
Account deleted

Onboarding Events

Onboarding started
Onboarding step completed
Onboarding skipped
First diagram created
First template copied
First AI provider connected
First AI generation completed
First RAG source uploaded
First export completed
First share link created

Canvas Events

Canvas opened
New diagram created
Shape added
Connector added
Object edited
Object grouped
Frame created
Page created
Layer used
Diagram saved
Diagram duplicated
Diagram version restored
Presentation mode opened
Export completed

Template Events

Template viewed
Template searched
Template filtered
Template previewed
Template copied
Template remixed
Template liked
Template saved
Template shared
Template published
Template reported

AI Events

AI provider connected
AI provider test succeeded
AI provider test failed
AI prompt submitted
AI diagram generated
AI workflow generated
AI agent run started
AI agent step completed
AI agent run failed
AI output accepted
AI output rejected
AI output edited
AI cost warning shown
AI budget threshold reached

RAG Events

RAG source uploaded
RAG source indexed
RAG indexing failed
RAG query submitted
RAG answer generated
RAG citation clicked
RAG source deleted
Learning RAG enabled
Learning RAG disabled
RAG memory cleared

Subscription Events

Pricing page viewed
Upgrade clicked
Checkout started
Checkout completed
Payment failed
Subscription activated
Subscription cancelled
Subscription renewed
Invoice viewed
Plan comparison viewed

Share modal opened
Public link created
Private link created
Password-protected link created
Expiring link created
Embed code copied
Shared diagram viewed
Shared template copied

22.3 Engagement Metrics Dashboard

The platform owner/admin dashboard must include engagement metrics such as:

Activity Metrics

Daily active users
Weekly active users
Monthly active users
Stickiness ratio: DAU/MAU
Average session duration
Median session duration
Sessions per user
Active users by plan
Active users by signup method

Creation Metrics

Diagrams created per day
Diagrams created per active user
Templates copied per day
AI diagrams generated per day
Workflows created per day
RAG sources uploaded per day
Exports completed per day
Share links created per day

Feature Adoption Metrics

Canvas usage adoption
AI usage adoption
RAG usage adoption
Template marketplace adoption
Export feature adoption
Sharing feature adoption
Presentation mode adoption
Community publishing adoption

Engagement Quality Metrics

Time to first diagram
Time to first AI generation
Time to first template copy
Time to first export
Time to first share
Repeat diagram creation rate
Repeat AI usage rate
Repeat template usage rate
High-engagement user percentage

22.4 Funnels

The app must support funnel tracking for important user journeys.

Track:

Landing page visited
Signup started
Signup completed
Email verified
First app session
First diagram created

Activation Funnel

Track:

User signs up
User completes onboarding
User creates first diagram
User copies first template
User exports or shares first diagram

AI Activation Funnel

Track:

AI provider settings opened
Provider added
Provider connection tested
First AI prompt submitted
First AI output accepted
First AI-generated diagram saved

RAG Activation Funnel

Track:

RAG page opened
Source uploaded
Source indexed
First RAG query completed
RAG result used in diagram/workflow

Pro Conversion Funnel

Track:

Pricing page viewed
Upgrade clicked
Checkout started
Payment completed
Pro feature used
Pro renewal completed

Template Funnel

Track:

Template gallery viewed
Template searched or filtered
Template previewed
Template copied
Template edited
Template exported/shared

22.5 Cohorts and Retention

The platform owner/admin must be able to view retention and cohort analytics.

Required cohort views:

Signup cohort
First diagram cohort
First AI usage cohort
First RAG usage cohort
First template copy cohort
Pro subscription cohort
Signup provider cohort
Acquisition source cohort where available

Required retention metrics:

Day 1 retention
Day 3 retention
Day 7 retention
Day 14 retention
Day 30 retention
Monthly retention
Rolling retention
Feature-based retention
Pro user retention
Free user retention

22.6 User Segmentation

Segment users by behavior and lifecycle stage.

Lifecycle Segments

New user
Activated user
Engaged user
Power user
Dormant user
Churn risk user
Re-activated user
Paying user
Cancelled user

Behavioral Segments

Template-first users
Blank-canvas users
AI-heavy users
RAG-heavy users
Workflow builders
Export-heavy users
Community creators
Share-heavy users
One-time users

Commercial Segments

Free users
Pro users
Upgrade-intent users
Failed-payment users
Renewal-risk users
High-value users

22.7 Churn Risk and Engagement Scoring

The platform should calculate engagement and churn-risk indicators.

Engagement Score Inputs

Recent login frequency
Diagrams created
Templates copied
AI usage frequency
RAG usage frequency
Exports completed
Shares created
Session duration
Return frequency
Pro feature usage

Churn Risk Signals

No login for defined period
No diagram created after signup
AI provider connection failed repeatedly
Payment failed
Subscription cancellation intent
Reduced activity compared with previous period
No usage after Pro upgrade
Low onboarding completion

Recommended Actions

The system should suggest actions such as:

Send onboarding reminder
Suggest templates
Suggest AI provider setup guide
Suggest Pro feature tutorial
Offer help article
Trigger win-back campaign later

22.8 In-App Messaging and Engagement Nudges

The app should support engagement nudges based on user behavior.

Examples:

Welcome checklist
Complete your first diagram prompt
Try a template suggestion
Connect your LLM key prompt
Try AI diagram generation prompt
Upload your first RAG source prompt
Export or share your diagram prompt
Upgrade suggestion when Pro value is clear
Re-engagement banner for dormant users

Rules:

Do not overwhelm users.
Allow dismissing nudges.
Do not show Pro upgrade prompts too aggressively.
Track nudge impressions, clicks, dismissals, and conversions.

Engagement tracking must be privacy-conscious.

Rules:

Do not track API keys or secrets.
Do not expose private prompts by default.
Do not expose uploaded RAG document contents in analytics.
Use event metadata rather than private content where possible.
Provide privacy policy coverage for analytics.
Allow account deletion workflows.
Respect applicable cookie/consent requirements where relevant.
Aggregate analytics for platform dashboards wherever possible.

22.10 Engagement Tracking MVP Requirements

MVP should include:

Product event tracking table
User sessions tracking
Signup and activation funnels
AI activation funnel
Pro conversion funnel
DAU/WAU/MAU dashboard
Feature adoption dashboard
Template usage dashboard
Basic retention dashboard
Basic churn risk indicators
Engagement score per user
Privacy-safe analytics design

Post-MVP:

Advanced cohort analysis
Behavioral segmentation engine
Automated lifecycle campaigns
In-app messaging builder
Referral attribution
SEO attribution
Creator analytics dashboard
Predictive churn scoring
Personalized product recommendations

23. Import, Export, Download and Interoperability Requirements

This section expands the product requirements after reviewing draw.io / diagrams.net import, export, save, publish, and interoperability behavior. The goal is to match draw.io where expected and exceed it with modern AI, B2C, developer, community, and marketplace-oriented formats.

23.1 Product Goal

The app must provide world-class import/export support so users can move diagrams in and out of the product without lock-in.

Key goals:

Let users import existing work from draw.io, Visio, Lucidchart, Gliffy, Mermaid, PlantUML, SQL, CSV, JSON, images, and documents.
Let users export professional diagrams for editing, sharing, printing, publishing, presentations, websites, documentation, and AI workflows.
Support editable round-trip export where possible.
Support high-quality static downloads for non-editable sharing.
Support developer-first formats for version control and automation.
Support public SEO/community template previews and downloadable templates.
Make export settings simple for casual users and powerful for advanced users.

23.2 Reference Capabilities Observed in draw.io / diagrams.net

Draw.io supports importing native .drawio and .xml files, Gliffy files, .vsdx Visio diagrams, Lucidchart diagrams, PNG files with or without embedded draw.io XML, SVG images, and JPEG images. It also supports text-based generation from SQL code, CSV data, text, Mermaid code, and freehand drawing. It works with local storage, Google Drive, OneDrive, NextCloud, Dropbox, GitHub, and GitLab. It does not support LibreOffice Draw .odg, .otg, and .fodg formats. Source: https://www.drawio.com/docs/manual/import/import-formats/

Draw.io export formats include .drawio, .xml, .png, .svg, .jpeg, .webp, .html, .pdf, JSON, URL export, iframe/embed options, and advanced export controls such as zoom, width, height, DPI, transparency, border width, and grid inclusion. Source: https://www.drawio.com/docs/manual/export/export-diagram/

Draw.io save formats include .drawio, editable .png with embedded diagram data, editable .svg with embedded diagram data, and .html; PDF can also contain embedded XML when exported with the diagram copy option. Source: https://www.drawio.com/docs/manual/editor/save-file-formats/

23.3 Native Editable Formats

The app must define its own native editable formats.

Required Native Formats

.dse or .diagramstudio native project file
.dse.json human-readable JSON project file
.dse.zip packaged project bundle
.drawio compatible export/import
.xml compatible export/import

Native File Requirements

Native project files should support:

Multi-page diagrams
Canvas state
Shapes
Connectors
Layers
Frames
Comments
Version metadata
Template metadata
Embedded assets where allowed
AI generation metadata where allowed
RAG source links without exposing private source contents
Custom shape library references
Export settings

Packaged Project Bundle

.dse.zip should include:

manifest.json
diagram.json
assets/
previews/
templates/
metadata.json
Optional README.md

This is useful for backup, migration, marketplace templates, and offline storage.

23.4 Import Formats

MVP Import Formats

The MVP should support importing:

.drawio
.xml
.dse / native format
.dse.json
.png image
.jpg / .jpeg image
.svg image
.webp image
Mermaid text
CSV data
SQL schema text
Plain text outline
Markdown outline

High-Priority Post-MVP Import Formats

Add support for:

.vsdx Microsoft Visio import
Visio stencil libraries where technically feasible
Gliffy files
Lucidchart files where technically feasible and legally permitted
PlantUML
Graphviz DOT
BPMN XML
DMN XML
OpenAPI / Swagger JSON or YAML
JSON Schema
Prisma schema
DBML
SQL DDL files
Kubernetes YAML
Docker Compose YAML
Terraform .tf files
CloudFormation JSON/YAML
Azure ARM/Bicep templates
GitHub repository structure import
Figma frame/image import later

Document-to-Diagram Import

Users should be able to upload documents and generate diagrams from:

PDF
DOCX
TXT
Markdown
CSV
XLSX
JSON
YAML

The system should use the user's own LLM key for document-to-diagram extraction.

AI-Assisted Import

For imperfect imports, the app should support:

AI cleanup suggestions
Auto-layout after import
Missing font warnings
Broken connector detection
Unsupported shape fallback handling
Image-to-editable-diagram extraction where feasible
OCR-assisted diagram reconstruction where feasible

23.5 Export and Download Formats

MVP Export Formats

The MVP should support downloading/exporting diagrams as:

Native .dse or .diagramstudio
.dse.json
.drawio
.xml
.png
.svg
.jpg / .jpeg
.webp
.pdf
.html
Public share URL

Professional Export Formats

Post-MVP should support:

Multi-page PDF
PDF with embedded editable diagram data
PNG with embedded editable diagram data
SVG with embedded editable diagram data
ZIP package containing all pages/assets
PowerPoint .pptx
Word .docx diagram report
Markdown .md documentation export
HTML documentation site export
JSON API export
CSV node/edge export
Excel .xlsx diagram inventory export
Animated GIF for animated flows
MP4/WebM video walkthrough export later

Developer Export Formats

Support exporting to:

Mermaid
PlantUML
Graphviz DOT
BPMN XML
DMN XML
OpenAPI flow documentation
JSON Schema documentation
DBML
SQL DDL from ER diagrams
Prisma schema from ER diagrams
Terraform skeleton from cloud diagrams later
Kubernetes YAML skeleton from architecture diagrams later

Presentation and Publishing Exports

Support:

Presentation mode link
Full-screen public presentation
PNG slide deck export
PDF slide deck export
PPTX export
Speaker-note-style diagram explanation export later
Social image export presets
Blog image export presets
LinkedIn carousel export later

23.6 Export Settings

Every major export flow should provide simple and advanced options.

Simple Export Options

Export current page
Export all pages
Export selected objects
Export selected frame
Export transparent background
Export with background
Export with grid
Export with comments hidden or visible
Export with watermark based on plan

Advanced Export Options

Page range
Scale/zoom percentage
Width
Height
DPI
Margin
Border width
Theme: light/dark/current
Background color
Transparent background
Include metadata
Include embedded editable diagram data
Include or exclude hidden layers
Include or exclude comments
Include or exclude links
Include or exclude tooltips
Rasterize text option
Embed fonts where legally allowed
Compress output
Password-protect PDF later

23.7 Round-Trip Editable Export

The app should support round-trip editing wherever possible.

Editable Export Targets

Native .dse
.dse.json
.dse.zip
.drawio
.xml
PNG with embedded editable metadata
SVG with embedded editable metadata
PDF with embedded editable metadata where feasible

Round-Trip Requirements

User can export file
User can re-import file
Diagram structure is preserved
Pages are preserved
Shapes are preserved
Connectors are preserved
Layers are preserved where supported
Comments and metadata are preserved where supported
Unsupported features are documented in import warnings

23.8 Import/Export Quality and Validation

The system must show clear validation results after import/export.

Import Report

After import, show:

File type
Pages imported
Objects imported
Connectors imported
Images imported
Unsupported objects
Replaced fonts
Broken links
Conversion warnings
Suggested cleanup actions

Export Report

After export, show:

Output format
Pages exported
File size
Whether editable metadata is included
Whether links are preserved
Whether layers are preserved
Known limitations

23.9 Storage Import Sources

Users should be able to import files from:

Local device
Drag and drop
URL import for supported public files
Google Drive later
OneDrive later
Dropbox later
GitHub later
GitLab later
Supabase Storage user library
Existing app template library
Community marketplace

No enterprise tenant administration is required.

23.10 Download and Export UX

The export UX should include:

Quick export button
Export modal
Format search
Recommended formats
Recently used formats
Format explanations
Preview before export
File size estimate
Quality estimate
Pro feature labels
Batch export option
Export history

Recommended quick export presets:

Edit later
Share image
Print PDF
Embed on website
Use in PowerPoint
Developer handoff
AI/LLM-readable JSON
Backup project
Social media post

23.11 Format Support Matrix

Must Match draw.io

.drawio import/export
.xml import/export
PNG import/export
SVG import/export
JPEG import/export
WebP export
HTML export/embed
PDF export
JSON export
URL export
Mermaid import
SQL import
CSV import
Text import
Visio .vsdx import where feasible
Gliffy import later
Lucidchart import later where feasible

Must Exceed draw.io

Native .dse project format
.dse.zip complete project bundle
PPTX export
DOCX report export
Markdown documentation export
Excel diagram inventory export
PlantUML import/export
Graphviz DOT import/export
BPMN XML import/export
OpenAPI-to-diagram import
SQL-to-ERD import/export
RAG document-to-diagram import
Agent workflow export/import
AI-readable JSON schema export
Social media export presets
Creator marketplace template packaging

23.12 Security Requirements for Import/Export

Import/export must be secure.

Requirements:

Sanitize imported SVG and HTML
Block malicious script injection
Validate file extensions and MIME types
Limit max file size by plan
Scan uploaded files where feasible
Strip dangerous embedded scripts
Warn users about unsafe HTML/SVG exports
Do not include secrets in exported files
Do not include API keys in metadata
Do not include private RAG source contents unless explicitly exported by the user
Do not expose private prompts in public exports by default
Audit sensitive import/export events

23.13 Monetization and Plan Gating

Free plan may include:

PNG export
SVG export
JPEG export
Basic PDF export
Native project export
draw.io import/export
Limited import file size

Pro plan should include:

Advanced PDF export
WebP export
HTML embed export
PPTX export
DOCX report export
Markdown export
ZIP project bundle
Batch export
Advanced export settings
Embedded editable metadata
Developer formats
AI-assisted import cleanup
Document-to-diagram import
Higher file size limits

23.14 MVP Requirements for Import/Export

MVP must include:

Import .drawio
Import .xml
Import PNG/JPEG/SVG images
Import Mermaid text
Import CSV/SQL/text/Markdown outlines
Export native project format
Export .drawio
Export .xml
Export PNG
Export SVG
Export JPEG
Export WebP
Export PDF
Export HTML
Export JSON
Export public share URL
Export current page/all pages/selection
Export with transparent background
Export with grid option
Export with scale/DPI options
Basic import validation report
Basic export report

Post-MVP:

VSDX import
VSDX export if feasible
Gliffy import
Lucidchart import where permitted
PPTX export
DOCX export
XLSX export
Markdown documentation export
PlantUML import/export
Graphviz DOT import/export
BPMN XML import/export
OpenAPI import
Agent workflow export/import
Batch export
ZIP project package

24. Deep draw.io Parity and Micro-Feature Requirements

This section captures the smaller, high-utility features that make draw.io / diagrams.net feel powerful in day-to-day use. The goal is not only to match these workflows, but to modernize them for a beautiful B2C, AI-first canvas product.

24.1 Product Principle

The app must not only provide major diagram types and exports. It must also include the detailed productivity features that users expect from mature diagramming software.

These micro-features are important because they reduce friction, speed up diagram creation, improve precision, enable reuse, support complex diagrams, and help users move from a rough idea to a polished visual asset.

24.2 Editor Themes and Workspace Modes

The app should provide multiple workspace modes inspired by draw.io's Classic, Simple, Minimal, and Sketch-style editor experiences.

Required modes:

Full editor mode
Simple editor mode
Minimal canvas mode
Pure canvas mode
Whiteboard/sketch mode
Presentation mode
Review/comment mode
Template preview mode
Mobile/tablet editing mode

Mode-specific behavior:

Full editor mode shows shapes, format panel, toolbar, layers, pages, and menus.
Simple editor mode hides advanced menus and focuses on common actions.
Minimal canvas mode uses floating panels.
Pure canvas mode removes distractions and keeps only contextual tools.
Whiteboard/sketch mode emphasizes freehand drawing, sticky notes, rough shapes, and quick ideation.
Presentation mode shows diagrams full-screen with page/frame navigation.

The app must include useful panels and dialogs similar to a mature diagram editor.

Required panels:

Shapes panel
Search shapes panel
Format panel
Layers panel
Tags panel
Outline/minimap panel
Pages panel
Comments panel
Properties/metadata panel
Template panel
AI assistant panel
RAG sources panel
Export panel
Version history panel

Panel behavior:

Panels can be shown/hidden.
Panels can collapse.
Panels can float in minimal mode.
Panels remember the user's last position and size.
Advanced panels can be hidden for beginner users.

24.4 Shape Library System

The app must offer a rich, searchable shape library experience.

Required features:

Searchable shape libraries
Recently used shapes
Favorite shapes
Basic shapes
Flowchart symbols
Arrows
Callouts
UML shapes
BPMN shapes
ERD/database shapes
Network shapes
AWS icons
Azure icons
GCP icons
Kubernetes icons
Security icons
UI wireframe components
Floor plan shapes
Org chart shapes
Mind map shapes
Whiteboard primitives
AI workflow nodes
RAG pipeline nodes
Automation workflow nodes

Shape library enhancements:

Drag and drop shapes onto canvas
Click to insert shape
Replace selected shape from library
Insert and connect selected shape
Show library categories with icons
Configure which libraries are visible
Search by synonym, category, and tag
AI-suggested shapes based on diagram context

24.5 Scratchpad and Personal Reusable Components

The app must include a personal scratchpad similar to draw.io's scratchpad.

Required scratchpad features:

User can drag shapes into scratchpad.
User can drag groups into scratchpad.
User can drag mini-process flows into scratchpad.
Scratchpad items can be renamed.
Scratchpad items can be reordered.
Scratchpad items can be deleted.
Scratchpad items can be searched.
Scratchpad can be exported as a library.
Scratchpad can be imported from a file.
Scratchpad is synced across devices for logged-in users.

Enhancements beyond draw.io:

AI can recommend reusable scratchpad components.
User can convert scratchpad item to template.
User can publish scratchpad item to marketplace if creator mode is enabled.
User can organize scratchpad items into folders.

24.6 Custom Shape Libraries and Stencils

The app must support custom libraries and stencils.

Required features:

Create new custom library
Import custom library XML where compatible
Import SVG icon sets
Import PNG/JPG/WebP image sets
Import animated GIF where supported
Add selected canvas objects to a custom library
Add groups and containers to a custom library
Rename library entries
Export custom library
Share custom library link
Load library by URL later
Marketplace shape packs later

Enhancements:

Library versioning
Library preview thumbnails
Library tags
Library categories
Private library vs public library options
AI-generated custom icon/shape suggestions
Convert uploaded SVG into theme-color-controllable shape where feasible

24.7 Pages, Frames and Multi-Page Diagrams

The app must support multi-page diagram documents.

Required page features:

Add page
Duplicate page
Rename page
Delete page
Reorder pages
Move between pages with keyboard shortcuts
Page thumbnails
Page-specific canvas settings
Page-specific background
Page-specific grid settings
Page-specific export settings
Copy objects between pages
Link shapes to pages

Frames:

Create frames on infinite canvas
Rename frames
Reorder frames
Export selected frame
Present frames as slides
Create frame from selection
Fit view to frame

24.8 Layers

The app must support layers for complex diagrams and interactive views.

Required layer features:

Add layer
Duplicate layer
Rename layer
Delete layer
Lock layer
Unlock layer
Hide/show layer
Reorder layers
Move selected object to layer
Select all objects on layer
Export with all layers
Export visible layers only
Layer-specific opacity later
Layer-specific tags later

Interactive layer features:

A shape can be configured as a button to show/hide layers.
Presentation mode can step through layers.
Export options can include/exclude hidden layers.
AI can suggest layer organization for complex diagrams.

24.9 Tags, Filters and Interactive Visibility

The app must support tagging shapes and connectors.

Required tag features:

Add tags to shapes
Add tags to connectors
Add tags to layers later
Search by tag
Select by tag
Hide/show by tag
Filter diagram by tag
Export visible tags only
Tag manager dialog

Use cases:

Feature flags in architecture diagrams
System status overlays
Process phase overlays
Risk overlays
Cost overlays
Environment overlays such as dev/test/prod

Enhancements:

AI-generated tags
Auto-tag by shape type
Tag-based diagram views
Saved views based on layer/tag combinations

24.10 Links, Tooltips, Metadata and Placeholders

The app must allow diagrams to become interactive and information-rich.

Required features:

Add hyperlink to shape
Add hyperlink to connector
Link to another page
Link to another frame
Link to external URL
Link to uploaded source document
Link to RAG source citation
Add tooltip to shape
Add tooltip to connector
Edit custom metadata/properties
Display metadata in properties panel
Use placeholders/variables in labels

Placeholder examples:

Page number
Page name
Current date
File name
Shape property
Diagram title
Creator name
Last updated date

Enhancements:

AI can generate missing tooltips.
AI can summarize shape metadata.
Tooltips can include citations from RAG.
Interactive public diagrams can show tooltips and links.

24.11 Connectors, Routing and Waypoints

The app must include a professional connector system.

Required connector features:

Straight connectors
Curved connectors
Orthogonal/right-angle connectors
Elbow connectors
Floating connectors
Fixed connectors
Custom connection points
Arrowheads at both ends
Connector labels
Multiple connector labels
Waypoints
Add waypoint
Remove waypoint
Clear waypoints
Reverse connector direction
Connect and clone shape
Drag shape onto direction arrow to connect
Snap connector to nearby shape
Auto-reroute connectors
Connector style presets
Dashed/dotted/solid connectors
Animated connector styles later

Advanced connector features:

Line jumps
Collision-aware routing
Avoid objects
Join connectors through waypoint nodes
Maintain connector path while moving objects
Show connector handles only when selected
AI cleanup for messy connectors

24.12 Connection Points

The app must allow users to control where connectors attach.

Required features:

Show connection points on hover
Fixed connection points
Floating perimeter connections
Add custom connection point
Move custom connection point
Delete custom connection point
Configure number of points per side
Snap connector to fixed point
Hold modifier key to force fixed connection
Preserve fixed points in custom library shapes

Enhancements:

AI-suggested connection point cleanup
Connection point templates for network, UML, ERD, and workflow shapes

24.13 Containers, Groups, Swimlanes and Collapsible Structures

The app must support smart containers.

Required features:

Group objects
Ungroup objects
Enter group
Exit group
Lock group
Resize group
Container shapes
Drop objects into container
Move container with child objects
Remove object from container
Collapse/expand container
Swimlane containers
Pool/lane structures
Add lane
Delete lane
Resize lane
Collapse/expand lane
Move shapes with lane

Use cases:

BPMN pools
Cross-functional flowcharts
Org charts
Architecture zones
Network security boundaries
App modules
Process phases

Enhancements:

AI can convert normal rectangles into smart containers.
AI can detect swimlane roles from a process description.
Containers can have rules, such as allowed shape types.

24.14 Tables, Lists and Structured Shapes

The app must support structured diagram shapes.

Required features:

Table shapes
Add row
Delete row
Duplicate row
Resize row/column
Entity/table shapes for ERD
UML class shapes with compartments
List shapes
Kanban-like column shapes
Matrix shapes
Roadmap blocks
Timeline blocks

Enhancements:

Import CSV into table shape
Convert table shape to CSV/XLSX
Convert SQL schema to ERD tables
AI normalize fields and relationships

24.15 Formatting and Styling

The app must include a powerful format panel.

Shape styling:

Fill color
Line color
Line width
Opacity
Rounded corners
Shadow
Sketch/rough style
Glass/modern style presets
Gradients later
Pattern fills later

Text styling:

Font family
Font size
Bold
Italic
Underline
Text color
Text alignment
Text position
Vertical text alignment
Writing direction
Rich text labels
Superscript/subscript later

Connector styling:

Line type
Line width
Line color
Start arrow
End arrow
Rounded connector corners
Curved connector mode
Dashed/dotted lines
Line jumps

Diagram-level styling:

Color scheme
Theme
Light/dark mode
Background color
Background image
Paper size
Page orientation
Grid visibility
Grid size
Guides visibility
Default style reset
Global shadow toggle

Enhancements:

Brand kits later
Saved style presets
Copy/paste style
AI polish diagram design
One-click beautify

24.16 Alignment, Arrangement and Precision Tools

The app must include precision editing tools.

Required features:

Align left
Align center
Align right
Align top
Align middle
Align bottom
Distribute horizontally
Distribute vertically
Bring forward
Send backward
Bring to front
Send to back
Match width
Match height
Match size
Rotate 90 degrees
Flip horizontal
Flip vertical
Autosize shape
Lock/unlock object
Snap to grid
Snap to guides
Smart spacing guides
Nudge by keyboard
Fine nudge with modifier keys
Create/remove space in canvas area

Enhancements:

AI auto-align
AI spacing cleanup
Smart diagram beautifier
Layout health score

24.17 Automatic Layouts

The app must provide automatic layout tools.

Required layouts:

Vertical flow layout
Horizontal flow layout
Vertical tree layout
Horizontal tree layout
Radial tree layout
Organic layout
Circle layout
Parallel layout
Org chart layout
Swimlane layout
BPMN cleanup layout
ERD layout
Cloud architecture layout

Layout settings:

Direction
Spacing
Layer spacing
Node spacing
Edge spacing
Compact mode
Preserve groups
Preserve selected area only
Layout selected container only
Undo layout

Enhancements:

AI recommends best layout.
AI explains why layout changed.
User can compare before/after layout.

24.18 Insert and Generate Tools

The app must include multiple ways to generate diagrams from structured input.

Required insert tools:

Insert shape
Insert text
Insert image
Insert icon
Insert table
Insert Mermaid
Insert SQL
Insert CSV
Insert plain text hierarchy
Insert Markdown outline
Insert freehand drawing
Insert layout
Insert template
Insert RAG source summary
Insert AI-generated diagram

24.19 Search, Find and Replace

The app must support finding content inside complex diagrams.

Required features:

Search shapes by label
Search connectors by label
Search metadata
Search tooltips
Search tags
Search comments
Find and replace text
Highlight search results
Jump to result
Filter search by page/frame/layer

Enhancements:

AI semantic search across diagrams
Search RAG sources linked to diagrams
Search templates and marketplace from canvas

The app must help users navigate large diagrams.

Required features:

Outline/minimap overview
Click minimap to jump
Fit window
Fit page
Fit selection
Reset view
Custom zoom
Zoom in/out
Pan with spacebar/mouse
Page/frame navigation
Breadcrumb navigation for groups/containers

Enhancements:

AI detect important regions
Named viewport bookmarks
Saved camera views
Guided walkthrough mode

24.21 Keyboard Shortcuts and Power User Productivity

The app must include robust keyboard shortcuts.

Required shortcuts:

Save
Undo/redo
Cut/copy/paste
Duplicate
Delete
Delete with connectors
Select all
Deselect all
Group/ungroup
Lock/unlock
Edit label
Edit link
Edit tooltip
Toggle layers
Toggle outline
Toggle format panel
Toggle shapes panel
Toggle tags
Find/replace
Zoom in/out
Fit page/window
Move/nudge objects
Resize objects
Bring forward/back
Bring to front/send to back
Previous/next page

Enhancements:

Shortcut command palette
Customizable shortcuts later
Shortcut cheat sheet
Onboarding shortcuts overlay

24.22 Context Menus and Quick Actions

The app must include rich right-click/context menus.

Context actions:

Edit label
Edit style
Edit link
Edit tooltip
Edit metadata
Add waypoint
Remove waypoint
Clear waypoints
Reverse connector
Group/ungroup
Bring forward/back
Lock/unlock
Move to layer
Add to scratchpad
Create template from selection
Export selection
AI improve selected area
AI explain selected area
AI convert selected area

24.23 Comments, Review and Collaboration-Light Features

Even as a B2C product, the app should support lightweight sharing and review.

Required features:

Add comment to diagram
Add comment to shape
Resolve comment
Reopen comment
Mention support later
View-only share link
Comment-enabled share link later
Export with comments hidden/visible
Review mode

Enhancements:

AI summarize comments
AI turn comments into diagram improvement tasks

24.24 Version History, Autosave and Recovery

The app must protect user work.

Required features:

Autosave
Manual save
Save status indicator
Version history
Restore previous version
Duplicate version
Compare versions later
Recover unsaved work
Conflict handling for multiple tabs/devices
Export backup

Enhancements:

AI-generated change summary
Named checkpoints
Before/after preview for AI changes

24.25 Image Handling and Asset Features

The app must support professional image use.

Required features:

Upload image
Drag image to canvas
Crop image
Resize image
Rotate image
Replace image
Set image as background
Use image in custom library
Image alt text for public/SEO pages
Compress image on export

Enhancements:

AI diagram extraction from image
OCR text extraction
Remove image background later if available without unsafe provider dependency
Convert image to reusable asset

24.26 Data, Metadata and Advanced Editing

The app should expose advanced editing options for power users.

Required features:

Edit object metadata
Edit diagram/page metadata
Edit raw JSON for native project later
Inspect object ID
Copy object ID
Custom properties
Data-driven labels
Metadata export
Metadata import

Enhancements:

AI validates metadata consistency
Custom property schema for templates
Template variables for reusable diagrams

24.27 Templates, Examples and Starter Workflows

The app must make starting easy.

Required features:

Template picker at new diagram creation
Blank canvas option
Recent templates
Popular templates
Featured templates
Category filters
Search templates
Preview template
Copy template
Remix template
Save as template
Template variables

Starter templates should include:

Blank flowchart
Swimlane process
BPMN process
UML class diagram
UML sequence diagram
ERD
AWS architecture
Azure architecture
GCP architecture
Kubernetes architecture
Org chart
Mind map
Customer journey
RAG pipeline
Agentic workflow
Product roadmap
Startup business model

24.28 Diagram Interactivity and Viewer Features

Public/shared diagrams must support a useful viewer.

Viewer features:

Zoom
Pan
Page navigation
Layer visibility toggle
Tag visibility toggle
Tooltips
Clickable links
Full-screen mode
Lightbox mode
Embed mode
Copy link
Download if allowed
Copy template if allowed

Enhancements:

Guided walkthrough
Interactive hotspots
Expand/collapse containers in viewer
AI explain this diagram in viewer if user provides key and has permission

24.29 Plugins, Extensions and Advanced Configuration

Post-MVP should support safe extensibility.

Possible features:

Plugin system
Template plugin packs
Shape pack plugins
Import/export plugins
AI agent plugins
Webhook integrations
Custom command palette actions
Public API later

Security requirements:

Plugins must not access secrets unless explicitly permitted.
Plugins must not expose private diagrams.
Plugin permissions must be visible.
Platform owner can enable/disable plugin system globally.

24.30 Desktop, Offline and Storage Convenience

Long-term product roadmap should include offline-friendly workflows.

Recommended features:

Progressive Web App
Offline cache for recent diagrams
Local-first editing later
Sync when online
Desktop app later
Import/export from local disk
Save backup copy locally
File association for native format later

24.31 What to Build Differently and Better Than draw.io

The app should exceed draw.io in these areas:

Beautiful modern B2C design
Pure canvas mode
AI-first prompt-to-diagram
BYOK-only AI provider management
AI cost analytics
AI governance
RAG and Learning RAG
Agentic workflow builder
SEO template marketplace
Creator community
Built-in revenue/product analytics
User engagement tracking
Churn and retention analytics
Native .dse.zip project bundles
AI-assisted import cleanup
AI diagram health scoring
AI layout/design beautification
Template remixing and creator profiles
Modern share links and social export presets

24.32 MVP Micro-Feature Checklist

MVP should include at minimum:

Shapes panel
Search shapes
Format panel
Pages
Layers
Grid
Guides
Snap-to-grid
Basic scratchpad
Basic custom library import/export
Multi-select
Group/ungroup
Lock/unlock
Bring forward/back
Align/distribute
Basic connector routing
Floating/fixed connectors
Waypoints
Connector labels
Basic containers
Swimlane template
Tooltips
Links
Basic metadata
Find/replace
Outline/minimap
Keyboard shortcuts
Autosave
Version history
Export selected/current/all pages
Template picker
Context menu
Right-click quick actions
Public viewer with zoom/pan/page navigation
AI beautify selected diagram area
AI explain selected diagram area

Post-MVP should add:

Advanced tags
Interactive layer/tag views
Advanced placeholders
Advanced custom libraries
Custom connection point editor
Advanced auto-layout engine
Table/list structured editing
Animated connectors
Guided walkthroughs
Plugin SDK
Full offline/desktop apps
Advanced viewer interactivity

25. User Data Persistence, Retention Controls and Deletion Governance

25.1 Core Principle

Every user's data must remain theirs. Anything a user creates, uploads, imports, saves, generates, annotates, publishes, or configures must persist until the user deletes it or until an explicitly configured platform retention policy applies.

The default product behavior must be persistent by default.

25.2 User-Owned Data That Must Persist

The following data must persist unless deleted by the user or affected by a configured retention policy:

Diagrams
Canvas documents
Pages
Frames
Shapes
Connectors
Layers
Tags
Comments
Annotations
Uploaded images
Uploaded documents
RAG sources
RAG embeddings/chunks
Generated diagrams
Saved AI outputs
Agent workflow definitions
Agent run history, if enabled
Templates created by the user
Scratchpad items
Custom shape libraries
Export history, if enabled
Share links
Profile settings
User AI provider configurations
User analytics preferences
Version history, subject to retention settings

25.3 User Deletion Controls

Users must be able to delete:

Individual diagram
Individual page/frame
Individual uploaded file
Individual image asset
Individual RAG source
Individual AI history item
Individual agent run
Individual workflow
Individual custom template
Individual share link
Entire account, subject to billing/legal retention restrictions

25.4 Soft Delete and Recovery

Deleted items should first move into a recoverable trash state.

Requirements:

Trash/recycle bin for deleted diagrams and files
Restore deleted item
Permanently delete item
Show deletion date
Show automatic permanent deletion date
Admin-configurable trash retention period
Default trash retention: 30 days unless changed

25.5 Platform Admin Retention Controls

Platform owner/admin must have a settings screen for retention policies.

Required controls:

Enable/disable automatic deletion
Configure auto-delete after X days
Default suggested value: 180 days
Configurable range: 30 to 3650 days
Apply policy to inactive Free users
Apply policy to inactive Pro users separately
Apply policy to deleted/trash items
Apply policy to AI logs
Apply policy to agent run traces
Apply policy to export history
Apply policy to temporary files
Apply policy to failed uploads
Apply policy to unverified accounts

Important:

All retention policies must be visible to affected users in privacy/settings pages.
Pro users should have stronger persistence protections by default.
Published public templates should not be removed merely because the author is inactive unless policy says so.
Billing and payment records may need to be retained according to legal/payment requirements.

25.6 Retention Exceptions

Do not auto-delete:

Active user data
Active Pro user data unless explicit policy allows it
Platform owner data
Active public marketplace templates unless separately moderated or deleted
Payment records required for legal/accounting compliance
Security audit logs required for abuse/fraud investigation within configured policy

25.7 User Notifications Before Auto-Deletion

Before automatic deletion, notify users:

30 days before deletion
7 days before deletion
1 day before deletion
After deletion completion

Notifications should include:

What will be deleted
Why it will be deleted
How to prevent deletion
How to export data before deletion
Link to retention policy

25.8 Data Export Before Deletion

Users must be able to export their data before deletion.

Export options:

Export all diagrams
Export all templates
Export all RAG source metadata
Export native project bundles
Export user profile data
Export account archive ZIP

Do not export secrets in plaintext.

25.9 Admin Retention Dashboard

Platform owner/admin should see:

Total stored diagrams
Data by user segment
Inactive users at risk of deletion
Upcoming deletion jobs
Recently deleted items
Failed deletion jobs
Storage saved by cleanup
Retention configuration history

25.10 Audit Logging

Log:

User deletion events
Admin retention setting changes
Auto-delete jobs
Restores
Permanent deletions
Failed deletion attempts
Data export events

26. Advanced Image Handling and Annotation Requirements

26.1 Image Handling Goals

The platform should support professional image workflows for diagrams, whiteboards, documentation, screenshots, references, annotations, template previews, and public sharing.

26.2 Image Import and Asset Management

Users must be able to:

Upload images
Drag and drop images
Paste images from clipboard
Import image from URL where safe
Import PNG
Import JPEG/JPG
Import SVG
Import WebP
Import GIF where supported
Store uploaded images in user asset library
Rename image assets
Delete image assets
Replace an image while preserving size/position
Reuse image across diagrams
View image metadata

26.3 Image Editing

Required image editing features:

Resize
Crop
Rotate
Flip horizontal
Flip vertical
Lock aspect ratio
Opacity control
Border control
Shadow
Rounded corners
Mask to shape
Set as background
Fit image to frame
Compress image for export
Replace image

Post-MVP:

Basic filters
Blur
Grayscale
Brightness/contrast
Remove background if provider support is configured by user/admin
OCR text extraction
Convert screenshot to editable diagram using BYOK AI

26.4 Annotation Tools

The app must support annotation on images and diagrams.

Required annotation tools:

Arrow annotation
Line annotation
Rectangle highlight
Circle/ellipse highlight
Freehand pen
Highlighter
Text note
Callout label
Numbered marker
Blur/redaction box
Pin/comment marker
Sticky note
Measurement ruler later

Annotation behavior:

Annotations remain editable
Annotations can be grouped with image
Annotations can be hidden/shown
Annotations can be exported with or without the base image
Annotation layers can be locked
Annotation color and style presets

26.5 Screenshot and Diagram Reconstruction

Users should be able to upload screenshots or images and use their own AI provider key to:

Extract text with OCR
Detect shapes
Detect arrows/connectors
Recreate editable diagram approximation
Suggest cleanup
Convert whiteboard photo into structured diagram
Convert hand-drawn flow into digital flowchart
Convert architecture screenshot into editable components

26.6 Image Security

Requirements:

Validate file type and MIME type
Set file size limits by plan
Sanitize SVG
Strip dangerous scripts from SVG/HTML content
Do not expose private images in public templates unless user publishes them
Do not include hidden private metadata in public exports
Allow users to delete image assets permanently

27. Offline, PWA and Desktop Roadmap

27.1 Progressive Web App MVP

The app should be installable as a PWA.

MVP PWA features:

Installable app shell
Responsive canvas UI
Offline fallback page
Cached static assets
Recent diagram quick access
Push notification support later
Share target support later

27.2 Offline Editing Roadmap

Post-MVP offline features:

Local cache for recent diagrams
Offline open for cached diagrams
Offline edits queued locally
Sync when online
Conflict detection
Conflict resolution UI
Version checkpoint before sync
User warning when working offline

27.3 Local-First Storage Roadmap

Long-term:

Local-first document store
File-system-backed diagrams in desktop app
End-to-end encrypted local cache option
Manual local backup
Export all data archive
Import backup archive

27.4 Desktop App Roadmap

Future desktop apps:

Windows
macOS
Linux

Desktop app capabilities:

Open native .dse files from disk
Save native files to disk
File association for .dse / .diagramstudio
Offline editing
Local asset library
Local export engine
Local LLM endpoint support through Ollama/LM Studio
Desktop notifications
OS clipboard integration

27.5 Mobile and Tablet Roadmap

Future mobile/tablet support:

Tablet-optimized canvas
Touch gestures
Pencil/stylus support
Mobile viewer
Mobile commenting
Quick diagram capture
Photo-to-diagram upload

28. Custom Plugin and Extension Platform

28.1 Plugin Vision

The app should support a safe custom plugin architecture so power users and creators can extend the product without compromising user data, secrets, or platform stability.

28.2 Plugin Types

Supported plugin categories:

Shape packs
Icon libraries
Template packs
Import plugins
Export plugins
AI agent plugins
RAG connector plugins
Canvas tools
Format/style presets
Automation actions
Developer integrations
Marketplace widgets

28.3 Plugin Permissions

Every plugin must declare permissions.

Permission categories:

Read current diagram
Modify current diagram
Read user asset library
Write to user asset library
Access selected objects only
Access RAG source metadata
Access network
Access export APIs
Access AI provider through user's selected provider only
Access storage

Rules:

Plugins must never access raw secrets.
Plugins must never receive AI API keys directly.
Plugins must use secure proxy/execution APIs.
Users must approve plugin permissions.
Platform owner can disable plugin system globally.
Platform owner can remove unsafe marketplace plugins.

28.4 Plugin Marketplace

Future marketplace features:

Browse plugins
Install plugin
Disable plugin
Uninstall plugin
Rate/review plugin
Report plugin
Featured plugins
Verified creator badge
Plugin changelog
Plugin version history

28.5 Plugin Developer Experience

Future developer support:

Plugin SDK
Plugin manifest
TypeScript types
Sandbox runtime
Local plugin dev mode
Example plugins
Import/export plugin templates
AI agent plugin templates
Documentation and API reference

28.6 Plugin Security

Requirements:

Sandboxed execution
Strict permission model
No direct secret access
User consent before install
Review process for public plugins
Rate limits
Audit logs
Kill switch for unsafe plugins
Content Security Policy controls

29. Deep Research: How AI and Agentic AI Can Help Flow Diagram Creation

29.1 Research Summary

AI diagram tools increasingly support prompt-to-diagram, workflow generation, architecture generation, editable outputs, and diagram-as-code workflows. Eraser describes a workflow where users write a structured prompt, identify phases/tasks/start/end points, generate a workflow diagram, refine it with follow-up prompts, and manually adjust the final layout. Source: https://www.eraser.io/ai/workflow-diagram-generator

Agentic diagram tools are moving beyond static flowcharts into specialized agent/RAG/MCP diagrams, animated flows, multi-agent orchestration, tool-call workflows, and scenario playback. Chartado highlights text-to-animated architecture diagrams for multi-agent systems, RAG pipelines, function/tool calling workflows, fan-out orchestration, MCP tool servers, reflection loops, and agentic RAG. Source: https://chartado.com/ai-architecture-diagram-generator/

Modern canvas AI SDK patterns show that an AI agent can read and manipulate the canvas directly. Tldraw documents AI approaches including canvas-as-output, visual workflows, and AI agents that access editor APIs to read and modify canvas content. Source: https://tldraw.dev/docs/ai

Tldraw's agent starter kit shows a canvas agent can create, update and delete shapes, draw freehand strokes, rotate, resize, align, distribute, stack, reorder shapes, track todos, move viewport, count matching shapes, schedule reviews, and call external APIs. Source: https://tldraw.dev/starter-kits/agent

Agent architecture documentation guidance emphasizes that production agent diagrams should explicitly represent orchestrators/planners, tool registries, memory layers, sub-agents, human-in-the-loop gates, checkpoint stores, and guardrails/evaluation layers. Source: https://architecturediagram.ai/blog/ai-agent-architecture-diagrams

29.2 AI Features for Flow Diagram Creation

Prompt-to-Flowchart

User describes a process in natural language and AI creates a flowchart with:

Start node
End node
Process steps
Decision nodes
Branches
Loops
Error paths
Roles
Inputs and outputs

Document-to-Flowchart

User uploads SOPs, PDFs, manuals, policies, meeting notes, requirements, or user stories. AI extracts:

Actors
Process steps
Decision points
Exceptions
Handoffs
Approval gates
Data inputs
Outputs

Then the system generates a structured diagram using the user's BYOK provider.

Meeting Notes to Process Map

AI can convert meeting notes into:

Process flow
Swimlane diagram
Action workflow
Responsibility map
Decision tree
Follow-up task diagram

Screenshot or Whiteboard to Diagram

AI can analyze an image or whiteboard photo and reconstruct:

Editable shapes
Connectors
Labels
Annotations
Layout suggestions

Flow Cleanup Agent

An AI cleanup agent should:

Detect crossed connectors
Detect missing start/end nodes
Detect unlabeled decisions
Detect disconnected nodes
Detect inconsistent symbols
Detect duplicate steps
Suggest auto-layout
Improve spacing
Improve naming
Group related steps

Diagram Explainer Agent

AI should explain diagrams in plain language:

What the process does
Who is involved
Where risk exists
Where bottlenecks exist
Which steps are unclear
What improvements are possible

Flow Optimization Agent

AI should suggest:

Remove redundant steps
Merge duplicate approvals
Add missing validation
Highlight bottlenecks
Recommend automation opportunities
Identify manual steps
Recommend RAG/agent automation candidates

Swimlane Agent

AI should convert a simple process into a swimlane diagram by identifying:

Roles
Teams
Systems
Departments
Ownership boundaries
Handoffs

BPMN Agent

AI should convert normal flowcharts to BPMN-like diagrams with:

Events
Activities
Gateways
Pools
Lanes
Message flows
Error/exception paths

Agentic Workflow Agent

AI should turn normal business flows into executable or semi-executable agentic workflows with:

Trigger node
Agent node
Prompt node
RAG retrieval node
Tool/API call node
Human approval node
Conditional branch node
Output/export node

29.3 Agentic AI Architecture Inside the App

Recommended agentic architecture:

Planner agent: understands user goal and plans diagram creation.
Parser agent: extracts steps, roles, decisions, entities, and data flows.
Diagram builder agent: creates canvas nodes and connectors.
Layout agent: chooses structure and spacing.
Style agent: applies visual theme and readability improvements.
Validator agent: checks completeness and correctness.
Explainer agent: generates summary and notes.
RAG agent: retrieves relevant context from user's knowledge base.
Reviewer agent: checks for ambiguity, missing steps, and contradictions.
Export agent: suggests best export/download format.

29.4 Canvas Agent Capabilities

The canvas agent should be able to safely perform these actions:

Create shapes
Create connectors
Edit labels
Reposition objects
Resize objects
Align objects
Distribute objects
Apply layout
Apply styles
Create frames
Create pages
Create layers
Add tags
Add tooltips
Add links
Add annotations
Add comments
Group objects
Move objects into containers
Generate version checkpoint before changes
Explain every change
Ask user before destructive operations

29.5 AI Interaction Patterns

The UI should support these AI interaction modes:

Chat + Canvas

A right-side AI panel where the user asks for changes and sees proposed edits.

Select and Ask

User selects part of canvas and asks:

Improve this
Explain this
Convert to BPMN
Add missing decision points
Make this a swimlane
Clean up connectors
Make it presentation-ready

Inline AI Actions

Right-click actions:

AI improve selected area
AI explain selected area
AI add tooltips
AI add annotations
AI create missing connections
AI convert to template
AI export recommendation

Scenario Playback

For agentic/RAG workflows, user can play through a scenario step by step:

Request enters system
Agent calls tool
RAG retrieves context
Human approval occurs
Output is produced

AI Review Checklist

AI shows a checklist before applying changes:

Nodes to add
Nodes to remove
Connectors to change
Layout changes
Style changes
Risks or assumptions

29.6 AI Governance for Diagram Creation

AI diagram features must follow BYOK and governance policies:

Use only user-selected provider/model.
Do not use Lovable AI or Lovable Gateway.
Show estimated token/cost before large operations.
Create version checkpoint before AI edits.
Require confirmation before destructive edits.
Do not send private RAG sources unless user enables RAG context.
Show citations when using RAG.
Store AI traces only if user allows it.
Mask secrets in prompts and exports.

29.7 AI Differentiators to Build

Build features that make this app world-class:

Prompt-to-flowchart
Prompt-to-swimlane
Prompt-to-BPMN
Document-to-process-map
Screenshot-to-editable-diagram
Whiteboard-photo-to-flowchart
Diagram-to-SOP document
Diagram-to-agentic-workflow
Diagram health score
Diagram readability score
Process bottleneck detection
Automation opportunity detection
AI-generated tooltips
AI-generated annotations
AI-generated presentation script
AI-generated export recommendations
AI-generated marketplace template metadata
AI version comparison summary
Multi-agent diagram repair workflow
AI learning from user's prior diagram style if enabled

29.8 MVP AI Flow Diagram Features

MVP should include:

Prompt-to-flowchart
Prompt-to-swimlane
AI cleanup selected area
AI explain selected area
AI add missing connectors
AI suggest decision nodes
AI auto-layout recommendation
AI generate tooltip/annotation
AI convert document text to process steps
AI cost estimate per generation
AI version checkpoint before applying edits

Post-MVP:

Screenshot-to-editable-diagram
BPMN conversion agent
Agentic workflow execution design
Scenario playback
Multi-agent canvas collaboration
Diagram health scoring
Process optimization recommendations
Automated template metadata generation

30. Lovable Build Instruction Addendum v7

Mandatory additional instructions:

All user-created data must persist by default unless the user deletes it or a visible configured retention policy applies.
Add admin setting for automatic deletion after configurable days, default option 180 days.
Add retention dashboard, soft delete, trash restore, permanent delete, and pre-deletion notifications.
Add advanced image handling, annotation tools, OCR-ready roadmap, and screenshot-to-editable-diagram roadmap.
Add PWA installability and offline roadmap.
Add desktop app roadmap for Windows, macOS, and Linux.
Add custom plugin architecture with strict sandboxing and no raw secret access.
Add agentic AI flow diagram creation features using BYOK only.
Add AI canvas agent capabilities with version checkpoints and human confirmation before destructive changes.
Continue to enforce: no tenant administration, no Lovable AI, no Lovable Gateway, no hardcoded secrets, Joseph as unrevokable platform owner.

31. Production-Ready Agentic AI Diagram Modeling Requirements

31.1 Purpose

The platform must support real production-grade agentic AI workflow documentation, not only generic flowcharts. Users must be able to visually model, design, explain, validate, and improve modern AI systems that include orchestrators, planners, agents, sub-agents, tools, memory, retrieval, checkpoints, human approvals, guardrails, evaluations, and outputs.

This capability is required because agentic AI systems are not simple linear flows. They often include loops, retries, delegation, memory access, tool calling, retrieval-augmented generation, human-in-the-loop steps, validation layers, and persistent state.

31.2 Required Agentic AI Diagram Types

The app must support purpose-built templates and shape libraries for:

Single-agent workflow diagram
Multi-agent orchestration diagram
Orchestrator-worker diagram
Planner-executor diagram
Supervisor-agent diagram
Router-agent diagram
Reflection loop diagram
Critic-reviewer diagram
RAG pipeline diagram
Agentic RAG diagram
MCP tool server diagram
Tool calling workflow diagram
Human-in-the-loop approval diagram
Guardrails and evaluation pipeline diagram
Memory architecture diagram
Checkpoint and resumability diagram
Async job orchestration diagram
Agent swarm diagram
ReAct-style reasoning/action workflow diagram
Document processing AI workflow diagram
Customer support AI agent workflow diagram
AI research assistant workflow diagram
AI coding agent workflow diagram
AI workflow automation diagram

31.3 Mandatory Agentic AI Shape Library

The app must include a dedicated Agentic AI shape library with at least the following nodes.

Core Agent Nodes

User goal/input
AI agent
Orchestrator
Planner
Executor
Supervisor
Router
Coordinator
Worker agent
Specialist sub-agent
Critic agent
Reviewer agent
Evaluator agent
Reflection agent
Summarizer agent
Research agent
Writer agent
Coder agent
Tool-using agent
Retriever agent
Memory manager agent

Tool and Integration Nodes

Tool registry
Tool selector
Function call
API tool
Web search tool
Database tool
File system tool
Code execution tool
Browser tool
Email tool
Calendar tool
Payment tool
CRM tool
MCP client
MCP server
External service
Webhook
Queue
Scheduler

Memory and Context Nodes

Short-term memory
Long-term memory
Working memory
Episodic memory
Semantic memory
Conversation history
Scratchpad
Vector database
Embedding model
Chunking pipeline
Context builder
Context window
Prompt memory
User preference memory
Project memory
Diagram memory

RAG Nodes

RAG source
Document loader
Text splitter
Embedding generator
Vector index
Retriever
Reranker
Citation builder
Context assembler
Grounded answer generator
Source verifier
Hallucination checker
Knowledge refresh job
Learning RAG updater

Control Flow Nodes

Start
End
Decision
Conditional branch
Loop
Retry
Timeout
Error handler
Fallback model
Model switch
Human approval gate
Manual review
Escalation
Checkpoint
Resume point
State store
Task queue
Parallel fan-out
Aggregation
Voting/consensus
Confidence threshold

Guardrail and Governance Nodes

Input guardrail
Output guardrail
Prompt injection detector
PII detector
Safety classifier
Policy checker
Grounding checker
Citation checker
Bias checker
Quality evaluator
Cost budget checker
Rate limit checker
Audit logger
Trace recorder
Redaction layer
Secret masker

Model and Provider Nodes

LLM model
Small model
Vision model
Embedding model
Reranking model
Local model
BYOK provider
OpenAI-compatible endpoint
Provider router
Model fallback chain
Cost estimator
Token meter

31.4 Agentic AI Connector Types

Agentic diagrams need specialized connectors beyond normal arrows.

Required connector types:

Request flow
Response flow
Tool call
Tool result
Retrieval query
Retrieved context
Memory write
Memory read
Human approval
Error path
Retry path
Fallback path
Escalation path
Async event
Queue message
Evaluation result
Guardrail decision
Citation link
Cost telemetry
Audit trace

Connector styling:

Solid line for normal request/response flow
Dashed line for optional/fallback paths
Dotted line for telemetry/audit flow
Double line for human approval gates
Colored route for error/retry paths
Animated flow option in viewer mode later

31.5 Agentic AI Object Metadata

Every agentic AI node should support structured metadata.

Required metadata fields:

Node type
Description
Role/purpose
Input schema
Output schema
Prompt template reference
Model/provider reference
Tool permissions
Memory access scope
RAG source access
Human approval required: yes/no
Cost estimate
Latency estimate
Risk level
Guardrails applied
Retry policy
Timeout policy
Logging level
Version
Owner/user
Last updated date

31.6 Agentic AI Diagram Validation

The AI governance and diagram validation engine must be able to detect:

Missing start node
Missing end node
Agent without model/provider
Tool call without tool registry
RAG flow without retriever
RAG flow without citation/grounding checker
Memory write without retention policy
Human approval gate missing before high-risk step
No fallback path for critical model/tool failure
No error handler
No checkpoint for long-running workflow
No cost budget checker
No audit logger for sensitive workflow
Orphaned node
Circular loop without stop condition
Prompt injection risk in RAG source
Used tool lacks declared permissions

31.7 Agentic AI Diagram Health Score

The platform should calculate an AI workflow health score using:

Completeness
Readability
Guardrail coverage
RAG grounding coverage
Human approval coverage
Error handling coverage
Cost control coverage
Observability coverage
Security risk level
Maintainability

The score should include:

Overall score
Category breakdown
List of issues
Suggested fixes
One-click AI repair proposal

31.8 Agentic AI Templates

The app must include ready-made templates for:

Basic chatbot with tools
Talk to Rafa assistant flow
RAG chatbot
Learning RAG assistant
Multi-agent research workflow
Planner-executor workflow
Orchestrator-worker workflow
Human approval workflow
Agent with MCP server
Document ingestion pipeline
Customer support automation
Sales assistant workflow
Code review agent workflow
Compliance review agent workflow
Diagram generation agent workflow
AI cost governance workflow
Prompt injection defense workflow
Guardrails and eval workflow

31.9 Agentic AI Export Requirements

Agentic diagrams should export to:

Native project format
JSON workflow schema
Agent workflow JSON
Mermaid
Markdown documentation
PDF architecture report
PNG/SVG
PPTX
DOCX design document
YAML workflow specification later

31.10 Agentic AI Execution Readiness Label

Agentic diagrams are design-first, not necessarily executable. The app should clearly label each diagram as:

Conceptual design
Implementation-ready design
Executable workflow draft
Documentation-only
Needs validation

The app must not claim a workflow is executable unless the required execution engine and integrations are implemented.

32. Talk to Rafa: Context-Aware Agentic AI Chatbot and Semantic Search

32.1 Product Requirement

The platform must include a built-in AI chatbot named Talk to Rafa.

Talk to Rafa is not a generic chat widget. It is a context-aware, BYOK-powered, agentic AI assistant that understands the user's current diagram, selected objects, templates, RAG sources, prior diagrams, preferences, and current task context.

32.2 Mandatory Naming

The chatbot must be called:

Talk to Rafa

Do not call it:

AI Assistant
Chatbot
Copilot
Lovable AI
Rafa AI Gateway

The user-facing feature name must be Talk to Rafa.

32.3 BYOK Requirement

Talk to Rafa must use only the user's configured AI provider and API key.

Rules:

No Lovable AI
No Lovable Gateway
No Lovable-managed provider key
No hidden default model
No hardcoded provider key
User chooses provider/model
User can change provider/model
User can disable Talk to Rafa
User can clear Talk to Rafa history

32.4 Core Talk to Rafa Capabilities

Talk to Rafa must help users:

Create diagrams from prompts
Improve existing diagrams
Explain diagrams
Search diagrams semantically
Find templates
Generate workflows
Generate agentic AI diagrams
Generate RAG diagrams
Convert notes to diagrams
Convert documents to process maps
Convert selected objects to a template
Add missing connectors
Add decision nodes
Add tooltips
Add annotations
Design agentic workflows
Review architecture diagrams
Validate BPMN/flowchart logic
Estimate AI cost for a generation
Suggest export format
Explain errors
Help configure BYOK providers
Help use the app features

32.5 Context Awareness

Talk to Rafa should understand context from:

Current diagram
Current page/frame
Current selection
Visible viewport
Diagram metadata
Shape labels
Connector labels
Tooltips
Comments
Layers
Tags
User-created templates
Scratchpad items
RAG sources selected by user
Recent user actions
AI provider settings, without seeing raw secrets
Subscription plan
Export target
Current error or warning

32.6 Semantic Search

The platform must include semantic search integrated into Talk to Rafa.

Semantic search should work across:

Diagram titles
Shape labels
Connector labels
Tooltips
Comments
Tags
Metadata
Templates
Marketplace templates
User scratchpad
RAG source titles
RAG source chunks
Agent workflows
Export history where enabled

Search features:

Natural language search
Keyword search
Hybrid search
Filters by diagram/template/type/date/tag
Similar diagrams
Similar templates
Related RAG sources
Search result snippets
Citation/source links
Open result on canvas
Highlight matching object

32.7 Context-Aware RAG

Talk to Rafa must support context-aware RAG.

RAG behavior:

User selects which sources are allowed
Rafa retrieves only from allowed sources
Rafa cites sources
Rafa separates grounded facts from generated suggestions
Rafa warns when there is insufficient evidence
Rafa can use current diagram as context
Rafa can use selected objects as context
Rafa can answer questions about uploaded documents
Rafa can generate diagrams from RAG answers

32.8 Agentic Modes for Talk to Rafa

Talk to Rafa should support multiple modes.

Ask Mode

Answer questions about the app, diagrams, templates, or documents.

Create Mode

Generate diagrams, workflows, templates, annotations, or documentation.

Edit Mode

Modify selected diagram objects after user approval.

Review Mode

Critique a diagram and return issues, improvements, and health score.

Search Mode

Search across diagrams, templates, and RAG sources.

Teach Mode

Explain how to use a feature step by step.

Agent Mode

Plan and complete multi-step canvas tasks with checkpoints and user approvals.

32.9 Safe Canvas Editing by Rafa

Talk to Rafa may propose canvas actions but must follow safe editing rules.

Rules:

Create version checkpoint before applying AI edits
Show proposed changes before applying major changes
Ask user confirmation before destructive edits
Never delete user content without explicit approval
Allow undo/rollback
Explain what changed
Highlight modified objects
Keep an audit trail of AI edit actions

32.10 Rafa Suggested Prompts

The app should provide suggested prompts such as:

Create a customer onboarding flowchart
Turn this into a swimlane diagram
Explain this diagram
Find missing decision points
Clean up connectors
Add tooltips to every step
Convert this flow into BPMN
Generate a RAG pipeline diagram
Generate an agentic workflow for this process
Search my diagrams for payment workflows
Find templates for product roadmap
Create a presentation from this diagram
Estimate the AI cost for this generation

32.11 Rafa Conversation Persistence

Conversation history should persist by default unless the user deletes it or retention settings apply.

User controls:

Clear current conversation
Delete individual message
Delete Rafa history
Disable history saving
Export conversation
Turn off Learning RAG from conversations

32.12 Rafa Analytics

Track privacy-safe Rafa analytics:

Rafa opened
Prompt submitted
Mode used
Diagram generated
Diagram edited
Search performed
RAG answer generated
AI output accepted
AI output rejected
Estimated token/cost
Failure rate
Average latency

Do not expose private prompt contents to platform owner by default.

32.13 Talk to Rafa MVP

MVP must include:

Talk to Rafa panel
BYOK provider selection
Current diagram context
Selected object context
Prompt-to-flowchart
Prompt-to-swimlane
Diagram explanation
AI cleanup selected area
Semantic search MVP
RAG answer with citations
AI cost estimate
Version checkpoint before edits
Accept/reject proposed changes
Clear chat history

Post-MVP:

Multi-agent Rafa orchestration
Advanced semantic search
Cross-diagram memory
Scenario playback
Screenshot-to-diagram
Voice input later
Rafa workflow automation recipes

33. Six-Sprint Lovable Build Plan and Context-Safe Execution Structure

33.1 Why Six Sprints

The product is large. To prevent Lovable from losing context, the build must be split into six clear sprints. Each sprint should have a narrow mission, explicit non-negotiables, database scope, UI scope, AI scope, security scope, acceptance criteria, and carry-forward context.

Each sprint must start by restating the global rules:

B2C only
No tenant administration
No Lovable AI
No Lovable Gateway
BYOK only
No hardcoded secrets
Joseph is unrevokable platform owner
User data persists by default
Free + ₹499/year Pro
Stripe and Razorpay keys configured later in-app
Build real working features, not mockups

33.2 Sprint 1: Foundation, Auth, Ownership, Persistence and Admin Shell

Sprint Mission

Build the secure B2C foundation of the app.

Must Build

App shell
Responsive layout
Landing page shell
Dashboard shell
Account creation
Email/password login
Magic link login
Google sign-in wiring
Apple sign-in wiring
Microsoft sign-in wiring
Auth provider enable/disable settings
User profile
Password reset
Change password
Session management
Platform admin shell
Seed joseph.ferdinand@falconveritas.com as unrevokable owner
App settings table
Feature flags table
Audit logs table
Persistent user data principle
Retention settings shell with 180-day configurable option

Data Model Scope

profiles
app_settings
auth_provider_settings
feature_flags
audit_logs
retention_policies
deletion_jobs
trash_items

Acceptance Criteria

User can sign up and sign in.
Platform owner exists and cannot be removed or downgraded.
Admin can enable/disable auth providers.
Data persistence rules are visible in app settings.
Retention policy can be configured but should not delete active data by default.
No tenant admin is present.

Lovable Context Reminder

Do not build canvas yet beyond placeholder navigation. Focus on auth, settings, owner, persistence, and admin shell.

33.3 Sprint 2: Canvas Core, Draw.io Micro-Feature Parity and Persistence

Sprint Mission

Build the core diagram editor experience with persistent diagrams and essential draw.io-like editing features.

Must Build

Diagram dashboard
Create diagram
Open diagram
Autosave
Manual save
Version history MVP
Infinite canvas
Page view option
Grid
Snap-to-grid
Guides
Shape panel
Search shapes
Basic flowchart shapes
Connectors
Floating connectors
Fixed connectors MVP
Waypoints MVP
Connector labels
Format panel MVP
Align/distribute
Bring forward/back
Group/ungroup
Lock/unlock
Pages
Frames
Layers MVP
Tags MVP
Links
Tooltips
Metadata MVP
Scratchpad MVP
Custom shape library MVP
Outline/minimap MVP
Keyboard shortcuts MVP
Context menu MVP

Data Model Scope

diagrams
diagram_versions
canvases
canvas_objects
canvas_connections
pages
frames
layers
tags
scratchpad_items
custom_libraries

Acceptance Criteria

User can create and save diagrams.
Diagram persists after logout/login.
User can add shapes and connectors.
User can use basic draw.io-like features.
User can restore earlier version.
User can delete and restore from trash.

Lovable Context Reminder

This sprint must make the canvas usable. Do not build advanced AI yet except placeholders for Talk to Rafa panel.

33.4 Sprint 3: Import, Export, Image Handling, Annotations and Templates

Sprint Mission

Make the platform useful for real users through import/export, templates, image handling, annotations, and sharing MVP.

Must Build

Import .drawio
Import .xml
Import PNG/JPEG/SVG/WebP assets
Mermaid import MVP
CSV/text outline import MVP
SQL-to-ERD import MVP if feasible
Export native project JSON
Export .drawio
Export .xml
Export PNG
Export SVG
Export JPEG
Export WebP
Export PDF
Export HTML
Export public share URL
Export current page/all pages/selection
Export transparent/grid/DPI options
Import/export validation reports
Image asset library
Image crop/resize/rotate/replace
Image annotations
Arrow/shape/text/freehand annotations
Blur/redaction annotation
Template gallery MVP
100+ template seed target
Template copy/clone
Public template preview MVP

Data Model Scope

templates
template_categories
marketplace_items
image_assets
annotations
export_jobs
import_jobs
share_links

Acceptance Criteria

User can import and export common formats.
User can annotate images/diagrams.
User can copy a template into their account.
User can create a public share link.
Export does not include secrets or private RAG contents.

Lovable Context Reminder

Focus on utility and portability. Do not build advanced community marketplace payments yet.

33.5 Sprint 4: BYOK AI, Talk to Rafa, Semantic Search, RAG and Agentic Diagram Modeling

Sprint Mission

Build the AI core using BYOK only, including Talk to Rafa, semantic search, context-aware RAG, prompt-to-diagram, and production-ready agentic AI diagram modeling.

Must Build

BYOK provider setup
Encrypted AI provider keys
Masked key display
Key fingerprinting
Provider test connection
Default provider/model selection
Talk to Rafa panel
Current diagram context awareness
Current selection context awareness
Prompt-to-flowchart
Prompt-to-swimlane
AI explain diagram
AI cleanup selected area
AI add missing connectors
AI add tooltips/annotations
AI cost estimate per generation
Version checkpoint before AI edits
Accept/reject AI proposed changes
Semantic search MVP
RAG source upload
RAG indexing MVP
RAG answer with citations
Learning RAG setting
Agentic AI shape library
Orchestrator/planner nodes
Tool registry nodes
Memory layer nodes
Sub-agent nodes
Human approval gate nodes
Checkpoint store nodes
Guardrail/evaluation nodes
Agentic AI connector types
Agentic AI health score MVP

Data Model Scope

ai_providers
ai_provider_keys
ai_usage_events
ai_cost_estimates
ai_governance_settings
rag_sources
rag_chunks
rag_queries
semantic_index
rafa_conversations
rafa_messages
agent_runs
agent_steps
workflow_nodes
workflow_edges

Acceptance Criteria

User can add their own AI key.
No Lovable AI or Lovable Gateway is used.
Talk to Rafa can create and explain diagrams.
Talk to Rafa can search context and RAG sources.
AI edits require checkpoint and approval.
Agentic diagrams can model orchestrators, planners, tools, memory, sub-agents, approvals, checkpoints, guardrails, and evaluations.

Lovable Context Reminder

This is the most important AI sprint. Keep BYOK and secure secret handling non-negotiable.

33.6 Sprint 5: Subscriptions, Payments, Analytics, Governance, Community and SEO

Sprint Mission

Add monetization, analytics, SEO, community, governance, and admin intelligence.

Must Build

Free plan
₹499/year Pro plan
Stripe configuration screen
Razorpay configuration screen
Test/live mode settings
Webhook secret configuration
Checkout flow
Subscription status sync
Payment events
Revenue dashboard
Product analytics dashboard
User engagement dashboard
DAU/WAU/MAU
Activation funnels
AI activation funnel
Pro conversion funnel
Retention/cohort analytics MVP
Churn-risk indicators MVP
AI usage analytics
AI governance settings
AI cost dashboard
App cost analytics dashboard
SEO metadata management
Sitemap generation
Public template gallery
Template category pages
Public community gallery MVP
Likes/saves/copy count
Report template
Moderation queue

Data Model Scope

subscriptions
payment_events
payment_provider_settings
product_events
user_sessions
engagement_events
user_engagement_scores
user_funnels
cohort_snapshots
retention_snapshots
revenue_metrics_snapshots
cost_metrics_snapshots
community_reports
seo_pages

Acceptance Criteria

User can upgrade to Pro via configured provider.
Platform owner can view revenue and product analytics.
Platform owner can view AI usage/cost analytics.
SEO pages are indexable.
Community template gallery works.
Moderation tools exist.

Lovable Context Reminder

Do not turn this into tenant admin. This is platform owner/admin only for B2C.

33.7 Sprint 6: Plugins, PWA/Offline Roadmap, Polish, Quality, Security and Launch Readiness

Sprint Mission

Prepare the product for launch-quality usage with plugin groundwork, PWA readiness, security, polish, testing, documentation, and performance hardening.

Must Build

PWA installability
Offline fallback page
Cached static assets
Offline roadmap screens/settings
Plugin architecture foundation
Plugin manifest model
Plugin install/disable/uninstall MVP
Plugin permission model
Plugin sandboxing plan
Shape pack plugin MVP if feasible
Import/export plugin hooks later
Security hardening
SVG/HTML sanitization
File validation
Rate limiting
Audit log coverage
Data retention job runner
Pre-deletion notifications
Account export archive MVP
Performance optimization
Canvas loading optimization
Error boundaries
Empty states
Onboarding checklist
Help/tutorial pages
Keyboard shortcut guide
Final UI polish
Mobile/tablet responsive polish
Launch QA checklist

Data Model Scope

plugin_manifests
plugin_installations
plugin_audit_logs
offline_sync_events
notification_events
account_exports

Acceptance Criteria

App is installable as PWA.
Plugin system foundation exists with strict permissions.
User data retention and deletion jobs are safe and auditable.
App feels polished and usable.
Security checks do not reveal secrets.
Launch checklist is complete.

Lovable Context Reminder

This sprint should stabilize, secure, and polish. Avoid adding large new feature areas unless critical.

33.8 Sprint Carry-Forward Context Template

At the end of each sprint, Lovable must generate a short handover note containing:

What was built
What database tables were added
What Supabase policies were added
What routes/pages were added
What components were added
What is incomplete
Known bugs
Security notes
AI/BYOK notes
Data persistence notes
Next sprint TODOs

This handover should be stored in project documentation so the next sprint does not lose context.

34. Final Master Non-Negotiables Checklist

The final implementation must always preserve these rules:

Direct B2C app only
No tenant administration
No enterprise tenant hierarchy
No Lovable AI
No Lovable Gateway
No Lovable-managed AI provider keys
BYOK only
No hardcoded secrets
Secrets encrypted, fingerprinted, masked, and audited
User data persists by default
Auto-delete only through visible configurable retention settings
Default retention option: 180 days configurable by platform owner
Joseph Ferdinand email seeded as unrevokable platform owner
Talk to Rafa is mandatory
Context-aware RAG is mandatory
Semantic search is mandatory
Agentic AI diagram modeling is mandatory
Orchestrators/planners must be explicit diagram objects
Tool registries must be explicit diagram objects
Memory layers must be explicit diagram objects
Sub-agents must be explicit diagram objects
Human approval gates must be explicit diagram objects
Checkpoint stores must be explicit diagram objects
Guardrails/evaluation layers must be explicit diagram objects
Stripe and Razorpay configurable inside app
Free, Pro, and Pro Plus plan structure with Whiteboard restricted to Pro/Pro Plus
SEO/community features included
Engagement, revenue, cost, and AI analytics included
Plugin support roadmap included
PWA/offline/desktop roadmap included
Import/export must match and exceed draw.io
Canvas must be beautiful, modern, fast, and functional

35. Deep Explanation: How Context-Aware RAG Functions in Falcon Flowmira

35.1 Plain-English Overview

Context-aware RAG means the app does not simply search uploaded documents and send random snippets to an LLM. Instead, it understands the user's current working context, retrieves only relevant and permitted knowledge, assembles a grounded context pack, asks the user's selected BYOK model to respond, and then returns an answer or diagram update with citations, confidence indicators, and safe editing controls.

In Falcon Flowmira, context-aware RAG powers Talk to Rafa, semantic search, document-to-diagram generation, diagram explanation, agentic AI workflow modeling, AI cleanup, and knowledge-based template recommendations.

35.2 Why Context-Aware RAG Is Needed

A normal LLM may not know a user's private diagrams, uploaded PDFs, workflow notes, custom templates, prior decisions, or current canvas selection. Context-aware RAG solves this by retrieving relevant information at query time and adding it to the prompt so the model answers from the user's approved knowledge rather than guessing.

This is especially important for:

Converting uploaded SOPs into flowcharts
Explaining a diagram using linked documents
Finding related diagrams across the user's account
Creating diagrams from project-specific requirements
Building agentic workflows from user-provided architecture notes
Answering questions about the current canvas
Reusing learned user diagram style if enabled
Avoiding hallucinated process steps
Showing citations for document-grounded answers

35.3 Context Sources

Context-aware RAG can use multiple context layers, but only when permitted.

Immediate Canvas Context

Current diagram title
Current page/frame
Current viewport
Current selection
Shape labels
Connector labels
Layers
Tags
Tooltips
Comments
Annotations
Metadata
Recent canvas actions

User Knowledge Context

Uploaded PDFs
DOCX files
Markdown files
TXT files
CSV/XLSX files
JSON/YAML files
Saved templates
Scratchpad items
Custom libraries
Prior diagrams if user allows cross-diagram memory
User preferences if learning is enabled

Agentic Workflow Context

Agent nodes
Tool registry nodes
Memory nodes
Guardrail nodes
Human approval gates
Checkpoints
Workflow state
Agent run traces, if history is enabled

Product Context

Current plan: Free or Pro
Enabled features
Available export formats
User's selected AI provider and model, without exposing raw keys
AI budget settings
RAG permissions
Retention settings

35.4 Context-Aware RAG Pipeline

The platform should implement the RAG flow as a clear pipeline.

Step 1: User Intent Detection

Talk to Rafa first identifies what the user is asking.

Example intents:

Ask a question
Generate a flowchart
Convert document to diagram
Search diagrams
Explain current diagram
Improve selected area
Create agentic AI workflow
Validate diagram
Add annotations
Recommend export format

Step 2: Permission and Scope Check

Before retrieval, the app checks:

Which RAG sources the user allowed
Whether Learning RAG is enabled
Whether current diagram context can be used
Whether cross-diagram search is enabled
Whether prompt history can be saved
Whether private documents can be used
Whether the user has enough plan limits

Step 3: Query Rewriting

The user's prompt may be rewritten into better retrieval queries.

Example:

User asks: “Convert this onboarding doc into a swimlane.”

Rewritten retrieval queries:

onboarding process steps
roles and approvals
handoff points
exceptions and edge cases
final completion criteria

Step 4: Hybrid Retrieval

The app retrieves data using a combination of:

Keyword search
Semantic vector search
Metadata filters
Tag filters
Diagram object search
Template search
RAG source search
Recent activity context

Step 5: Reranking

Retrieved chunks are reranked so the most relevant information appears first.

Reranking should prioritize:

Direct relevance to user prompt
Current diagram/page/selection
User-selected RAG sources
Freshness
Source reliability
Exact metadata matches
Prior user preference if enabled

Step 6: Context Pack Assembly

The system assembles a context pack for the BYOK model.

Context pack should include:

User request
Current canvas summary
Selected object summary
Relevant retrieved chunks
Source citations
Allowed actions
Disallowed actions
Desired output format
Cost/budget constraints
Safety instructions
Required confirmation rules

Step 7: BYOK Model Call

The app sends the assembled prompt to the user's selected provider/model only.

Rules:

No Lovable AI
No Lovable Gateway
No hidden provider
No raw secrets in prompt
No private sources unless explicitly allowed
Token/cost estimate recorded

Step 8: Grounded Response Generation

The model returns:

Answer
Diagram plan
Proposed canvas changes
Citations
Assumptions
Missing information
Confidence level
Suggested next steps

Step 9: Verification and Safety Checks

The app validates the result.

Checks include:

Are citations present when RAG was used?
Did the answer invent unsupported claims?
Does the generated diagram contain start/end nodes?
Are there disconnected nodes?
Are destructive edits requested?
Are secrets accidentally included?
Is the cost within user budget?
Does the output violate enabled policies?

Step 10: User Approval and Canvas Application

If the result changes the canvas:

Create version checkpoint
Show proposed changes
Let user accept/reject
Apply non-destructive edits only after approval
Require explicit approval for deletes/replacements
Highlight modified objects
Allow rollback

Step 11: Memory and Analytics Update

Depending on user settings, the app may store:

Query metadata
Token/cost estimate
Feature used
Accepted/rejected output
Updated diagram summary
Learned preference if Learning RAG is enabled

The app must not store private prompt contents in platform-owner analytics by default.

35.5 Context-Aware RAG Output Types

Context-aware RAG should produce:

Plain answer
Source-cited answer
Diagram plan
Flowchart
Swimlane diagram
BPMN draft
Agentic AI workflow
RAG pipeline diagram
Explanation summary
Annotation suggestions
Template recommendations
Export recommendations
Validation report

35.6 Context-Aware RAG Privacy Rules

Required rules:

User chooses which sources are searchable
Private diagrams are never used for public/community search
Secrets are never embedded or retrieved into prompts
RAG source text is not shown to platform owner by default
User can delete RAG sources
User can clear RAG index
User can disable Learning RAG
User can clear learned memory
Citations must identify source document and chunk/page when available
Public templates must not include private RAG sources

35.7 Context-Aware RAG Failure Handling

When retrieval is weak or missing, Talk to Rafa should say:

“I do not have enough context.”
“No matching source was found.”
“Upload or select a source to ground this answer.”
“I can generate a draft from general reasoning, but it will not be source-grounded.”

The UI should clearly distinguish:

Grounded answer
Partially grounded answer
Ungrounded draft
AI suggestion
User-owned source citation

35.8 Context-Aware RAG MVP Requirements

MVP must include:

RAG source upload
RAG source indexing
Semantic search over RAG chunks
Semantic search over diagram titles and object labels
Talk to Rafa access to current diagram context
Talk to Rafa access to selected object context
Source citation display
User-controlled source selection
Clear RAG memory option
RAG answer to diagram generation MVP
Token/cost estimate for RAG queries

Post-MVP:

Hybrid search
Reranking
Graph RAG over diagrams
Cross-diagram memory
Personal style memory
Auto-generated knowledge graph
Structured workflow extraction
Multi-agent retrieval planning
Query decomposition
Retrieval quality scoring

36. Deep Explanation: How Talk to Rafa Works

36.1 Product Definition

Talk to Rafa is the built-in context-aware, agentic AI chatbot for Falcon Flowmira. It helps users create, edit, explain, search, validate, export, and improve diagrams using the user's own LLM keys and approved knowledge sources.

Talk to Rafa must feel like a diagramming partner that understands the canvas, not just a chat box.

36.2 User Experience

Talk to Rafa should appear as:

A right-side chat panel in the editor
A floating command/chat button in pure canvas mode
A search assistant in the dashboard
A help assistant in settings/admin screens
A template discovery assistant in the marketplace

The user should be able to interact with it using:

Natural language prompts
Suggested prompt chips
Right-click canvas actions
Selection-based actions
Slash commands later
Voice input later

36.3 Rafa's Core Loop

Talk to Rafa works through a predictable loop.

1. Understand

Rafa reads the user's request and determines intent.

Examples:

Create a diagram
Edit selected area
Search knowledge
Explain diagram
Review diagram
Convert diagram type
Build agentic workflow
Recommend template
Recommend export

2. Gather Context

Rafa gathers only allowed context:

Current canvas
Current selection
Visible viewport
Diagram metadata
Tags/layers/tooltips/comments
Selected RAG sources
User templates
Semantic search results
Product feature context

3. Plan

Rafa creates an internal action plan.

Example plan:

Extract actors from uploaded document
Identify process steps
Detect decision points
Create swimlane structure
Add connectors
Apply layout
Add tooltips and citations
Show preview to user

4. Estimate Cost

For AI operations, Rafa should show or log:

Estimated input tokens
Estimated output tokens
Estimated cost
Selected model/provider
Budget warning if needed

5. Propose

Before changing the canvas, Rafa should show:

Summary of changes
Objects to be created
Objects to be modified
Objects to be deleted, if any
Required confirmation
Sources used

6. Execute Safely

If the user approves:

Create checkpoint
Apply canvas operations
Highlight changes
Save version
Log AI edit metadata

7. Explain and Continue

Rafa explains what changed and suggests next actions.

Examples:

“I created a 7-step onboarding flow.”
“I added decision nodes where approvals occur.”
“I found two missing exception paths.”
“Would you like me to convert this into BPMN?”

36.4 Rafa Modes

Ask Mode

Answer user questions about diagrams, features, templates, or documents.

Create Mode

Generate a new diagram, template, workflow, RAG pipeline, or agentic AI architecture.

Edit Mode

Modify selected diagram regions with user approval.

Review Mode

Audit diagrams for readability, missing nodes, errors, bottlenecks, guardrail gaps, RAG grounding, and agentic workflow completeness.

Search Mode

Semantic search across diagrams, templates, RAG sources, comments, tags, and metadata.

Teach Mode

Explain how to use the app step-by-step.

Agent Mode

Complete multi-step tasks with checkpoints, todos, approvals, and rollback.

36.5 Rafa Canvas Tools

Rafa should have tool access through safe app APIs, not raw database or secret access.

Allowed tools:

Read current canvas summary
Read selected objects
Search diagram objects
Search templates
Search RAG sources
Create shape
Create connector
Edit label
Add tooltip
Add annotation
Add tag
Create layer
Create frame
Apply layout
Apply style
Create version checkpoint
Export diagram
Generate validation report
Estimate AI cost

Restricted tools:

Delete object requires explicit approval
Replace diagram requires explicit approval
Publish public template requires explicit approval
Use RAG source requires source permission
Use AI provider requires user-selected BYOK provider
Access secrets is never allowed

36.6 Rafa and Agentic AI Orchestration

For complex tasks, Rafa should orchestrate specialized internal agents.

Recommended internal agents:

Intent classifier
Context retriever
RAG planner
Diagram planner
Canvas editor
Layout optimizer
Style optimizer
Validator
Cost estimator
Safety reviewer
Export advisor
Documentation writer

Example flow:

User asks Rafa: “Build an agentic RAG workflow from this document.”
Intent classifier detects “agentic workflow generation.”
Context retriever retrieves uploaded document chunks.
RAG planner extracts sources, roles, tools, memory, and guardrails.
Diagram planner creates node/edge plan.
Canvas editor creates orchestrator, tool registry, memory, retriever, sub-agent, approval, checkpoint, and guardrail nodes.
Layout optimizer organizes the workflow.
Validator checks missing error paths and guardrails.
Cost estimator estimates generation cost.
Rafa shows preview and asks user to apply changes.

36.7 Rafa Safety Requirements

Talk to Rafa must always follow these rules:

BYOK only
No Lovable AI
No Lovable Gateway
No raw secret access
No destructive edits without confirmation
Version checkpoint before canvas modifications
Clear citations for RAG answers
Clear distinction between facts and suggestions
User can clear conversation history
User can disable Learning RAG
User can disable Rafa history
Platform owner cannot view private prompts by default

36.8 Rafa UI Requirements

Required UI elements:

Chat input
Mode selector
Provider/model indicator
Cost estimate indicator
Context chips showing active context
Source selector
Citation drawer
Proposed changes preview
Accept/reject buttons
Undo/rollback button
Suggested prompts
Search results panel
Memory settings shortcut
Clear conversation button

36.9 Rafa Example User Flows

Flow 1: Create a Flowchart

User: “Create a customer onboarding flowchart with payment verification.”

Rafa:

Creates process steps
Adds decision nodes
Adds connectors
Applies clean layout
Shows preview
Asks to apply

Flow 2: Convert Document to Swimlane

User uploads SOP and asks: “Turn this into a swimlane.”

Rafa:

Retrieves SOP chunks
Extracts roles and steps
Builds lanes
Adds citations in tooltips
Shows missing steps/questions

Flow 3: Review Agentic Workflow

User selects an agentic workflow and asks: “Is this production-ready?”

Rafa checks:

Orchestrator present
Tool registry present
Memory layer present
Guardrails present
Checkpoints present
Error paths present
Human approval gates present
Cost budget present
Audit logging present

Then Rafa returns a health score and suggested fixes.

Flow 4: Semantic Search

User: “Find my diagrams related to refund approval.”

Rafa searches:

Diagram names
Shape labels
Connector text
Tags
Comments
RAG source titles
Template names

Then Rafa shows ranked results and opens the selected result on canvas.

36.10 Rafa MVP Acceptance Criteria

Talk to Rafa MVP is complete when:

User can open Talk to Rafa in the editor
User can choose their BYOK provider/model
Rafa can read current diagram summary
Rafa can understand selected objects
Rafa can generate a flowchart
Rafa can generate a swimlane
Rafa can explain the current diagram
Rafa can run semantic search MVP
Rafa can answer from RAG with citations
Rafa can propose canvas edits
User can accept/reject edits
A version checkpoint is created before edits
Rafa estimates AI usage/cost
User can clear Rafa conversation history

37. Updated Naming Rule: Talk to Rafa

All references to the AI chatbot feature must use the name Talk to Rafa.

Use only “Talk to Rafa” anywhere in the product UI, database labels shown to users, help documentation, onboarding, prompts, admin settings, SEO pages, or marketplace templates.

Internal database table names may use rebekka_ prefixes where needed, such as:

rafa_conversations
rafa_messages
rafa_actions
rafa_context_events
rafa_search_events

The official assistant feature name is:

Talk to Rafa

38. Whiteboard Mode Requirements: Pro and Pro Plus Only

38.1 Product Rule

Whiteboard Mode is a premium feature and must be available only to Pro and Pro Plus users.

Free users must not be able to create, edit, export, duplicate, copy, or convert whiteboards. Free users may only view marketing previews or public template previews if the platform owner enables this for growth and conversion.

38.2 Whiteboard Branding

Whiteboard Mode belongs to:

Falcon Flowmira AI canvas for diagrams, workflows, and knowledge. Powered by Talk to Rafa.

38.3 Access Control by Plan

Free Plan

Free users:

Cannot create a new whiteboard
Cannot edit a whiteboard
Cannot export a whiteboard
Cannot copy a whiteboard template into their account
Cannot use Talk to Rafa for whiteboard generation
Cannot use whiteboard-to-diagram conversion
Cannot use voting, timer, facilitation, workshop, annotations, or advanced image handling in whiteboards
Can view public whiteboard template previews only if enabled
Should see clear upgrade prompts for Pro or Pro Plus

Pro Plan: ₹499/year

Pro users can use Whiteboard Mode with standard limits:

Create whiteboards
Edit whiteboards
Add sticky notes
Add text
Add shapes
Add connectors and arrows
Add frames
Use freehand drawing
Upload and place images
Use basic image crop, resize, rotate, replace
Use basic annotations
Use basic whiteboard templates
Export PNG, SVG, PDF, JPEG, WebP
Save and reopen whiteboards
Use version history
Delete and restore whiteboards from trash
Use Talk to Rafa to summarize a whiteboard using BYOK
Use Talk to Rafa to organize sticky notes using BYOK
Use Talk to Rafa to convert selected whiteboard content into a flowchart draft using BYOK
Create public/private share links if enabled by platform owner

Pro Plus Plan: Price Configurable Later

Pro Plus users get advanced Whiteboard Mode:

Everything in Pro
Higher whiteboard limits
Higher object limits
Higher file upload limits
Larger image asset limits
Advanced annotations
Advanced facilitation mode
Voting
Dot voting
Timer
Focus mode
Workshop mode
Advanced whiteboard templates
Advanced Talk to Rafa whiteboard generation
Context-aware RAG whiteboard generation with citations
Whiteboard-to-swimlane conversion
Whiteboard-to-BPMN conversion
Whiteboard-to-agentic-workflow conversion
Whiteboard-to-RAG-pipeline conversion
Whiteboard-to-customer-journey conversion
Whiteboard-to-architecture-diagram conversion
Workshop summary export when implemented
DOCX/PPTX/CSV/XLSX whiteboard export when implemented
Community whiteboard template publishing if enabled
Priority access to future premium whiteboard templates and plugins

38.4 Whiteboard Upgrade Flow

When a Free user attempts to access Whiteboard Mode, show an upgrade screen.

Upgrade screen should include:

Whiteboard feature preview
Pro benefits
Pro Plus benefits
Upgrade to Pro button
Upgrade to Pro Plus button if plan is enabled
Pricing display controlled by platform owner/admin
Reminder that AI features use BYOK only

38.5 Whiteboard Feature Gating Requirements

The app must enforce feature gating on both frontend and backend.

Required enforcement:

UI gating
Route gating
API gating
Database policy gating where applicable
Export action gating
Template copy gating
Talk to Rafa whiteboard action gating
Whiteboard community publishing gating

Never rely only on hidden buttons in the UI. Backend checks must prevent unauthorized Free users from creating or modifying whiteboard resources.

38.6 Whiteboard Database Plan Fields

Whiteboard-related tables should support plan-aware limits through app settings and subscription checks.

Recommended fields/settings:

whiteboard_feature_enabled
whiteboard_required_plan: Pro or Pro Plus
free_whiteboard_preview_enabled
pro_whiteboard_limit
pro_plus_whiteboard_limit
pro_whiteboard_object_limit
pro_plus_whiteboard_object_limit
pro_image_upload_limit_mb
pro_plus_image_upload_limit_mb
pro_export_formats_enabled
pro_plus_export_formats_enabled

38.7 Whiteboard Analytics by Plan

Track:

Free users who clicked Whiteboard Mode
Free users shown upgrade modal
Free-to-Pro conversion from Whiteboard Mode
Free-to-Pro Plus conversion from Whiteboard Mode
Pro whiteboards created
Pro Plus whiteboards created
Whiteboard-to-diagram conversions by plan
Talk to Rafa whiteboard prompts by plan
Whiteboard exports by plan
Whiteboard template copies by plan

Do not expose private whiteboard content in platform analytics by default.

38.8 Sprint Placement Update

Whiteboard Mode should be introduced only after subscription gating is reliable.

Recommended sprint placement:

Sprint 2: Add placeholder navigation only, locked for Free users
Sprint 3: Build Pro-gated whiteboard canvas, sticky notes, frames, images, annotations, and export
Sprint 4: Build Pro/Pro Plus-gated Talk to Rafa whiteboard intelligence and RAG conversion
Sprint 5: Add payment analytics, upgrade funnels, plan enforcement, and Pro Plus controls
Sprint 6: Polish, PWA/offline support, performance, security, and export hardening

38.9 Lovable Instruction Addendum

When building Whiteboard Mode:

Restrict Whiteboard Mode to Pro and Pro Plus plans only.
Free users must not create, edit, export, copy, or convert whiteboards.
Backend must enforce access control.
Pro users get standard whiteboard tools.
Pro Plus users get advanced facilitation, advanced AI whiteboard generation, advanced conversions, and higher limits.
Use Talk to Rafa for all AI whiteboard capabilities.
Talk to Rafa must use BYOK only.
No Lovable AI or Lovable Gateway may be used.

39. Pro Plus Feature Model, Onboarding Gating and Free-to-Pro Upgrade Flow

39.1 Purpose

Falcon Flowmira must clearly separate Free, Pro, and Pro Plus experiences so users understand what they can do, why premium features are valuable, and how to upgrade without friction.

The product must avoid confusing users with locked features that appear broken. Every gated feature must explain:

What the feature does
Why it is premium
Which plan unlocks it
What the user gets after upgrading
Whether AI usage requires BYOK
Whether the action is available in Pro or only Pro Plus

39.2 Plan Philosophy

Free Plan

Free is for discovery, basic diagramming, template browsing, and conversion into paid plans.

Free should help users understand the value of Falcon Flowmira, but it should not include premium productivity systems such as Whiteboard Mode, advanced Talk to Rafa workflows, advanced RAG, or advanced exports.

Pro Plan: ₹499/year

Pro is the main affordable paid plan for individual users.

Pro should unlock the core premium experience:

Full diagramming experience
Standard Whiteboard Mode
Standard Talk to Rafa workflows using BYOK
Standard RAG and semantic search
Standard exports
Version history
Template cloning
Standard analytics for personal usage

Pro Plus Plan: Price Configurable Later

Pro Plus is the advanced creator/power-user plan.

Pro Plus should unlock higher limits, advanced whiteboarding, advanced AI workflows, advanced RAG, advanced conversions, advanced workshop tools, and future premium capabilities.

Pro Plus must be configurable by the platform owner/admin, including:

Plan name
Description
Price
Billing interval
Feature list
Enabled/disabled status
Stripe price ID
Razorpay plan ID
Trial settings if added later

39.3 How Pro Plus Features Work

Pro Plus features are advanced premium capabilities that sit above the Pro plan. They should be designed as power-user accelerators, not basic requirements.

Pro Plus Feature Categories

Pro Plus should include advanced features across these areas:

Advanced Whiteboard

Larger number of whiteboards
Higher object limits per whiteboard
Larger image upload limits
Advanced annotations
Dot voting
Timer
Focus mode
Workshop mode
Advanced facilitation tools
Advanced whiteboard templates
Workshop summary exports when implemented

Advanced Talk to Rafa

Advanced Talk to Rafa whiteboard generation
Multi-step agentic workflows
Advanced canvas editing proposals
Advanced diagram review
Advanced AI cleanup
Advanced AI diagram health scoring
Advanced AI workflow repair proposals
Advanced agentic AI diagram validation

Advanced RAG and Semantic Search

Higher RAG source limits
Larger document upload limits
More indexed chunks
Advanced context-aware RAG
Cross-diagram semantic search
Advanced source filtering
Advanced citation views
Learning RAG expansion
Future Graph RAG support

Advanced Conversion Tools

Whiteboard-to-swimlane conversion
Whiteboard-to-BPMN conversion
Whiteboard-to-agentic-workflow conversion
Whiteboard-to-RAG-pipeline conversion
Whiteboard-to-customer-journey conversion
Whiteboard-to-architecture-diagram conversion
Screenshot-to-editable-diagram roadmap features
Advanced document-to-diagram extraction

Advanced Export and Reporting

Advanced PDF export
Advanced multi-page exports
DOCX report export when implemented
PPTX export when implemented
CSV/XLSX whiteboard summary export when implemented
ZIP project bundle export
Advanced export presets
Higher export size limits

Future Premium Ecosystem

Premium whiteboard templates
Premium agentic AI templates
Premium RAG templates
Premium plugins
Premium shape packs
Advanced creator tools
Community publishing controls if enabled

39.4 Pro Plus Backend Behavior

The backend must treat Pro Plus as a real subscription tier, not a UI-only label.

Required backend checks:

Check active subscription plan before allowing Pro Plus actions
Enforce Pro Plus object limits
Enforce Pro Plus upload limits
Enforce Pro Plus export limits
Enforce Pro Plus AI workflow limits
Enforce Pro Plus RAG limits
Enforce Pro Plus community publishing if applicable
Return structured upgrade-required errors for unauthorized users

Recommended response pattern:

{
  "error": "upgrade_required",
  "required_plan": "pro_plus",
  "current_plan": "free",
  "feature": "advanced_whiteboard_voting",
  "message": "This feature requires Pro Plus."
}

39.5 Feature Gate Types

Falcon Flowmira should use multiple types of gates depending on the user journey.

Hard Gate

Blocks access entirely.

Use for:

Creating whiteboards on Free
Advanced Pro Plus-only exports
Advanced whiteboard facilitation tools
Advanced Talk to Rafa workflows

Soft Gate

Shows feature preview but requires upgrade to use.

Use for:

Public whiteboard template previews
Premium template previews
Pro Plus feature examples
Sample AI workflow diagrams

Usage Limit Gate

Allows use until limit is reached.

Use for:

Number of diagrams
Number of RAG sources
Number of exports
Number of AI runs if app-side limits are set
Whiteboard object limits for Pro vs Pro Plus

Upgrade CTA Gate

Prompts upgrade at a high-intent moment.

Use when:

User clicks “New Whiteboard” on Free
User tries to export advanced format
User tries to use Talk to Rafa advanced conversion
User reaches plan limit
User previews a Pro Plus template

39.6 How Gating Affects Onboarding

Gating must be integrated into onboarding carefully. The goal is to educate and convert users, not frustrate them.

Onboarding Principle

The onboarding flow should personalize the user's first experience based on intended use.

Ask the user what they want to do:

Create diagrams
Build workflows
Use whiteboard
Use AI with Talk to Rafa
Upload documents for RAG
Browse templates
Import draw.io/Visio files

Based on this answer, onboarding should route them appropriately.

39.7 Free User Onboarding

Free users should see an onboarding path that emphasizes available value while previewing locked premium capabilities.

Free Onboarding Steps

Welcome to Falcon Flowmira
Choose goal: diagram, workflow, template, import, AI, whiteboard
If user chooses a Free-supported feature, continue normally
If user chooses Whiteboard, advanced AI, advanced RAG, or premium export, show a premium preview
Explain the required plan
Offer upgrade to Pro or Pro Plus
Let the user continue with a Free alternative if available

Free User Whiteboard Onboarding

If a Free user selects Whiteboard during onboarding:

Show Whiteboard preview screen
Explain that Whiteboard Mode is available in Pro and Pro Plus only
Show Pro benefits
Show Pro Plus benefits
Provide “Upgrade to Pro” button
Provide “Compare Pro and Pro Plus” link
Provide “Continue with Diagram Canvas” fallback

Do not silently hide Whiteboard Mode from Free users. It should be visible as a premium feature but locked.

39.8 Pro User Onboarding

Pro users should be onboarded into core premium workflows.

Pro onboarding should include:

Create first diagram
Create first whiteboard
Add own AI provider key
Try Talk to Rafa
Upload first RAG source
Copy a premium template
Export a diagram

For Pro users, Pro Plus features should appear as advanced optional upgrades, not blocking core workflows.

Example:

Pro can create a whiteboard
Pro can use basic annotations
Pro sees advanced voting/timer/facilitation as Pro Plus features

39.9 Pro Plus User Onboarding

Pro Plus users should be onboarded into advanced power workflows.

Pro Plus onboarding should include:

Create advanced whiteboard
Try facilitation tools
Start voting session
Use advanced Talk to Rafa whiteboard generation
Convert whiteboard into swimlane/BPMN/agentic workflow
Use advanced RAG with citations
Export advanced report when implemented
Explore Pro Plus templates and plugins

39.10 Upgrade Flow From Free to Pro

The Free-to-Pro upgrade flow must be simple, transparent, and conversion-focused.

Entry Points

Free users should be able to upgrade from:

Pricing page
Dashboard upgrade banner
New Whiteboard button
Premium template preview
Export modal
Talk to Rafa advanced prompt
RAG limit reached screen
Diagram limit reached screen
Account settings
Onboarding premium preview

Upgrade Flow Steps

User clicks a Pro-gated feature or Upgrade button
App shows upgrade modal or pricing page
User sees Pro plan at ₹499/year
User sees what will unlock immediately
User selects payment provider if both are enabled, or app uses configured default
User proceeds to Stripe or Razorpay checkout
Payment completes
Webhook confirms subscription
App updates subscription status
User returns to exact feature they tried to use
App shows success message
User can immediately use Pro feature

Upgrade Success Message

Suggested copy:

“Welcome to Pro. Whiteboard Mode, Talk to Rafa premium workflows, advanced exports, templates, RAG, and version history are now unlocked.”

Return-to-Feature Requirement

If the user upgraded from a locked feature, send them back to that exact feature after payment.

Examples:

If user clicked New Whiteboard, open new whiteboard after upgrade
If user clicked premium export, reopen export modal after upgrade
If user clicked Talk to Rafa premium conversion, reopen that prompt flow after upgrade
If user clicked premium template, copy the template after upgrade confirmation

39.11 Upgrade Flow From Free to Pro Plus

If Pro Plus is enabled, Free users may upgrade straight to Pro Plus.

Flow:

User clicks Pro Plus-gated feature
App shows Pro vs Pro Plus comparison
User selects Pro Plus
Checkout opens
Webhook confirms subscription
User returns to Pro Plus feature
App unlocks advanced feature

Pro Plus should be clearly positioned as advanced and optional.

39.12 Upgrade Flow From Pro to Pro Plus

Pro users should be able to upgrade to Pro Plus from:

Advanced Whiteboard tools
Voting feature
Workshop mode
Advanced Talk to Rafa conversion
Advanced RAG limits
Advanced export modal
Plan settings

Flow:

Pro user clicks Pro Plus feature
App shows Pro Plus upgrade modal
App explains additional benefits
User confirms upgrade
Payment provider handles proration if supported/configured
Webhook updates plan
App unlocks Pro Plus feature

39.13 Downgrade Behavior

If a user downgrades from Pro Plus to Pro or from Pro to Free:

Do not delete existing data immediately
Preserve whiteboards and diagrams
Restrict editing/exporting of features no longer available
Allow user to view existing locked content where appropriate
Show upgrade prompt to regain editing access
Respect retention policy only after visible rules and notifications

For example:

Pro Plus user has advanced whiteboard with voting data
User downgrades to Pro
Whiteboard remains visible/editable with Pro-supported tools
Pro Plus-only voting analytics become read-only or locked

39.14 Upgrade Analytics

Track upgrade analytics:

Upgrade modal viewed
Pricing page viewed
Feature gate triggered
Feature that triggered upgrade
Plan selected
Checkout started
Checkout completed
Payment failed
Upgrade success
User returned to feature after upgrade
Free-to-Pro conversion
Free-to-Pro Plus conversion
Pro-to-Pro Plus conversion
Whiteboard-driven upgrade conversion
Talk to Rafa-driven upgrade conversion
Export-driven upgrade conversion

Do not expose private content in analytics.

39.15 Upgrade UX Copy Examples

Free User Clicks New Whiteboard

“Whiteboard Mode is available in Pro and Pro Plus. Upgrade to create brainstorming boards, sticky-note workshops, workshop templates, and convert ideas into diagrams with Talk to Rafa.”

Buttons:

Upgrade to Pro
Compare Pro Plus
Continue with Diagram Canvas

Pro User Clicks Voting

“Voting is a Pro Plus facilitation tool. Upgrade to Pro Plus to run workshops, dot voting, timers, advanced whiteboard sessions, and advanced Talk to Rafa conversions.”

Buttons:

Upgrade to Pro Plus
Continue without voting

Free User Clicks Advanced Export

“Advanced exports are included in Pro. Upgrade to export professional PDF, SVG, WebP, and additional formats as they become available.”

Buttons:

Upgrade to Pro
Back to basic export

39.16 Lovable Build Addendum: Gating and Upgrade Flow

Lovable must implement plan gating as a real application capability.

Mandatory requirements:

Build a central feature-gating service/helper
Enforce gates on frontend and backend
Add required_plan metadata for premium actions
Add upgrade modals
Add pricing page with Free, Pro, and Pro Plus
Keep Pro price as ₹499/year
Make Pro Plus price configurable by platform owner/admin
Add Stripe and Razorpay checkout hooks
Add webhook-based subscription status sync
Return user to the feature that triggered upgrade
Preserve user data on downgrade
Never delete user data simply because of downgrade
Track upgrade analytics without private content exposure
Keep Whiteboard Mode restricted to Pro and Pro Plus only
Keep advanced Whiteboard features restricted to Pro Plus where specified

20. Final Product Direction

The product should become:

Falcon Flowmira, a premium B2C AI canvas platform where consumers, creators, students, consultants, developers, and founders can design diagrams, workflows, knowledge systems, and AI-powered visual documents using their own LLM keys, with full cost transparency, governance, analytics, and secure secret management.

Falcon Flowmira Ultimate Master PRD v10

Full Comprehensive Lovable Build Blueprint with Six Sprints, Talk to Rafa, Agentic AI, RAG, Semantic Search, Import/Export, Community, Analytics, Plugins and Data Persistence

1. Product Vision

2. Explicit Non-Scope: No Tenant Administration

3. Authentication and Account Management

Supported Account Options

Provider Enable/Disable Controls

User Account Features

Recommended Consumer Security Features

4. Subscription Model

Free Plan

Pro Plan

Pro Plus Plan

Payment Providers

5. Strict AI Provider and Secret Policy

Mandatory AI Policy

BYOK Only

Secure Secret Storage

Secret Metadata

6. AI Usage Cost Management

User-Level AI Usage Dashboard

AI Cost Estimation

AI Budgets

AI Cost Alerts

Platform-Level AI Analytics

7. AI Governance

User AI Governance

Platform AI Governance

AI Audit Logs

AI Safety and Reliability

8. App People Analytics

User Acquisition Analytics

Activation Analytics

Engagement Analytics

Retention Analytics

User Segmentation

9. Revenue Analytics

Revenue Dashboard Metrics

Subscription Analytics

Unit Economics

10. App Cost Analytics

Cost Categories

Cost Dashboard

Cost Alerts

11. Growth, Marketing and Virality Features

Sharing Features

Referral Features

Community Features

SEO Features

12. Canvas and Diagram Features

Pure Canvas Mode

Diagram Types

Compatibility

13. Templates and Marketplace

Built-In Templates

Marketplace Functions

Marketplace Analytics

14. Platform Owner Administration

Permanent Owner

Platform Admin Console Modules

15. Analytics Data Privacy

16. Database Modules

17. MVP Scope v2

Must Build in MVP

Post-MVP

18. Lovable Build Instructions

19. Definition of Success

21. SEO and Community Growth Features

21.1 SEO Strategy

Required SEO Pages

SEO Technical Requirements

SEO Content Requirements

Programmatic SEO

SEO Analytics

21.2 Community Features

Public Community Gallery

Template Discovery Features

Creator Profiles

Template Publishing

Community Moderation