Lighthouse AI Architecture

​

Architecture Overview

​

Three-Tier Architecture

1. Frontend (Next.js): Chat interface, message rendering, model selection
2. API Route: Request handling, authentication, stream transformation
3. Langchain Agent: LLM orchestration, tool calling through MCP

​

Request Flow

1. User Submits a Message. The chat component (ui/components/lighthouse/chat.tsx) captures the user’s question (e.g., “What are my critical findings in AWS?”) and sends it as an HTTP POST request to the backend API route.
2. Authentication and Context Assembly. The API route (ui/app/api/lighthouse/analyst/route.ts) validates the user’s session, extracts the JWT token (stored via auth-context.ts), and gathers context including the tenant’s business context and current security posture data (assembled in data.ts).
3. Agent Initialization. The workflow orchestrator (ui/lib/lighthouse/workflow.ts) creates a Langchain agent configured with:
   • The selected LLM, instantiated through the factory (llm-factory.ts)
   • A system prompt containing available tools and instructions (system-prompt.ts)
   • Two meta-tools (describe_tool and execute_tool) for accessing Prowler data
4. LLM Reasoning and Tool Calling. The agent sends the conversation to the LLM, which decides whether to respond directly or call tools to fetch data. When tools are needed, the meta-tools in ui/lib/lighthouse/tools/meta-tool.ts interact with the MCP client (mcp-client.ts) to:
   • First call describe_tool to understand the tool’s parameters
   • Then call execute_tool to retrieve data from the MCP Server
   • Continue reasoning with the returned data
5. Streaming Response. As the LLM generates its response, the stream handler (ui/lib/lighthouse/analyst-stream.ts) transforms Langchain events into UI-compatible messages and streams tokens back to the browser in real-time using Server-Sent Events. The stream includes both text tokens and tool execution events (displayed as “chain of thought”).
6. Message Rendering. The frontend receives the stream and renders it through message-item.tsx with markdown formatting. Any tool calls that occurred during reasoning are displayed via chain-of-thought-display.tsx.

​

Frontend Components

​

Core Components

​

Configuration Components

​

Supporting Components

​

Library Code

​

Workflow Orchestrator

• Initializing the Langchain agent with system prompt and tools
• Loading tenant configuration (default provider, model, business context)
• Creating the LLM instance through the factory
• Generating dynamic tool listings from available MCP tools

// Simplified workflow initialization
export async function initLighthouseWorkflow(runtimeConfig?: RuntimeConfig) {
  await initializeMCPClient();

  const toolListing = generateToolListing();
  const systemPrompt = LIGHTHOUSE_SYSTEM_PROMPT_TEMPLATE.replace(
    "{{TOOL_LISTING}}",
    toolListing,
  );

  const llm = createLLM({
    provider: providerType,
    model: modelId,
    credentials,
    // ...
  });

  return createAgent({
    model: llm,
    tools: [describeTool, executeTool],
    systemPrompt,
  });
}

​

MCP Client Manager

• Connection Management: Retry logic with configurable attempts and delays
• Tool Discovery: Fetches available tools from MCP server on initialization
• Authentication Injection: Automatically adds JWT tokens to prowler_app_* tool calls
• Reconnection: Supports forced reconnection after server restarts

• MAX_RETRY_ATTEMPTS: 3 connection attempts
• RETRY_DELAY_MS: 2000ms between retries
• RECONNECT_INTERVAL_MS: 5 minutes before retry after failure

// Authentication injection for Prowler App tools
private handleBeforeToolCall = ({ name, args }) => {
  // Only inject auth for prowler_app_* tools (user-specific data)
  if (!name.startsWith("prowler_app_")) {
    return { args };
  }

  const accessToken = getAuthContext();
  return {
    args,
    headers: { Authorization: `Bearer ${accessToken}` },
  };
};

​

Meta-Tools

​

Additional Library Modules

​

API Route

1. Request Parsing: Extracts messages, model, and provider from request body
2. Authentication: Validates session and extracts access token
3. Context Assembly: Gathers business context and current data
4. Agent Initialization: Creates Langchain agent with runtime configuration
5. Stream Processing: Transforms agent events to UI-compatible format
6. Error Handling: Captures errors with Sentry integration

export async function POST(req: Request) {
  const { messages, model, provider } = await req.json();

  const session = await auth();
  if (!session?.accessToken) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }

  return await authContextStorage.run(accessToken, async () => {
    const app = await initLighthouseWorkflow(runtimeConfig);
    const agentStream = app.streamEvents({ messages }, { version: "v2" });

    // Transform stream events to UI format
    const stream = new ReadableStream({
      async start(controller) {
        for await (const streamEvent of agentStream) {
          // Handle on_chat_model_stream, on_tool_start, on_tool_end, etc.
        }
      },
    });

    return createUIMessageStreamResponse({ stream });
  });
}

​

Backend Components

​

Database Models

​

LighthouseProviderConfiguration

• provider_type: openai, bedrock, or openai_compatible
• credentials: Encrypted JSON containing API keys or AWS credentials
• base_url: Custom endpoint for OpenAI-compatible providers
• is_active: Connection validation status

​

LighthouseTenantConfiguration

• business_context: Optional context for personalized responses
• default_provider: Default LLM provider type
• default_models: JSON mapping provider types to default model IDs

​

LighthouseProviderModels

• model_id: Provider-specific model identifier
• model_name: Human-readable display name
• default_parameters: Optional model-specific parameters

​

Background Jobs

​

check_lighthouse_provider_connection

• OpenAI: Lists models via client.models.list()
• Bedrock: Lists foundation models via bedrock_client.list_foundation_models()
• OpenAI-compatible: Lists models via custom base URL

​

refresh_lighthouse_provider_models

• Fetches current model catalog from provider
• Filters out non-chat models (DALL-E, Whisper, TTS, embeddings)
• Upserts model records in LighthouseProviderModels
• Removes stale models no longer available

EXCLUDED_OPENAI_MODEL_PREFIXES = (
    "dall-e", "whisper", "tts-", "sora",
    "text-embedding", "text-moderation",
    # Legacy models
    "text-davinci", "davinci", "curie", "babbage", "ada",
)

​

MCP Server Integration

​

Tool Namespacing

​

Authentication Flow

1. User authenticates with Prowler App, receiving a JWT token
2. Token is stored in session and propagated via authContextStorage
3. MCP client injects Authorization: Bearer <token> header for prowler_app_* calls
4. MCP Server validates token and applies RLS filtering

​

Tool Execution Pattern

Agent needs data → describe_tool("prowler_app_search_findings")
    → Returns parameter schema → execute_tool with parameters
    → MCP client adds auth header → MCP Server executes
    → Results returned to agent → Agent continues reasoning

​

Extension Points

​

Adding New LLM Providers

1. Frontend: Update ui/lib/lighthouse/llm-factory.ts with provider-specific initialization
2. Backend: Add provider type to LighthouseProviderConfiguration.LLMProviderChoices
3. Jobs: Add credential extraction and model fetching in lighthouse_providers.py
4. UI: Add connection workflow in ui/components/lighthouse/workflow/

​

Modifying System Prompt

​

Adding Stream Events

• on_chat_model_stream: Token-by-token text streaming
• on_chat_model_end: Model completion with tool call detection
• on_tool_start: Tool execution started
• on_tool_end: Tool execution completed

​

Adding MCP Tools

​

Configuration

​

Environment Variables

​

Database Configuration

• OpenAI: {"api_key": "sk-..."}
• Bedrock: {"access_key_id": "...", "secret_access_key": "...", "region": "us-east-1"} or {"api_key": "...", "region": "us-east-1"}
• OpenAI-compatible: {"api_key": "..."} with base_url field

​

Tenant Configuration

{
    "business_context": "Optional organization context for personalized responses",
    "default_provider": "openai",
    "default_models": {
        "openai": "gpt-4o",
        "bedrock": "anthropic.claude-3-5-sonnet-20240620-v1:0"
    }
}

​

Related Documentation