✅ MindFlight AI Server – Document Outline (Synthesized)¶

1️⃣ Introduction¶

• 🎯 Purpose of this document:

• Explain the role of the server in the MindFlight AI ecosystem.

• Understand how it orchestrates workflows and automates tasks.

• 🧭 Key concepts:

• Workflow orchestration.

• Providers & Clients.
• Background job manager.
• Notifications and Webhooks.

• 📊 Mermaid diagram:

• Present a diagram of the main interactions: Client → Server → Provider.

2️⃣ Core Concepts¶

• 🔧 Workflow Orchestration:

• Define how the server executes steps in a defined order.

• 🛠️ Providers:

• Present the role of Providers as 'bridges' to external services.

• ⏳ Job Manager:

• Explain asynchronous task management.

• 🔔 Notifications & Events:

• Difference between internal notifications (pub/sub) and external notifications (webhooks).

• 🗄️ Memory & Resources:

• How the server stores session data (key/value memory) and manages files.

3️⃣ Architecture & Project Structure¶

• 🗂️ Folder overview:

• /cmd

• /internal
• /pkg
• /config

• 🔍 How it works:

• How the server starts, loads the configuration, and initialises the Providers.

• 🔗 Client & Provider connection:

• Brief mention of the role of the two other MindFlight AI components (Clients and Providers).

4️⃣ Configuration¶

• 🛠️ config.yaml file:

• Key parameters to configure: ports, JWT secret, database.

• 🌍 Environment variables:

• Priority and examples of overriding via env vars.

• 🐳 Running via Docker:

• Example docker-compose.yml.

5️⃣ Go Patterns (Simplified for Developers)¶

👉 Short explanations and commented Go examples for each:

• ✅ Interface & Factory Pattern
• ✅ Adapter & Plug-in Pattern
• ✅ Middleware (Auth / Logging)
• ✅ Job Worker (asynchronous)
• ✅ Event-Driven (Watermill)
• ✅ Command-Line (Cobra)
• ✅ Config & Error Handling

6️⃣ Usage and Examples¶

• 🔑 Authentication:

• Complete example: login & token retrieval.

• 💬 Chat API:

• Example with curl.

• 🛠️ Execute a Provider tool:

• Calling a filesystem_list_files tool.

• 🗃️ Memory & Resources:

• Storage/retrieval example.

• 📊 Jobs & Notifications:

• Track a job and subscribe to an event.

7️⃣ Practical Use Cases¶

📧 Unipile Provider¶

• 🎯 Objective: manage email synchronisation.
• 🗺️ Flow: incoming webhook → internal event → background task.
• 🔎 Example: receiving an email → processing by the AI agent.

🔄 Webhook Management¶

• 🛠️ Overview of the two types:

• Incoming: Provider that receives notifications.

• Outgoing: Notifications to external clients.
• 📈 Recommended Mermaid diagram.
• 🔧 Example: subscribe to an email.processed event.

📝 Email Draft Processor Plugin¶

• 🎯 Objective: create email drafts from AI prompts.

• 🛠️ Flow:

• Launch a tool → prepare the draft → background job if necessary.

• 📂 Example: How to use the API to generate a draft + simplified Go code.

8️⃣ Best practices & Limitations¶

• ✅ Security:

• Never expose hard-coded tokens.

• 🔄 Providers:

• Always register factories correctly.

• ⚠️ Limitations:

• Long jobs must be monitored.

• Error handling in webhooks.

• 🚀 Performance:

• Use PostgreSQL Pub/Sub for efficient scaling.

9️⃣ Navigation & References¶

• 🔗 Link to:

• MindFlight AI Client Documentation.

• Provider Documentation.
• Additional modules (JobManager, Watermill).
• 📚 Glossary of key terms.
• 🚀 'To go further': Best practices for developing custom Providers.

10️⃣ Appendices¶

• ✅ Complete example of config.yaml.
• ✅ API endpoint cheat sheet.
• ✅ Schematic overview of the database.