Skip to content

Project Structure

Understanding the project structure helps developers navigate the codebase efficiently and understand how different parts work together.

🌳 Project Tree Overview

This is a conceptual overview. Actual file names and sub-directories might vary slightly based on evolution, but the core components remain.

├── cmd/
│   ├── mfo-client-service/  # Example main application for the client service
│   ├── taskflow-visualizer/ # Utility to visualize taskflows
│   └── yaml-validator/      # Utility to validate YAML configurations
├── internal/
│   ├── api/                 # Specialized MFO API client implementations & interfaces
│   │   ├── interfaces.go    # Defines interfaces for API clients (Chat, Resource, Event etc.)
│   │   ├── event_client.go  # Implementation for EventClientInterface
│   │   ├── chat_client.go   # Implementation for ChatClientInterface
│   │   └── ...              # Other specialized clients
│   ├── auth/                # Authentication providers and logic
│   │   ├── auth_provider.go # Defines AuthProvider interface
│   │   └── jwt_auth.go      # Example JWT based AuthProvider implementation
│   ├── client/              # Core HTTP BaseClient for API communication
│   │   └── client.go        # Implements the BaseClient
│   ├── handlers/            # HTTP handlers for incoming webhooks/events
│   │   └── webhook_handler.go
│   ├── models/              # Data structures (API requests/responses, taskflow definitions)
│   │   ├── event.go
│   │   ├── job.go
│   │   ├── api_error.go
│   │   └── flow_definition.go
│   ├── taskflow/            # Taskflow engine components (registry, builder, executor)
│   │   ├── registry.go
│   │   ├── builder.go
│   │   ├── executor.go
│   │   └── loader.go
│   ├── config/              # Configuration loading and management
│   │   └── config.go
├── examples/                # Example configurations and runnable scenarios
│   └── simple-webhook-flow/
├── docs/                    # Documentation files
├── pkg/                     # Shared libraries or utilities (if any, less common for internal)
// ... (other project files like go.mod, go.sum, Makefile, etc.)

🔑 Key Components Explained

/cmd: Entry Points

Metaphor: 🖥️ The Control Panel

This folder contains main application packages that serve as entry points for running the MFO Client service or related utility tools (e.g., configuration validators, taskflow visualizers).

Example:

  • mfo-client-service/main.go: The main application to start the webhook listener and initialize client services.
  • yaml-validator/main.go: A tool to validate MFO Client YAML configuration files or taskflow definitions.

/internal/client: Core API Client

Metaphor: 📞 The Universal Communicator

This package houses the BaseClient (client.go), which is the foundational component for all HTTP communication with the MFO server. It handles request construction, execution, response parsing, and integration with an AuthProvider for adding authentication to requests. It's also where global configurations like timeouts, retry policies, and circuit breakers for API calls are applied.

Files of Interest:

  • client.go: Contains the BaseClient struct and its methods (e.g., Get, Post, Put, Delete).

/internal/auth: Authentication Providers

Metaphor: 🔑 The Security Guard & Keymaster

This package is responsible for authentication. It defines the AuthProvider interface and provides implementations for various authentication strategies (e.g., API token, OAuth2, JWT). The BaseClient uses an AuthProvider to obtain authentication credentials (like tokens) to include in API requests.

Files of Interest:

  • auth_provider.go: Defines the AuthProvider interface (e.g., GetAuthHeader()).
  • jwt_auth.go (example): An implementation for JWT-based authentication, perhaps including login methods.

/internal/api: Specialized API Clients

Metaphor: 📞 Departmental Phones

Building upon the BaseClient, this package defines interfaces (e.g., EventClientInterface, ChatClientInterface in interfaces.go) and provides concrete implementations for interacting with specific domains of the MFO server API. Each specialized client (e.g., EventClient, ChatClient) uses the BaseClient to make its HTTP calls, focusing only on the logic relevant to its domain.

Files of Interest:

  • interfaces.go: Defines all specialized client interfaces.
  • event_client.go: Implements EventClientInterface for event-related API calls.
  • resource_client.go: Implements ResourceClientInterface for resource management calls.

/internal/handlers: Incoming Event Processors

Metaphor: 🛎️ The Reception Desk Team

This package handles incoming HTTP requests, primarily webhooks. Handlers parse and validate these requests before initiating further processing, such as forwarding the event to the MFO server (using an appropriate specialized API client from /internal/api) or triggering a local taskflow.

Example (webhook_handler.go):

// internal/handlers/webhook_handler.go
package handlers

import (
    "context"
    "encoding/json"
    "log"
    "net/http"
    "time"

    "your_project_path/internal/api"      // For EventClientInterface
    "your_project_path/internal/models"   // For your Event struct
)

func WebhookHandler(eventClient api.EventClientInterface, webhookSecret string) http.HandlerFunc {
    return func(w http.ResponseWriter, r *http.Request) {
        // Signature verification (using webhookSecret) should happen here first!
        // ... (signature verification logic omitted for brevity) ...

        var receivedEvent models.Event
        if err := json.NewDecoder(r.Body).Decode(&receivedEvent); err != nil {
            http.Error(w, "Invalid data", http.StatusBadRequest)
            return
        }
        defer r.Body.Close()

        log.Printf("Webhook received: %+v", receivedEvent)

        // Asynchronously forward using the injected EventClient
        go func(eventToForward models.Event) {
            ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
            defer cancel()
            _, err := eventClient.SendEvent(ctx, eventToForward)
            if err != nil {
                log.Printf("Error forwarding event via EventClient: %v", err)
            }
        }(receivedEvent)

        w.WriteHeader(http.StatusAccepted)
    }
}

/internal/models: Data Blueprints

Metaphor: 🗂️ Blueprint Drawer

This package defines all Go data structures used throughout the application. This includes: * Structs for API requests and responses (e.g., models.ChatRequest, models.Resource). * Internal representations of events, jobs, and other entities. * Taskflow definitions (models.FlowDefinition, models.TaskDefinition). * Custom error types like models.APIError. These models are crucial for type safety and ensuring consistency with the MFO server API (as defined in Section 2.5 of the main MFO Orchestrator documentation).

Files of Interest:

  • event.go: Defines the Event struct and related types.
  • job.go: Defines Job related structs.
  • api_error.go: Defines APIError and other error-related structs.
  • flow_definition.go: Defines structs for parsing YAML taskflow definitions.

/internal/taskflow: Workflow Engine Components

Metaphor: ⚙️ The Customizable Assembly Line

This package contains the MFO client's specific components for its local taskflow engine, built upon go-taskflow. It includes: * registry.go: The TaskRegistry for mapping task types from YAML to Go functions. * builder.go: The Builder for constructing executable gtf.Flow objects from models.FlowDefinition. * executor.go: The FlowExecutor for managing the execution of taskflows, including context setup (e.g., injecting MFO API clients) and concurrency. * loader.go: Utilities for loading and parsing YAML flow definitions into models.FlowDefinition.

These components work together to enable the definition, construction, and execution of local workflows.

/internal/config: Configuration Management

Metaphor: 🔩 The Settings Panel

This package is responsible for loading, parsing, and providing access to the client's configuration, typically from a YAML file (e.g., config.yaml). It defines structs that map to the configuration file structure, covering API client settings (URLs, timeouts, retry policies), webhook listener settings, and taskflow engine parameters.

Files of Interest:

  • config.go: Defines configuration structs and the LoadConfig function.

/examples: Demo Scenarios & Configurations

Metaphor: 🧪 The Sandbox & Tutorials

This folder contains ready-to-run examples and sample configurations demonstrating how to set up and use the MFO Client, its taskflow capabilities, and integrations.

🗺️ Diagram – Component Interactions

This diagram illustrates how the key internal components interact. Note that cmd/* applications would initialize and wire these components together.

graph TD
    subgraph "External Interfaces"
        direction LR
        WebhookSource[Webhook Source] --> WH[handlers.WebhookHandler]
        ConfigFile[config.yaml] --> CM[config.LoadConfig]
    end

    subgraph "MFO Client Core Logic (internal)"
        direction TD
        CM --> AppInit[Application Initialization]
        AppInit --> BC[client.BaseClient]
        AppInit --> AP[auth.AuthProvider]
        AppInit --> TFExec[taskflow.FlowExecutor]
        AppInit --> Reg[taskflow.TaskRegistry]
        AppInit --> Build[taskflow.Builder]
        AppInit --> Load[taskflow.Loader]

        WH --> EventProc[Event Processing Logic]
        EventProc --> SpecializedClientUser{Use Specialized API Client OR Trigger Taskflow}

        SpecializedClientUser -- Uses --> SC[api.SpecializedClient]
        SpecializedClientUser -- Triggers --> TFExec

        SC -- Uses --> BC
        BC -- Uses --> AP
        AP -- Authenticates --> MFOServerAPI[MFO Server API]
        BC -- Communicates --> MFOServerAPI

        TFExec -- Uses --> Reg
        TFExec -- Uses --> Build
        TFExec -- Uses --> Load
        Load --> FlowDef[models.FlowDefinition]
        Build -- Creates Task --> TaskFunc[models.TaskFunc]
        TaskFunc -- May Use --> SCUser{Uses Specialized API Client}
        SCUser --> SC
    end

    MFOServerAPI

    classDef internal fill:#f9f,stroke:#333,stroke-width:2px;
    class AppInit,BC,AP,TFExec,Reg,Build,Load,WH,EventProc,SpecializedClientUser,SC,TaskFunc,SCUser internal;

    classDef external fill:#ccf,stroke:#333,stroke-width:2px;
    class WebhookSource,ConfigFile,CM,MFOServerAPI external

This revised structure provides a clearer separation of concerns, making the MFO Client more modular, maintainable, and testable.

By understanding the project structure and the role of each package, you'll be able to navigate, extend, and maintain the Client MindFlight AI component with confidence.