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 `LLMProvider` abstraction, routing, configuration, session state, encryption, and the MCP client layer. This crate is UI-agnostic and must not depend on concrete providers, terminals, or blocking I/O.
-   `owlen-tui`: Hosts all terminal UI behaviour (event loop, rendering, input modes) while delegating business logic and provider access back to `owlen-core`.
-   `owlen-cli`: Small entry point that parses command-line options, resolves configuration, selects providers, and launches either the TUI or headless agent flows by calling into `owlen-core`.
-   `owlen-mcp-llm-server`: Runs concrete providers (e.g., Ollama) behind an MCP boundary, exposing them as `generate_text` tools. This crate owns provider-specific wiring and process sandboxing.
-   `owlen-mcp-server`: Generic MCP server for file operations and resource management.
-   `owlen-ollama`: Direct Ollama provider implementation (legacy, used only by MCP servers).

### Boundary Guidelines

- **owlen-core**: The dependency ceiling for most crates. Keep it free of terminal logic, CLIs, or provider-specific HTTP clients. New features should expose traits or data types here and let other crates supply concrete implementations.
- **owlen-cli**: Only orchestrates startup/shutdown. Avoid adding business logic; when a new command needs behaviour, implement it in `owlen-core` or another library crate and invoke it from the CLI.
- **owlen-mcp-llm-server**: The only crate that should directly talk to Ollama (or other provider processes). TUI/CLI code communicates with providers exclusively through MCP clients in `owlen-core`.

## 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)?;
```

## Vim Mode State Machine

The TUI follows a Vim-inspired modal workflow. Maintaining the transitions keeps keyboard handling predictable:

- **Normal → Insert**: triggered by keys such as `i`, `a`, or `o`; pressing `Esc` returns to Normal.
- **Normal → Visual**: `v` enters visual selection; `Esc` or completing a selection returns to Normal.
- **Normal → Command**: `:` opens command mode; executing a command or cancelling with `Esc` returns to Normal.
- **Normal → Auxiliary modes**: `?` (help), `:provider`, `:model`, and similar commands open transient overlays that always exit back to Normal once dismissed.
- **Insert/Visual/Command → Normal**: pressing `Esc` always restores the neutral state.

The status line shows the active mode (for example, “Normal mode • Press F1 for help”), which doubles as a quick regression check during manual testing.

## 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.