# Architecture Overview

Kollabor CLI is a monorepo containing 8 extracted packages plus the core
orchestration layer. Everything is event-driven with hooks at every level.

## Monorepo Structure

```
kollabor-cli/
├── kollabor/                    # Core orchestration
│   ├── application.py           # Main TerminalLLMChat entry point
│   ├── cli.py                   # CLI argument parsing
│   ├── commands/                # Slash command system
│   ├── llm/                     # LLM orchestration layer
│   ├── fullscreen/              # Fullscreen command integration
│   ├── logging/                 # Logging configuration
│   └── config_hooks.py          # JSON hook loading
│
├── packages/
│   ├── kollabor-ai/             # LLM services
│   ├── kollabor-agent/          # Agent runtime
│   ├── kollabor-tui/            # Terminal UI
│   ├── kollabor-events/         # Event bus + hooks
│   ├── kollabor-config/         # Configuration management
│   ├── kollabor-plugins/        # Plugin framework
│   ├── kollabor-engine/         # HTTP server (future)
│   └── kollabor-webui/          # Web UI (future)
│
├── plugins/                     # Plugin implementations
└── bundles/agents/              # Agent definitions
```

## Package Summary

| Package | Purpose | Key Exports |
|---------|---------|-------------|
| kollabor-ai | LLM API, conversation, profiles | ProfileManager, ConversationManager, APICommunicationService |
| kollabor-agent | Tool execution, MCP, shell | AgentManager, ToolExecutor, MCPIntegration |
| kollabor-tui | Terminal rendering, input, widgets | TerminalRenderer, InputHandler, EventDrivenRenderLoop |
| kollabor-events | Event bus, hook registry | EventBus, EventType, Hook |
| kollabor-config | Config loading, migration | ConfigService, ConfigManager |
| kollabor-plugins | Plugin discovery, loading | PluginRegistry, PluginFactory, KollaborPluginSDK |

## Data Flow

```
user input
    ↓
InputHandler (kollabor_tui)
    ↓
SlashCommandParser → CommandExecutor (kollabor/commands/)
    ↓
LLMService.process_stream() (kollabor/llm/)
    ↓
APICommunicationService (kollabor_ai)
    ↓
Provider (kollabor_ai/providers/)
    ↓
StreamingHandler → MessageDisplayService (kollabor_tui)
    ↓
MessageDisplayCoordinator → TerminalRenderer (kollabor_tui)
```

## Event Flow

Every action emits events through the EventBus:

```
event_bus.emit(EventType.USER_INPUT, context)
    ↓
HookRegistry.get_hooks(event_type)
    ↓
HookExecutor.execute() [priority order: SYSTEM(1000) → DISPLAY(10)]
    ↓
plugin.hook(context) → modified_context
    ↓
return modified_context to caller
```

Hook priorities:
- SYSTEM (1000): Core framework hooks
- SECURITY (900): Permission checks
- PREPROCESSING (500): Input transformation
- LLM (100): LLM request/response
- POSTPROCESSING (50): Response processing
- DISPLAY (10): UI rendering

## Import Paths

Core application (kollabor/):
```python
from kollabor.application import TerminalLLMChat
from kollabor.llm import LLMService
from kollabor.commands.registry import SlashCommandRegistry
```

LLM services (kollabor-ai):
```python
from kollabor_ai import ProfileManager, ConversationManager
from kollabor_ai.api_communication_service import APICommunicationService
from kollabor_ai.providers.registry import ProviderRegistry
```

Agent system (kollabor-agent):
```python
from kollabor_agent import AgentManager, ToolExecutor
from kollabor_agent.mcp_integration import MCPIntegration
from kollabor_agent.permissions.manager import PermissionManager  # Direct import
```

Terminal UI (kollabor-tui):
```python
from kollabor_tui import TerminalRenderer, InputHandler
from kollabor_tui.message_coordinator import MessageDisplayCoordinator
from kollabor_tui.terminal_state import get_terminal_size
from kollabor_tui.design_system import T, S, C, solid, TagBox
```

Event system (kollabor-events):
```python
from kollabor_events import EventBus, EventType, Hook, HookPriority
from kollabor_events.models import CommandResult, ConversationMessage
```

Configuration (kollabor-config):
```python
from kollabor_config import ConfigService, ConfigLoader, initialize_config
```

Plugin framework (kollabor-plugins):
```python
from kollabor_plugins import PluginRegistry, KollaborPluginSDK
from kollabor_plugins.base import BasePlugin
```

## Key Architectural Patterns

1. Event-Driven: All communication via EventBus hooks
2. Dependency Injection: Services registered on EventBus, accessed via get_service()
3. Facade Pattern: InputHandler, TerminalRenderer coordinate subsystems
4. Coordinator Pattern: MessageDisplayCoordinator prevents race conditions
5. Provider Pattern: Pluggable LLM providers (OpenAI, Anthropic, Gemini, etc.)
6. Plugin System: Dynamic discovery and loading from plugins/ directories

## Runtime Directory Structure

```
~/.kollabor-cli/
├── config.json              # User configuration
├── agents/                  # Global agent definitions
├── system_prompt/           # Global system prompts
└── projects/
    └── <encoded-path>/      # Project-specific data
        ├── conversations/   # JSONL logs
        ├── logs/            # Application logs
        └── .kollabor-cli/   # Local overrides
            ├── agents/      # Project-specific agents
            └── hooks.json   # Config hooks
```

Path encoding: `/home/user/myproject` → `home_user_myproject`
