---

🎯 Overview: From Code to Intelligent Design & Decisions

FlowSquad is an AI-powered SDLC intelligence platform that transforms how development teams create requirements, designs, and test cases. Instead of starting from scratch or using generic AI tools, FlowSquad learns from YOUR actual codebase to generate context-aware documentation.

The Problem We Solve

Traditional SDLC Documentation Challenges:

• ❌ Vague Requirements: "Add user login" → But what about password reset? MFA? Session management?
• ❌ Manual Design Docs: Hours spent creating technical designs that become outdated immediately
• ❌ Copy-Paste Test Cases: Rewriting the same test scenarios for every new feature
• ❌ No Quality Visibility: Is this release better or worse than the last? No one knows.
• ❌ Generic AI Guesses: ChatGPT/Copilot don't understand YOUR code patterns and conventions

FlowSquad's Approach:

• ✅ Codebase-Aware AI: Vector database learns YOUR code patterns, frameworks, and conventions
• ✅ Complete SDLC Pipeline: Code Analysis → Requirements → Design → Test Cases → Quality Scoring
• ✅ Context-Driven Generation: Every output considers your existing codebase structure
• ✅ Quality Gates: Completeness scores (0-100), risk analysis, automated recommendations
• ✅ Time Savings: 80% reduction in SDLC documentation time

How It Works

1. Analyze Your Code
   └─> Parse any language (Python, Java, JavaScript, etc.)
   └─> Extract modules, dependencies, complexity, patterns
   └─> Store embeddings in vector database

2. Refine Requirements
   └─> Transform vague ideas into complete requirements
   └─> AI adds acceptance criteria, dependencies, risks
   └─> Completeness scoring (0-100) ensures quality

3. Generate Designs
   └─> Auto-create technical design documents
   └─> Architecture diagrams, API contracts, database schemas
   └─> Context-aware: knows your existing tech stack

4. Create Test Cases
   └─> Learn from your existing test patterns
   └─> Generate new test cases that match your style
   └─> Automation script analysis (Selenium, Pytest, Cypress, etc.)

5. Score Quality
   └─> Quality metrics (test coverage, automation %, complexity)
   └─> Risk analysis (low/medium/high per module)
   └─> Prioritized recommendations for improvement

Who Should Use FlowSquad?

✅ Perfect For:

• Product Managers: Transform vague ideas into complete user stories with acceptance criteria
• Business Analysts: Document requirements with AI-powered refinement and completeness scoring
• Software Architects: Auto-generate technical designs aligned with existing architecture
• Development teams: 5-500 developers building features faster with less documentation overhead
• Engineering managers: Gain visibility into quality metrics and technical debt
• QA teams: Automate test case creation and track automation coverage
• System integrators: Handle repetitive patterns with codebase-aware AI
• Regulated industries: Finance, healthcare, government needing comprehensive documentation

---

🚀 Installation

FlowSquad Evaluation is available in two deployment options:

• Windows Portable - No installation required, double-click to run
• Docker Container - Cross-platform deployment for Linux, macOS, Windows (WSL/Docker Desktop), and servers

Installation (Windows Portable)

FlowSquad Evaluation is distributed as a portable package - no installation required!

Windows:

1. Extract the FlowSquad-Portable-v1.0.zip to a folder (e.g., C:\FlowSquad)
   • Right-click → Extract All → Choose location
   • ⚠️ Do NOT extract to temporary folders (Downloads, Temp, Desktop)
   • ⚠️ Avoid protected folders (Program Files, Windows, System32) - permission issues
   • ✅ Best locations: C:\FlowSquad, D:\FlowSquad, or any user-writable directory
2. Run FlowSquad.exe from the extracted folder
   • Double-click FlowSquad.exe
   • First launch may take 10-15 seconds (initializing Python environment)
   • ✅ Windows Defender/Firewall: Allow access when prompted
3. Access FlowSquad in your browser
   • Browser automatically opens to http://localhost:5000
   • If browser doesn't open, manually navigate to http://localhost:5000
   • ✅ Bookmark this URL for easy access
4. Complete the setup wizard on first launch

Data Location:

• All data stored in your local AppData folder:
  • Location: C:\Users\[YourUsername]\AppData\Local\FlowSquad\
  • flowsquad.db - Database file
  • vector_db/ - Code analysis embeddings
  • uploaded_documents/ - Generated reports
  • analysis_output/ - Analysis results
• Backup: Copy the AppData\Local\FlowSquad folder to preserve all data

System Requirements:

• Windows 10/11 (64-bit)
• 4 GB RAM minimum, 8 GB recommended
• 2 GB free disk space (more for large codebases)
• Internet connection (for LLM API access)

Installation (Docker - Linux/macOS/WSL/Server)

FlowSquad is available as a Docker container for cross-platform deployment!

Prerequisites:

• Docker installed (Get Docker)
• Docker Compose (included with Docker Desktop)
• 4 GB RAM minimum, 8 GB recommended
• Internet connection (for LLM API access)

Quick Start:

1. Extract the FlowSquad-Docker-v1.4.zip to a folder
2. Deploy using the deployment script:

   Windows (PowerShell):

   .\deploy.ps1

   Linux/Mac:

   chmod +x deploy.sh
   ./deploy.sh

3. Access FlowSquad in your browser
   • Navigate to http://localhost:5000
   • First launch may take 15-20 seconds (container initialization)
4. Complete the setup wizard on first launch

Managing the Container:

# Windows PowerShell
.\deploy.ps1 -Status    # Check if running
.\deploy.ps1 -Logs      # View logs
.\deploy.ps1 -Stop      # Stop container
.\deploy.ps1            # Start (run again)

# Linux/Mac
./deploy.sh status      # Check if running
./deploy.sh logs        # View logs  
./deploy.sh stop        # Stop container
./deploy.sh             # Start (run again)

Data Persistence:

• All data stored in Docker volume: flowsquad-data
• Survives container restarts and updates
• Location: /data inside container

Backup:

# Backup data volume (creates flowsquad-backup.tar.gz)
docker run --rm -v flowsquad-data:/data -v $(pwd):/backup alpine tar czf /backup/flowsquad-backup.tar.gz /data

# Restore data volume from backup
docker run --rm -v flowsquad-data:/data -v $(pwd):/backup alpine tar xzf /backup/flowsquad-backup.tar.gz -C /

---

⚙️ First Time Setup

The setup wizard guides you through configuration:

Step 1: Select AI Provider

• GitHub Models pre-selected as default (recommended for evaluation)
  • 30-day free trial - perfect for testing FlowSquad
  • Access to GPT-4o, GPT-4o-mini, and embeddings
  • Requires GitHub account and Personal Access Token
• Alternative providers:
  • OpenAI - GPT-4, GPT-3.5 Turbo, text-embedding-3-small (paid plans)
  • Anthropic - Claude 3.5 Sonnet, Claude 3 Opus (advanced reasoning)

Step 2: Configure Models & API

• Dynamic Instructions: Provider-specific setup steps appear automatically
• Get Your API Key:
  • GitHub Models: https://github.com/settings/tokens (create Personal Access Token)
  • OpenAI: https://platform.openai.com/api-keys
  • Anthropic: https://console.anthropic.com/settings/keys
• Test API Key: Click "Test Key" to validate access and fetch available models
• Select Models: Choose from models your API key can actually access
• Set token limits (max tokens per request) and daily limits for cost control

Step 3: Optional LDAP Security (Recommended for Enterprise)

• Enable LDAP for secure authentication against Active Directory
• Benefits: Centralized user management, password policies, audit trails
• Configure LDAP server, port, bind credentials, and search base
• Map LDAP groups to FlowSquad roles
• Otherwise, use default admin/admin login (change password for security)

Step 4: Review & Complete

• Verify settings and click "Complete Setup"

Default Login Credentials:

• Username: admin
• Password: admin

---

📦 Working with Products

Creating a Product

Option 1: Try Demo (Recommended for First-Time Users)

1. Click "🎬 Try Demo" button on dashboard
2. Real-Time Progress Tracking: Watch as FlowSquad builds your demo with detailed step-by-step progress
3. Completion Message: "🎉 FlowSquad at your service!"
   • Next Step: Load sample requirements from demo-products/ecommerce-platform/quick-requirements.txt
   • Go to Requirements tab → Paste text → Click "Refine Requirements"
4. Demo includes real analysis (not static data):
   • 3 codebases analyzed with AI semantic analysis
   • Backend API: Flask REST API (Python)
   • Frontend: React TypeScript application
   • Payment Service: Node.js microservice
   • 15 test cases loaded in VectorDB for semantic search
5. Try the complete workflow:
   • Analyze Tab: View analyzed codebases and their intelligence
   • Requirements Tab: Load sample requirements and refine with AI
   • Design Tab: Generate technical designs from refined requirements
   • Test Cases Tab: View loaded test cases and generate new ones
   • QA Automation Tab: Upload automation scripts
   • Quality Score Tab: Calculate quality score

Option 2: Create New Product

1. Click "Add Product" from dashboard
2. Enter product name and description
3. Product admin is automatically set to "admin" (or select LDAP users if configured)
4. Click "Create Product"
5. Start adding codebases and requirements

---

🔧 Main Features

1. Code Analysis

Purpose: Understand your codebase structure, complexity, and language metrics

How to use:

1. Go to product dashboard → Code Analysis tab
2. Enter Git repository URL (or upload ZIP)
3. Provide credentials if private repository
4. Click "Analyze Codebase"
5. View comprehensive results:
   • Language Metrics: Lines of code per language
   • Language Distribution: Percentage breakdown and visual charts
   • Complexity Analysis: Cyclomatic complexity, cognitive complexity
   • Code Structure: Entry points, dependencies, architecture layers
   • Technology Stack: Frameworks and libraries detected
   • File Statistics: Total files, directories, module count
6. Export analysis results for documentation

2. Requirements Management

Purpose: Refine and improve requirements quality

How to use:

1. Go to Requirements tab
2. Choose input method:
   • Paste text directly (one-liner or full document)
   • Upload requirement document (.md, .txt, .pdf)
   • Load from Jira ticket (Enterprise feature - preview only)
   • Load from Confluence page (Enterprise feature - preview only)
3. Click "Refine Requirements"
4. Review AI-generated refined requirements with:
   • Structured user stories
   • Acceptance criteria
   • Technical specifications
   • Priority assignments
5. Download or copy results

3. Design Generation

Purpose: Create technical design from requirements

How to use:

1. Go to Design tab
2. Select source (refined requirements or paste manually)
3. Click "Generate Design"
4. Review architecture diagrams and specifications
5. Download design document

4. Test Case Generation

Purpose: Generate comprehensive test scenarios and manage test data

How to use:

1. Go to Test Cases tab
2. Option A - Generate from Design:
   • Select source (design document or paste requirements)
   • Click "Generate Test Cases"
   • Review AI-generated scenarios with steps and expected results
3. Option B - Upload Existing Tests:
   • Click "Upload Test Cases" button
   • Select CSV or Excel file with columns: title, priority, status, description
   • Test cases stored for quality analysis
4. Manage Test Cases:
   • View all test cases in table format
   • Export to Excel/CSV for external use
   • Delete test cases using "Delete Test Cases" button
5. View test-to-code ratio and coverage metrics

5. Automation Analysis

Purpose: Analyze test automation scripts and measure automation coverage

How to use:

1. Go to QA Automation tab
2. Analyze Scripts:
   • Enter automation repository URL (Git)
   • Or upload automation scripts as ZIP
   • Click "Analyze Automation"
3. View Results:
   • Framework detection (Selenium, Pytest, JUnit, Cypress, etc.)
   • Script count and coverage metrics
   • Automation patterns and best practices
   • Recommendations for improvement
4. Manage Automation:
   • Delete automation data using "Delete Automation" button
   • Re-analyze after updates with "Re-Analyze" button

6. Quality Score Analysis

Purpose: Comprehensive quality metrics combining code, tests, and automation

How to use:

1. Go to Quality Score tab
2. Select Scan Mode:
   • Quick Scan (Recommended): Test density analysis via keyword matching
     • ⚡ Speed: 1-2 seconds
     • 💰 Cost: Free
     • 📊 Method: Measures test-to-code ratio (proxy metric)
     • ✅ Best for: Fast quality checks, regular monitoring
   • Deep Scan: LLM semantic coverage analysis
     • ⏱️ Speed: 30-60 seconds
     • 💰 Cost: $0.10-0.30 per analysis (API costs)
     • 📊 Method: LLM validates actual function coverage
     • ✅ Best for: Accurate coverage assessment, pre-release audits
3. Click "Calculate Quality Score"
4. Review 3-Layer Scoring System:
   • Test Density/Semantic Coverage (60 points): Quick Scan uses test-to-code ratio, Deep Scan uses actual function coverage
   • Automation Coverage (30 points): Automated tests / Total tests
   • Bonus (10 points): High coverage on both metrics
5. View Detailed Insights:
   • Covered vs uncovered modules
   • Test-to-code ratio (Quick) or function coverage (Deep)
   • Automation percentage (target: >70%)
   • Untested modules/functions requiring attention
   • Risk assessment and recommendations

---

📊 Understanding Quality Score Calculation

FlowSquad's quality score is a weighted combination of three key metrics:

Formula Breakdown

Quality Score = (Test Density/Semantic Coverage × 0.6) + (Automation Coverage × 0.3) + Bonus (0-10 points)

Where:
- Test Density (Quick) = Based on test-to-code ratio (0-100%)
- Semantic Coverage (Deep) = LLM-validated function coverage (0-100%)
- Automation Coverage = (Automated Tests / Total Tests) × 100%
- Bonus = +10 points if Code Coverage >70% AND Automation >50%

Component 1: Test Density / Semantic Coverage (60% weight)

IMPORTANT: This is NOT traditional code coverage (line/branch coverage from instrumentation tools).

Quick Scan - Test Density:

• What it measures: Test-to-code ratio via keyword matching
• How it works: Counts tests mapped to each module by name similarity
• Accuracy: Proxy metric (doesn't validate actual test content)
• Speed: 1-2 seconds
• Cost: Free

Deep Scan - Semantic Coverage:

• What it measures: Actual function coverage using LLM
• How it works: LLM extracts functions from code, validates which tests cover them
• Accuracy: High (validates actual test-function relationships)
• Speed: 30-60 seconds
• Cost: ~$0.10-0.30 per analysis

Component 2: Automation Coverage (30% weight)

What it measures: Percentage of test cases that are automated

Automation % = (Number of Automation Scripts / Number of Test Cases) × 100%

Component 3: Completeness Bonus (10 points)

Conditions: Both must be true:

• Test Density/Semantic Coverage > 70%
• Automation Coverage > 50%

Complete Example

E-Commerce Demo Scenario (Quick Scan):

Initial State:
Code Modules: 3 (Backend, Frontend, Payment Service)
Test Cases: 15
Automation Scripts: 0

Test Density (Quick Scan):
- Test-to-code ratio: 15/3 = 5.0
- Density: 100% (5+ tests per module)
- Score: 100% × 0.6 = 60 points

Automation Coverage:
- Scripts: 0/15 = 0%
- Score: 0% × 0.3 = 0 points

Bonus: 0 (automation <50%)

Total Quality Score: 60/100 ⚠️

After Uploading Automation:
Test Density: 60 points
Automation Coverage: 14/15 = 93% = 28 points
Bonus: +10 (100% code + 93% automation)

Total Quality Score: 98/100 ✅

---

👤 Admin Features

Access admin features from the navigation bar:

License Info (🔑 License)

• View trial status and days remaining
• Check product usage (evaluation limit: 2 products)
• Request evaluation extension
• View machine ID for support

Setup Configuration (⚙️ Setup)

AI Provider Settings:

• Switch between OpenAI, GitHub Models, or Anthropic
• GitHub Models recommended for evaluation (30-day free trial)
• Update API keys securely (stored encrypted)
• Test API Key: Validates authentication AND model access
• Model Selection: Choose from models your API key can actually access
• Adjust token and daily limits for cost control

LDAP Security Configuration:

• Enable/disable LDAP authentication
• Update LDAP server connection details
• Configure user search base and filters
• Map LDAP groups to application roles
• Test LDAP connectivity before saving

---

💡 Tips & Best Practices

1. Security Best Practices
   • API keys encrypted in database (Fernet encryption)
   • Use separate API keys for evaluation vs production
   • Enable LDAP for enterprise-grade authentication
   • Change default admin password immediately
   • Use LDAP groups for role-based access control
2. Try Demo First
   • Click "🎬 Try Demo" to see the complete FlowSquad workflow
   • Real AI analysis runs during demo creation
   • Experience the full SDLC pipeline: Code → Requirements → Design → Tests → Quality
   • Demo includes 3 codebases, 15 test cases, sample requirements
3. Cost Management
   • GitHub Models: 30-day free trial - best for evaluation
   • OpenAI: Start with daily limits to control costs
   • Use GPT-3.5 Turbo for faster/cheaper processing
   • GPT-4/GPT-4o provides better quality for complex analysis
4. Quality Score Optimization
   • Target 3-5 test cases per code module (test-to-code ratio)
   • Aim for >70% automation coverage
   • Use descriptive test/automation names for proper mapping
   • Re-run quality score after improvements to track progress
5. Evaluation Limits
   • Maximum 2 products
   • 45-day trial period
   • Full feature access during evaluation

---

🔄 Common Workflows

Workflow 0: Quick Demo (First-Time Users)

1. Click "Try Demo" on dashboard
2. Explore e-commerce platform demo with complete data
3. Use sample requirements from demo-products/ecommerce-platform/
4. Test Requirements refinement and Design generation
5. Delete demo product when ready for real work

Workflow 1: New Feature Development

1. Create product
2. Analyze existing codebase
3. Add feature requirements (paste or upload document)
4. Refine requirements with AI
5. Generate design document
6. Generate test cases
7. Upload or link automation repository
8. Review quality score and identify gaps

Workflow 2: Legacy Code Understanding

1. Create product
2. Analyze codebase for complexity hotspots
3. Review entry points and dependencies
4. Upload existing test cases (CSV/Excel)
5. Analyze automation coverage
6. Run quality score analysis
7. Get prioritized refactoring recommendations

Workflow 3: Complete SDLC Flow

1. Create product
2. Upload/paste requirements document
3. Refine requirements with AI-generated user stories
4. Generate technical design with architecture diagrams
5. Generate comprehensive test cases
6. Upload existing test cases or create new ones
7. Analyze automation repository
8. Calculate quality score (target: >75/100)
9. Iterate on gaps identified by quality analysis

---

🆘 Troubleshooting

"Setup Required" Error

Cause: Setup not completed or database missing

Solution:

• Complete the setup wizard
• If issue persists, reinstall FlowSquad

"Invalid API Key" Error

Cause: API key incorrect or expired

Solution:

1. Go to provider website and verify key
2. Generate new API key if needed
3. Use "Test API Key" button before saving
4. Check for typos or extra spaces

"License Expired" Error

Cause: 45-day trial period ended

Solution:

1. Get machine request key from License Info
2. Contact support@flowsquad.com for extension

"Product Limit Reached" Error

Cause: Already have 2 products (evaluation max)

Solution:

• Delete an existing product from the dashboard
• Product deletion removes database records AND uploaded documents folder
• Contact support@flowsquad.com for increased limit

Code Analysis Fails

Possible Causes:

• Unsupported language
• Large codebase (memory limits)
• Invalid file structure

Solutions:

1. Check language is supported (supports 30+ languages)
2. Split large codebases into modules
3. Ensure ZIP contains source code (not binaries)
4. Check logs/ folder for detailed error messages

LDAP Connection Fails

Possible Causes:

• LDAP server unreachable
• Incorrect bind credentials
• Port blocked by firewall
• Search base misconfigured

Solutions:

1. Verify LDAP host/port with IT department (standard: 389 for LDAP, 636 for LDAPS)
2. Test bind user credentials separately
3. Check firewall allows outbound connections
4. Try without SSL first (port 389) for testing
5. Verify search base DN matches your Active Directory structure

Quality Score Shows 0/100 or Low Score

Possible Causes:

• No codebases analyzed yet
• No test cases uploaded
• No automation scripts analyzed

Solutions:

1. Analyze at least one codebase first
2. Upload test cases (CSV/Excel) or generate from design
3. Analyze automation repository for coverage metrics
4. Use "Try Demo" to see realistic quality metrics (80-85/100)
5. Re-run quality analysis after adding data

---

❓ FAQ

Q: Should I try the demo first?
A: Yes! Click "Try Demo" to instantly explore all features with a complete e-commerce platform example. Delete it when ready for actual work.

Q: What file formats can I upload for test cases?
A: CSV and Excel (.xlsx, .xls) files. Required columns: title, priority, status, description.

Q: How is the Quality Score calculated?
A: Three components: Test Density/Semantic Coverage (60 points), Automation Coverage (30 points), Quality Metrics (10 points bonus). Target: >75/100 for production-ready code.

Q: What automation frameworks are supported?
A: All major frameworks: Selenium, Pytest, JUnit, TestNG, Cypress, Playwright, Mocha, Jest, Protractor, Robot Framework, Cucumber, SpecFlow, and more.

Q: What programming languages are supported for analysis?
A: FlowSquad supports 30+ languages including JavaScript, TypeScript, Python, Java, C#, PHP, Ruby, Swift, Kotlin, Go, Rust, and more.

Q: Can I delete test cases or automation data?
A: Yes. Each tab has a "Delete" button to remove all uploaded data and start fresh.

Q: Is my code sent to OpenAI/GitHub?
A: Only when explicitly requested for analysis. Code analysis happens locally. LLM is used only for documentation generation and requirements analysis.

Q: Which AI provider should I choose?
A: GitHub Models offers 30-day free trial (recommended). OpenAI (GPT-4) offers excellent quality. Anthropic (Claude) provides superior reasoning.

Q: Can I use offline?
A: No, evaluation version requires internet for LLM API calls. Enterprise version offers offline mode with local LLMs.

Q: Should I enable LDAP?
A: Yes, if you have Active Directory. LDAP provides enterprise-grade security: centralized authentication, password policies, and audit trails.

Q: Can multiple users use it simultaneously?
A: Yes. Evaluation version supports LDAP authentication for multiple users. Enterprise version provides unlimited concurrent users.

Q: What happens after 45 days?
A: Application stops allowing new products/analysis. Contact support@flowsquad.com for extension or upgrade.

Q: Can I migrate to a different machine?
A: Yes, but license is MAC-address locked. Contact support@flowsquad.com for a new license.

Q: Is my data secure?
A: Yes. All data stored locally in encrypted SQLite database. API keys encrypted with Fernet.

Q: Can I backup my data?
A: Yes. Backup the FlowSquad installation folder, especially flowsquad_engine.db file.

---

🚀 Enterprise Features (Coming Soon)

FlowSquad Enterprise Edition is currently under development. Based on evaluation user feedback, we're building a production-grade platform for teams of all sizes.

Enterprise Roadmap

Phase 1: Database Migration & Multi-Tenancy

• ✅ PostgreSQL database (scalable, production-ready)
• ✅ Multi-tenant architecture (organization isolation)
• ✅ Advanced RBAC (roles: admin, product manager, developer, viewer)
• ✅ Unlimited products and users
• ✅ Data migration from evaluation version (zero data loss)

Phase 2: Enterprise Features & Billing

• ✅ Stripe billing integration (subscription management)
• ✅ License management (online validation, grace periods)
• ✅ MFA support (TOTP via QR code)
• ✅ Enhanced audit logging
• ✅ Email notifications
• ✅ Organization dashboard (usage metrics, cost breakdown)

Phase 3: Advanced SDLC Pipeline - Complete Squad Workflow

• ✅ Requirements → Stories → Tasks End-to-End Flow
• ✅ User Story Breakdown (IT + Non-IT stories)
• ✅ Task Generation (Development, QA, Design, DevOps, Documentation, Security)
• ✅ Story Point Estimation (with confidence scoring)

Phase 4: Integrations

• ✅ GitHub/GitLab/Bitbucket (enhanced repository integration)
• ✅ Jira/Linear/Azure Boards (bidirectional sync)
• ✅ Confluence/Notion (auto-publish design docs)
• ✅ Slack/Teams (notifications, webhooks)
• ✅ SSO/SAML (enterprise authentication)

How to Stay Updated

Join the Enterprise Waitlist:

• Visit: https://flowsquad.io/enterprise (coming soon)
• Email: enterprise@flowsquad.com

---

📞 Support

Evaluation Extension:

• Click "🔑 License" → "Request Extension"
• Email generated key to support@flowsquad.com

Questions or Issues:

• Email: support@flowsquad.com
• Include your machine ID (from License page)

Upgrade to Enterprise:

• Email: support@flowsquad.com
• Unlimited products, advanced features, on-premise deployment

---