owlen/docs/architecture.md

# Owlen Architecture

This document provides a high-level overview of the Owlen architecture. Its purpose is to help developers understand how the different parts of the application fit together.

## Core Concepts

The architecture is designed to be modular and extensible, centered around a few key concepts:

-   **Providers**: Connect to various LLM APIs (Ollama, OpenAI, etc.).
-   **Session**: Manages the conversation history and state.
-   **TUI**: The terminal user interface, built with `ratatui`.
-   **Events**: A system for handling user input and other events.

## Component Interaction

A simplified diagram of how components interact:

```
[User Input] -> [Event Loop] -> [Session Controller] -> [Provider]
      ^                                                     |
      |                                                     v
[TUI Renderer] <------------------------------------ [API Response]
```

1.  **User Input**: The user interacts with the TUI, generating events (e.g., key presses).
2.  **Event Loop**: The main event loop in `owlen-tui` captures these events.
3.  **Session Controller**: The event is processed, and if it's a prompt, the session controller sends a request to the current provider.
4.  **Provider**: The provider formats the request for the specific LLM API and sends it.
5.  **API Response**: The LLM API returns a response.
6.  **TUI Renderer**: The response is processed, the session state is updated, and the TUI is re-rendered to display the new information.

## Crate Breakdown

-   `owlen-core`: Defines the core traits and data structures, like `Provider` and `Session`. Also contains the MCP client implementation.
-   `owlen-tui`: Contains all the logic for the terminal user interface, including event handling and rendering.
-   `owlen-cli`: The command-line entry point, responsible for parsing arguments and starting the TUI.
-   `owlen-mcp-llm-server`: MCP server that wraps Ollama providers and exposes them via the Model Context Protocol.
-   `owlen-mcp-server`: Generic MCP server for file operations and resource management.
-   `owlen-ollama`: Direct Ollama provider implementation (legacy, used only by MCP servers).

## MCP Architecture (Phase 10)

As of Phase 10, OWLEN uses a **MCP-only architecture** where all LLM interactions go through the Model Context Protocol:

```
[TUI/CLI] -> [RemoteMcpClient] -> [MCP LLM Server] -> [Ollama Provider] -> [Ollama API]
```

### Benefits of MCP Architecture

1. **Separation of Concerns**: The TUI/CLI never directly instantiates provider implementations.
2. **Process Isolation**: LLM interactions run in a separate process, improving stability.
3. **Extensibility**: New providers can be added by implementing MCP servers.
4. **Multi-Transport**: Supports STDIO, HTTP, and WebSocket transports.
5. **Tool Integration**: MCP servers can expose tools (file operations, web search, etc.) to the LLM.

### MCP Communication Flow

1. **Client Creation**: `RemoteMcpClient::new()` spawns an MCP server binary via STDIO.
2. **Initialization**: Client sends `initialize` request to establish protocol version.
3. **Tool Discovery**: Client calls `tools/list` to discover available LLM operations.
4. **Chat Requests**: Client calls the `generate_text` tool with chat parameters.
5. **Streaming**: Server sends progress notifications during generation, then final response.
6. **Response Handling**: Client skips notifications and returns the final text to the caller.

### Cloud Provider Support

For Ollama Cloud providers, the MCP server accepts an `OLLAMA_URL` environment variable:

```rust
let env_vars = HashMap::from([
    ("OLLAMA_URL".to_string(), "https://cloud-provider-url".to_string())
]);
let config = McpServerConfig {
    command: "path/to/owlen-mcp-llm-server",
    env: env_vars,
    transport: "stdio",
    ...
};
let client = RemoteMcpClient::new_with_config(&config)?;
```

## Session Management

The session management system is responsible for tracking the state of a conversation. The two main structs are:

-   **`Conversation`**: Found in `owlen-core`, this struct holds the messages of a single conversation, the model being used, and other metadata. It is a simple data container.
-   **`SessionController`**: This is the high-level controller that manages the active conversation. It handles:
    -   Storing and retrieving conversation history via the `ConversationManager`.
    -   Managing the context that is sent to the LLM provider.
    -   Switching between different models.
    -   Sending requests to the provider and handling the responses (both streaming and complete).

When a user sends a message, the `SessionController` adds the message to the current `Conversation`, sends the updated message list to the `Provider`, and then adds the provider's response to the `Conversation`.

## Event Flow

The event flow is managed by the `EventHandler` in `owlen-tui`. It operates in a loop, waiting for events and dispatching them to the active application (`ChatApp` or `CodeApp`).

1.  **Event Source**: Events are primarily generated by `crossterm` from user keyboard input. Asynchronous events, like responses from a `Provider`, are also fed into the event system via a `tokio::mpsc` channel.
2.  **`EventHandler::next()`**: The main application loop calls this method to wait for the next event.
3.  **Event Enum**: Events are defined in the `owlen_tui::events::Event` enum. This includes `Key` events, `Tick` events (for UI updates), and `Message` events (for async provider data).
4.  **Dispatch**: The application's `run` method matches on the `Event` type and calls the appropriate handler function (e.g., `dispatch_key_event`).
5.  **State Update**: The handler function updates the application state based on the event. For example, a key press might change the `InputMode` or modify the text in the input buffer.
6.  **Re-render**: After the state is updated, the UI is re-rendered to reflect the changes.

## TUI Rendering Pipeline

The TUI is rendered on each iteration of the main application loop in `owlen-tui`. The process is as follows:

1.  **`tui.draw()`**: The main loop calls this method, passing the current application state.
2.  **`Terminal::draw()`**: This method, from `ratatui`, takes a closure that receives a `Frame`.
3.  **UI Composition**: Inside the closure, the UI is built by composing `ratatui` widgets. The root UI is defined in `owlen_tui::ui::render`, which builds the main layout and calls other functions to render specific components (like the chat panel, input box, etc.).
4.  **State-Driven Rendering**: Each rendering function takes the current application state as an argument. It uses this state to decide what and how to render. For example, the border color of a panel might change if it is focused.
5.  **Buffer and Diff**: `ratatui` does not draw directly to the terminal. Instead, it renders the widgets to an in-memory buffer. It then compares this buffer to the previous buffer and only sends the necessary changes to the terminal. This is highly efficient and prevents flickering.