Flujo Documentation

The Storage API provides a simple interface for reading, writing, and deleting data using predefined keys. It acts as a bridge between frontend components and backend filesystem storage utilities.

Architecture

The system follows a three-tier flow:

1. Frontend Components: Make HTTP requests to the API.
2. API Layer (route.ts): Validates request parameters and handles HTTP methods.
3. Storage Utilities: Persists the validated data to the filesystem.

Supported Storage Keys

You must use one of the following valid StorageKey enum values for all operations:

• models
• mcp_servers
• flows
• chat_history
• theme
• global_env_vars
• encryption_key

The modelService provides consistent error handling across all operations. Every method returns a Promise that resolves to a result object. This object contains:

• success: A boolean flag indicating if the operation was successful.
• error: An optional message containing error details if success is false.

UI components should check the success flag to determine whether to proceed or display an error message to the user.

Updating a server configuration via PUT performs a merge and upsert. You can send a partial body to update specific fields.

Crucially, the disabled field controls the connection state:

• Setting disabled: true will disconnect the server.
• Setting disabled: false will (re)connect the server.

The Environment Variables API automatically protects sensitive data based on naming conventions.

Detection Logic: Variables with names containing any of the following substrings are treated as sensitive: key, secret, password, token, or auth.

Storage Behavior:

• Sensitive variables are encrypted before being persisted.
• Encrypted values are stored with an encrypted: prefix.
• If encryption fails, the value is stored with an encrypted_failed: prefix.

Retrieval Behavior:

• By default, the API returns ******** for sensitive values.
• Actual values are only returned if the includeSecrets=true parameter is provided in the request.

The FLUJO API layer acts as a bridge between the user interface and backend services. It is organized into a clean architecture pattern to ensure separation of concerns and maintainability.

The data flow follows this hierarchy:

1. UI Components: React components providing the interface.
2. Frontend Services: TypeScript modules that encapsulate API calls.
3. API Layer: Next.js API routes acting as adapters for HTTP requests.
4. Backend Services: The core business logic implementation.

This structure prevents circular dependencies and allows each layer to be tested and extended independently.

FLUJO records local, metadata-only execution statistics for experimental features. Data is stored as JSONL files (one JSON object per line) in the db/statistics/ directory, partitioned by UTC day using the format YYYY-MM-DD.jsonl.

Key Lifecycle Behaviors:

• Concurrency: Appends are serialized independently per partition, allowing concurrent runs to maintain event order without blocking other days.
• Reliability: Recording is "best-effort." Failures in serialization, appending, recovery, or retention will never reject or alter a flow execution.
• Retention: Partitions older than 90 days are pruned asynchronously following a successful append. Cleanup is isolated from the write result and may be retried later.

The telemetry contract is designed for anonymity. When building a collector, adhere to these privacy requirements:

• ID Rotation: The anonymousDailyId changes every UTC day.
• No PII: The ID must not be joined to IP addresses, user agents, registry accounts, cookies, or any other persistent identifiers.
• Log Sanitization: Request logs should omit or promptly discard source IP and user-agent data.
• Rate Limiting: The endpoint should be rate-limited, but the rate-limiting mechanism must not create a durable client fingerprint.