Administrator Guide

Complete reference for Global Administrators -- creating products, managing users, configuring LLMs, reviewing audit logs, and operating the Admin Panel.

1. Administrator Roles

FlowSquad defines three tiers of access. Understanding the role model is essential before configuring users, products, or authentication.

Global Administrator

Scope: Full, unrestricted system access. The first Global Admin is created during the Setup Wizard.

Product Administrator

Scope: Scoped to one or more assigned products. Product Admins have full control within their products but cannot access system-wide settings.

Granting Product Admin access -- two equivalent methods:

1. RBAC Admin Panel: Admin Panel -> User Management -> select the user -> assign the "Product Admin" role, then associate the user with the target product.
2. Product Settings: Navigate to the product -> Settings -> Admin List -> add the user's account directly to the product's admin list.

Both methods grant identical access. Either may be used depending on your workflow.

Product Admins can perform the following within their assigned products:

• Add and remove product members
• Configure product-specific LLM models and settings
• Delete artifacts (Requirements, Epics, Stories, Tasks, Test Cases, Designs) directly through the product dashboard -- no backend access is required
• View product-level analytics and audit events

Regular User

Scope: Read and write access on assigned products only.

• Create and edit requirements, epics, stories, and tasks
• Generate designs and test cases
• View analytics for their assigned products
• Cannot manage other users or access any admin features

2. Admin Panel Overview

The Admin Panel is the central control surface for Global Administrators. Access it by clicking Admin Panel in the top navigation bar. The URL is /admin.

3. Creating Products & Assigning Admins

Creating a Product

1. From the FlowSquad dashboard, click + New Product
2. Enter the Product Name (required) and an optional description
3. Select the Default LLM Model for this product (overrides the global default). Can be changed later in Product -> Settings -> LLM Configuration
4. Optionally assign initial Product Admins (see below)
5. Click Create Product

The new product opens automatically. Team members can now be added and the product is ready for use in all workflow tabs.

Assigning a Product Admin

Two equivalent methods -- use whichever fits your workflow:

Managing Product Members

Product Admins and Global Admins can add or remove members at any time:

• Navigate to Product -> Manage Users
• Search for existing FlowSquad users by name or email
• Assign role: Regular User (read/write on all tabs) or Product Admin (full product control)

Product Settings

Navigate to Product -> Settings. Available options:

• Product name, description, and logo
• LLM model assignments per operation (Analyze, Refine, Epic, Story, Task, Design, Test Cases, Quality, Security Scan, AskProduct)
• Admin List -- add or remove Product Admins
• Member list -- add or remove Regular Users
• Integration overrides -- override the default Jira project key for this product
• Danger Zone -- archive or permanently delete the product

4. User Management

Path: Admin Panel -> User Management

Creating Users

Local Users

1. Click + Add User
2. Complete the form:
   • Username -- required, must be unique
   • Email -- required, must be unique
   • Display Name -- shown in the UI
   • Password -- minimum 8 characters; stored as bcrypt hash (12 rounds)
   • Role -- Global Admin, Product Admin, or Regular User
3. If assigning Product Admin or Regular User, also assign the user to one or more products
4. Click Create User

LDAP / Active Directory Users

LDAP users are auto-created in FlowSquad on their first successful LDAP login. To pre-create an account before first login, use Admin Panel -> User Management -> Search LDAP, locate the user, and click Import.

SAML / OAuth2 Users

SSO users are created automatically when they complete their first login. The email address returned by the identity provider is used as the username. These accounts cannot have a local password set -- authentication is exclusively via SSO.

Assigning and Changing Roles

To promote a user to Global Admin: click the user's row -> Promote to Global Admin. This action requires confirmation, as Global Admins have full system access.

For product-level roles, navigate to the product -> Manage Users -> add or change the user's role (Product Admin or Regular User).

The role hierarchy:

Global Admin  (system-wide, unrestricted)
    v
Product Admin (scoped to assigned products)
    v
Regular User  (read/write on assigned products)

Resetting Passwords

Click a user's row -> Reset Password. You may either set a specific temporary password or generate a password-reset link to email to the user. SSO-only users (LDAP, SAML, OAuth2) do not have a local password and cannot use this function.

Bulk Import via CSV

To import multiple users at once: Admin Panel -> User Management -> Import Users (CSV). The CSV must include columns: username, email, display_name, role. Download the template from the import dialog for the exact format.

Multi-Authentication User Management

FlowSquad supports multiple authentication methods simultaneously. Each user record stores the auth provider and provider-specific ID:

To filter users by authentication provider, use the All Providers dropdown in the User Management list. Each user's detail view shows their auth method and last login timestamp.

Multi-Factor Authentication (MFA)

FlowSquad supports TOTP-based MFA (Google Authenticator, Authy, and compatible apps) with email backup codes.

• Users configure MFA in their own Preferences page by scanning a QR code
• 10 one-time backup codes are generated at setup time
• Optional SMS backup requires Twilio configuration in Settings

Admin MFA actions:

• View MFA status: The user list displays an MFA badge next to each user
• Reset MFA: Click user -> Reset MFA -- forces the user to re-enrol on next login
• Disable MFA: Click user -> Disable MFA -- removes MFA requirement for that account
• Force MFA policy: Admin Panel -> Settings -> Security -> Require MFA for all users -- users without MFA set up are redirected to the enrolment page on next login

5. Authentication Configuration

Configured via: Setup Wizard → Step 4 (Authentication). The wizard can be re-opened at any time from the ⚙️ Setup button in the navigation bar.

FlowSquad uses an ordered authentication chain: Local -> LDAP -> SAML -> OAuth2. Local authentication is always active and serves as the fallback. Each additional method is enabled independently.

Local Authentication

Always enabled and cannot be disabled. It provides the primary admin account and acts as the fallback when all other methods are unavailable.

• Minimum password length: 8 characters
• Passwords are hashed using bcrypt with 12 rounds
• Password complexity requirements are configurable in Admin Panel -> Settings -> Security

LDAP / Active Directory

1. Setup Wizard Step 4 → LDAP / Active Directory
2. Configure the connection:
   • Server URI: ldap://ad.company.com:389 or ldaps://ad.company.com:636
   • Bind DN: CN=ServiceAccount,OU=Users,DC=company,DC=com
   • Bind Password: Service account password
   • User Search Base: OU=Users,DC=company,DC=com
   • User Search Filter: (sAMAccountName={username})
   • Group Search Base: OU=Groups,DC=company,DC=com
   • Group Membership Attribute: memberOf
3. Click Test Connection to verify
4. Map LDAP groups to FlowSquad roles:
   • CN=FlowSquad-Admins,OU=Groups,DC=company,DC=com -> Global Admin
   • CN=FlowSquad-Users,OU=Groups,DC=company,DC=com -> Regular User
5. Save configuration

SAML 2.0 SSO

Supported identity providers include Keycloak, Okta, Azure AD, OneLogin, ADFS, Google Workspace, and any standard SAML 2.0 provider.

1. Setup Wizard Step 4 → SAML
2. Enter identity provider settings:
   • IdP Entity ID: Your IdP's entity ID (from IdP metadata)
   • IdP SSO URL: Single Sign-On URL from your IdP
   • IdP SLO URL: Single Logout URL (optional)
   • IdP Certificate: Paste the X.509 PEM certificate from your IdP
3. Copy service provider values to your IdP:
   • SP Entity ID: https://flowsquad.company.com/saml/metadata
   • SP ACS URL: https://flowsquad.company.com/saml/acs
   • SP SLO URL: https://flowsquad.company.com/saml/sls
4. Configure attribute mappings:
   • Email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
   • Display Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
5. Optionally enter Designated Admin Emails -- a comma-separated list of email addresses that are automatically promoted to Global Admin on first SSO login
6. Click Download Metadata XML and upload it to your IdP
7. Click Test SAML Login, then Save Configuration

OAuth2 Social Login

Supported providers: GitHub, Google, Microsoft, Okta, Keycloak, and any OpenID Connect-compatible provider.

Example: GitHub OAuth2 setup

1. In GitHub: Settings -> Developer Settings -> OAuth Apps -> New OAuth App
   • Homepage URL: https://flowsquad.company.com
   • Authorization callback URL: https://flowsquad.company.com/oauth2/github/callback
   • Copy the Client ID and Client Secret
2. In FlowSquad: Setup Wizard Step 4 → OAuth2 → GitHub
3. Enter Client ID, Client Secret, and scopes (user:email,read:user)
4. Click Test OAuth2 Login, then Save

6. LLM Configuration

Path: Admin Panel -> LLM Configuration

FlowSquad supports multiple LLM providers simultaneously. API keys are configured globally, then individual models are assigned per product and per operation, giving fine-grained control over both quality and cost.

Supported Providers

Adding an LLM Provider

OpenAI

1. Click + Add LLM Provider -> select OpenAI
2. Enter your API key
3. Select models to enable (GPT-4o for highest quality, GPT-4o-mini for cost efficiency, GPT-3.5-turbo for fastest/cheapest)
4. Click Test Connection, then Save

Anthropic Claude

1. Click + Add LLM Provider -> select Anthropic
2. Enter your API key
3. Select models (Claude 3.5 Sonnet for best overall, Claude 3 Opus for highest intelligence, Claude 3 Haiku for fastest/cheapest)
4. Click Test Connection, then Save

GitHub Models

1. Click + Add LLM Configuration -> select GitHub
2. Create a fine-grained Personal Access Token at github.com/settings/personal-access-tokens/new: under Permissions expand Copilot Request → set to Read-only. No repository access is needed. Classic PATs are not supported.
3. Paste the token (starts with github_pat_). Your account must be enrolled in the GitHub Models marketplace (free).
4. Click Test Connection & Fetch Models, select a text model, then Add to Configuration List

Note: Enterprise-managed user (EMU) accounts cannot access GitHub Models — use a personal GitHub account.

Ollama (Self-Hosted)

# 1. Install Ollama on your server
curl https://ollama.ai/install.sh | sh

# 2. Pull desired models
ollama pull llama3
ollama pull mistral

1. Click + Add LLM Provider -> select Ollama
2. Enter the Ollama API URL: http://localhost:11434
3. Available models are auto-detected from Ollama
4. Click Test Connection, then Save

Per-Product LLM Assignment

Path: Product -> Settings -> LLM Configuration

Each product can independently assign a different provider and model to each of the 10 AI operations:

Cost optimisation example:

Analysis (high volume):  GPT-4o-mini  = $0.15 per 1M tokens
Design (low volume):     GPT-4o       = $2.50 per 1M tokens
Total Savings: ~85% compared to using GPT-4o for all operations

LLM Cost Tracking

Path: Admin Panel -> Analytics & Insights -> LLM Usage

• Per-provider and per-product cost breakdown
• Token usage (input and output) with daily, weekly, and monthly trend charts
• Set monthly budget limits per product; email alerts fire when thresholds are reached
• Optionally pause AI operations automatically if the budget limit is exceeded

7. Database Management

Path: Admin Panel -> Database Settings

Database configuration is read-only in the Admin Panel after initial setup. Changing the database type requires running the Setup Wizard (/setup -- Global Admin only) and migrating existing data.

Supported Database Types

Configuration Database

FlowSquad uses a separate SQLite database (flowsquad_engine.db) for storing settings, API keys, license information, and authentication credentials. This database is always SQLite and is distinct from the product data database (PostgreSQL or MySQL).

Configuration Database Security

All sensitive values stored in the configuration database — API keys, integration passwords, SAML keys — are encrypted at the field level using Fernet AES-128-CBC before being written to the settings table. Whole-file database encryption is not available. For at-rest protection of the full database file, use filesystem-level encryption (LUKS/dm-crypt on Linux, BitLocker on Windows, or an encrypted Docker volume).

For product data encryption at rest, use your database platform's native capabilities:

• PostgreSQL: pgcrypto extension or filesystem-level encryption
• MySQL: InnoDB tablespace encryption

Running Migrations

Database migrations run automatically on application start whenever a new version of FlowSquad is launched. No manual steps are required. Always back up your database before upgrading.

8. License Management

Path: Admin Panel -> License Management

License Types

Viewing License Details

Admin Panel -> License Management displays:

• License type (Evaluation / Enterprise)
• Company name
• Maximum products allowed
• Expiration date and days remaining
• License key (partial, shown for reference only)

Applying a New Enterprise License

1. Receive the enterprise_license.lic file from FlowSquad sales
2. Admin Panel -> License Management -> Upload License
3. Select the .lic file and click Upload
4. The system validates the RSA-4096 signature, expiration date, and company name match
5. If valid, the license is activated immediately and the page reloads showing the new details

License Expiration Handling

When the license expires, FlowSquad blocks all access (HTTP 403) and displays a license expiry page. Users cannot log in until a valid license is uploaded. The license upload widget remains accessible on the expiry page so a Global Admin can apply a renewal without needing to log in first.

9. Analytics & Insights

Path: Admin Panel -> Analytics & Insights

Global Admins see analytics across all products. Product Admins accessing the product-level analytics tab see data for their assigned products only.

System-Wide Analytics

The system-wide dashboard provides:

• Usage metrics: Total requirements created (all-time and last 30 days), designs and test cases generated, active users (last 7 and 30 days), storage consumed
• LLM usage: API calls per provider, tokens consumed (input and output), estimated costs per provider and in total, average response time, error rate
• Performance: Average page load time, API response time, database query performance, background task queue depths

Per-Product Analytics

Path: Product -> Analytics tab

• Requirements by status (New, In Progress, Completed)
• Quality score trends over time
• Most active contributors
• LLM cost breakdown scoped to that product
• Activity timeline

Exporting Analytics

Data can be exported in the following formats:

• CSV -- raw data suitable for Excel or Google Sheets
• PDF -- formatted report with charts
• JSON -- for API and SIEM integration

Scheduled reports (daily, weekly, or monthly) can be configured and emailed to Global Admins and Product Admins with customisable metrics.

10. Audit Logs

Path: Admin Panel -> Audit Logs

FlowSquad logs all security-relevant and data-mutating events automatically. Logs cannot be modified or deleted by any user.

Logged Event Categories

Searching and Filtering Logs

Use the filter controls to narrow the log view:

• Date range: Last 7 days, last 30 days, or custom range
• Event type: Login, Create, Update, Delete, and more
• User: Specific username or all users
• Product: Specific product or all products
• Severity: Info, Warning, Error

Example searches: "All failed login attempts in the last 24 hours", "All product deletions by user admin", "All license changes".

Exporting Audit Logs

Logs can be exported as CSV (for compliance audits and Excel analysis), JSON (for SIEM integration), or PDF (formatted report).

FlowSquad audit logs are designed to satisfy the requirements of SOC 2, HIPAA, and GDPR compliance programmes:

• SOC 2: Comprehensive access and change event logging
• HIPAA: Full access logging with user identification
• GDPR: User data access tracking to support data subject requests

11. System Health

Path: Admin Panel → System Health (also accessible via the 🩺 System Health button on the Audit Logs, Analytics, User Management, and Settings pages)

The System Health page gives Global Administrators a live view of every service FlowSquad depends on, and lets them configure automated background monitoring that surfaces warnings directly in the UI.

On-Demand Health Check

Click ▶ Run Health Check Now to trigger an immediate probe of all configured services. Results appear in a table with three columns:

A summary line below the table shows the timestamp and a count of healthy services (e.g., 4/5 services healthy).

Recurring Health Monitoring

When enabled, FlowSquad runs health probes automatically in the background at a configurable interval. The results are surfaced as a warning banner at the top of every page whenever a service is degraded — no manual checking is required.

Click 💾 Save Settings after making changes. Settings take effect immediately without restarting FlowSquad.

12. Backup & Recovery

Regular backups protect against data loss from hardware failure, migration errors, or accidental deletions. FlowSquad recommends daily automated backups with off-site storage.

Configuration Database Backup

Copy the configuration database file directly:

# Linux/Docker -- config database
cp ${FLOWSQUAD_DATA_DIR:-/var/lib/flowsquad}/flowsquad_engine.db /backups/engine_$(date +%Y%m%d).db

# Windows
copy "%LOCALAPPDATA%\FlowSquad\flowsquad_engine.db" "C:\Backups\engine_%date:~-4,4%%date:~-10,2%%date:~-7,2%.db"

Product Database Backup

# PostgreSQL
pg_dump -U flowsquad -h localhost flowsquad > backup_$(date +%Y%m%d).sql

# MySQL / MariaDB
mysqldump -u flowsquad -p flowsquad > backup_$(date +%Y%m%d).sql

# SQLite (if used for product data)
cp flowsquad_engine.db backup_$(date +%Y%m%d).db

Automated Backup Script (Linux)

#!/bin/bash
BACKUP_DIR="/var/backups/flowsquad"
DATE=$(date +%Y%m%d_%H%M%S)
mkdir -p $BACKUP_DIR

# Backup product database
pg_dump -U flowsquad flowsquad | gzip > $BACKUP_DIR/flowsquad_$DATE.sql.gz

# Backup config database
cp /var/lib/flowsquad/flowsquad_engine.db $BACKUP_DIR/flowsquad_engine_$DATE.db

# Retain only the last 30 days
find $BACKUP_DIR -name "*.sql.gz" -mtime +30 -delete

echo "Backup completed: $DATE"

Schedule this script as a daily cron job:

# Make executable
sudo chmod +x /usr/local/bin/backup-flowsquad.sh

# Run daily at 2:00 AM
sudo crontab -e
# Add: 0 2 * * * /usr/local/bin/backup-flowsquad.sh

Restore Procedure

# PostgreSQL
gunzip -c backup_YYYYMMDD.sql.gz | psql -U flowsquad flowsquad

# MySQL
gunzip -c backup_YYYYMMDD.sql.gz | mysql -u flowsquad -p flowsquad

13. Security Best Practices

Administrator Account Security

• Use a minimum 16-character password for all Global Admin accounts
• Use a password manager -- do not reuse passwords
• Enable TOTP-based MFA for every Global Admin account
• Maintain 2-3 Global Admin accounts for redundancy; do not create more
• Review active user accounts quarterly and remove accounts for departed personnel immediately
• Rotate LLM API keys at least every 90 days
• Review audit logs at minimum weekly for suspicious activity

Network Security

• Always serve FlowSquad over HTTPS in production -- obtain certificates from Let's Encrypt or a trusted CA
• Use an Nginx (or Apache) reverse proxy for SSL termination, rate limiting, and DDoS protection
• Block direct external access to port 5000 -- expose only port 443 via the reverse proxy

# UFW example -- allow HTTPS only from internet, block direct FlowSquad port
sudo ufw allow 443/tcp
sudo ufw deny 5000/tcp

Database Security

• Verify API keys and integration credentials are stored (field-level Fernet encryption is applied automatically)
• Restrict the FlowSquad database user to only the FlowSquad database:

-- PostgreSQL: limit permissions
REVOKE ALL ON DATABASE postgres FROM flowsquad;
GRANT ALL PRIVILEGES ON DATABASE flowsquad TO flowsquad;

• Store database backups off-site (AWS S3, Azure Blob Storage, or equivalent)
• Enable encryption at rest for the product database using your database platform's native capabilities

Compliance Checklists

SOC 2

• Audit logs enabled and exported monthly
• MFA enforced for all Global Admin accounts
• Sensitive credentials stored encrypted (field-level encryption, enabled by default)
• Regular security patches applied

HIPAA

• All communications served over HTTPS
• Database encryption enabled (at rest and in transit)
• Access logs retained for a minimum of 6 years
• Role-based access controls (RBAC) implemented

GDPR

• User data export capability available
• User deletion (right to be forgotten) supported
• Audit logs capture all data access events
• Data processing agreements in place with LLM providers

14. Troubleshooting: Admin & Platform Issues

Performance -- Slow Requirement Refinement (30+ Seconds)

Diagnosis: Admin Panel -> Analytics -> LLM Usage -> check average response times.

Solutions:

• Switch to a faster model: Admin Panel -> Products -> Edit product -> LLM Configuration -> Refine -> select GPT-4o-mini (averages 1-3 s, 90% cheaper than GPT-4o)
• Break down long inputs: Very long requirements (5,000+ characters) increase token count. Split into three smaller focused requirements.
• Check network latency to LLM provider: ping api.openai.com -- if >200 ms, consider switching to Anthropic Claude or Ollama (self-hosted, zero network latency)

Performance -- PostgreSQL Slow Queries

Diagnosis:

-- Find slow queries in PostgreSQL
SELECT query, total_time, calls, mean_time
FROM pg_stat_statements
WHERE mean_time > 1000
ORDER BY total_time DESC
LIMIT 10;

Solutions:

-- Add missing indexes
CREATE INDEX idx_requirements_product_id ON requirements(product_id);
CREATE INDEX idx_designs_requirement_id ON designs(requirement_id);
CREATE INDEX idx_test_cases_design_id ON test_cases(design_id);
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_audit_logs_timestamp ON audit_logs(timestamp);

Tune PostgreSQL configuration in /etc/postgresql/XX/main/postgresql.conf:

shared_buffers      = 256MB
effective_cache_size = 1GB
work_mem            = 16MB

sudo systemctl restart postgresql

Configuration Database Recovery

If flowsquad_engine.db is missing or corrupted, restore from a backup copy. No password is required. Sensitive field values (API keys, passwords) will be re-entered through the Setup Wizard after restore.

License Upload Errors