Best Practices

Best practices & Limitations¶

To get the best out of the MindFlight AI Server, it's essential to follow a few best practices and understand the limitations of the system. This ensures your deployment remains secure, stable, and scalable.

✅ Security Best Practices¶

• Never hardcode tokens or secrets:
  Always store sensitive data (like JWT tokens, API keys) in environment variables or a secure vault.

• Use HTTPS in production:
  Make sure all API endpoints are served over HTTPS to avoid token leakage.

• Validate incoming webhooks:
  Check the authenticity of webhooks by validating signatures or using secret keys.

Example:

# Bad practice (DO NOT DO THIS)
const token = "hardcoded_secret_token";

# Good practice
export SLOP_JWT_SECRET=your_secret_token

🔄 Provider Registration¶

• Always register factories properly: When adding a new Provider, make sure to register its factory so that the server can instantiate it dynamically.

• Test provider routes: Ensure that all API routes and webhooks for your Provider are tested before deployment.

Checklist:

• ✅ Factory registered in RegisterProvider().
• ✅ Tools exposed via GetTools().
• ✅ Routes mounted dynamically.
• ✅ Jobs scheduled as needed.

⚠️ System Limitations¶

• Long-running Jobs: Jobs that run for a long time (e.g., over 5–10 minutes) should be monitored carefully.

• If a job hangs or fails, use the /api/jobs/status endpoint to check and manage it.

• Webhook Error Handling: Webhook delivery can fail if:

• The receiver is unavailable.

• The payload is invalid.

Always implement retry logic and log errors for debugging.

Metaphor: If a pizza order takes too long, keep checking the oven and have a plan B!

🚀 Performance Tips¶

• PostgreSQL Pub/Sub: The server uses PostgreSQL's Pub/Sub to distribute events internally.

• ✅ This allows the system to scale horizontally across multiple instances.

• ✅ It keeps notifications and events synchronized in real-time.

• Optimize Provider performance:

• Minimize external API calls where possible.

• Cache frequent results (e.g., email list retrieval).

• Job queue management:

• Use a reasonable number of workers.

• Balance between throughput and resource usage.

Common Pitfalls (and How to Avoid Them)¶

Quick Recap¶

• 🔒 Security: Always protect your secrets; validate webhooks.
• 🧱 Provider Setup: Register and test your Providers properly.
• 🕒 Limits: Monitor long-running jobs and handle webhook errors.
• 🚀 Performance: Use Pub/Sub and scale smartly.