> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Understanding the Olis system architecture and design principles

## System Overview

Olis is architected as a modern monorepo that combines multiple applications and shared libraries into a cohesive ecosystem. The architecture emphasizes modularity, type safety, and developer experience.

```mermaid theme={null}
graph TB
    User[User] --> Desktop[Desktop Client]
    User --> Extension[Chrome Extension]
    Desktop --> API[API Server]
    Extension --> API
    API --> RAG[RAG System]
    API --> DB[(Database)]
    Desktop --> Sidecar[Native Sidecar]
    RAG --> VectorDB[(Vector DB)]
```

## Monorepo Structure

<CodeGroup>
  ```bash Directory Layout theme={null}
  olis-monorepo/
  ├── apps/
  │   ├── electron-client/    # Desktop application
  │   ├── api-server/          # Python backend
  │   └── chrome-extension/    # Browser extension
  ├── libs/
  │   ├── shared-ui/          # Shared React components
  │   ├── shared-types/       # TypeScript type definitions
  │   └── native-modules/     # Rust native modules
  ├── infra/                  # Infrastructure configuration
  ├── scripts/                # Build and utility scripts
  └── docs/                   # Documentation
  ```
</CodeGroup>

## Component Architecture

### Desktop Client (Electron)

<Card title="Technology Stack" icon="desktop">
  * **Electron**: Native desktop wrapper
  * **Next.js**: React framework with App Router
  * **TypeScript**: Type-safe development
  * **Tailwind CSS**: Utility-first styling
  * **Native Sidecar**: Rust-based native modules
</Card>

**Key Features**:

* Static export for file:// protocol compatibility
* Hot module reloading in development
* Native integration via Rust sidecar
* Local LLM support via bundled `llama-server`

```mermaid theme={null}
graph LR
    Main[Electron Main] --> Renderer[Next.js Renderer]
    Main --> Sidecar[Rust Sidecar]
    Renderer --> API[Backend API]
    Renderer --> LLM[Local LLM]
```

### API Server (Python)

<Card title="Technology Stack" icon="server">
  * **FastAPI**: Modern Python web framework
  * **Uvicorn**: ASGI server
  * **RAG Pipeline**: Document retrieval and generation
  * **Vector Database**: Semantic search
</Card>

**Key Features**:

* RESTful API endpoints
* Real-time document processing
* RAG (Retrieval-Augmented Generation) system
* Redis caching layer
* Docker containerization

**API Architecture**:

```python theme={null}
# Main API structure
api-server/
├── src/
│   ├── backend/
│   │   ├── routers/       # API route handlers
│   │   ├── utils/         # Utility functions
│   │   │   └── retrievers/  # RAG components
│   │   └── models/        # Data models
│   └── main.py           # Application entry
└── tests/
    └── integration_tests/  # API tests
```

### Chrome Extension

<Card title="Technology Stack" icon="chrome">
  * **Manifest V3**: Modern extension API
  * **TypeScript**: Type-safe extension code
  * **Webpack**: Module bundling
</Card>

**Key Features**:

* Context menu integration
* Page content extraction
* Background service worker
* Communication with API server

## Data Flow

### Intent Detection Pipeline

<Steps>
  <Step title="User Input">
    User types or speaks query in the desktop client or extension
  </Step>

  <Step title="Intent Analysis">
    Local or remote LLM analyzes the input to detect user intent:

    * **Local Mode**: Bundled llama-server with GGUF model
    * **Remote Mode**: Hosted LLM via API
    * **NLP Fallback**: Heuristic-based detection
  </Step>

  <Step title="Context Retrieval">
    RAG system retrieves relevant context from:

    * Document store
    * Vector database (semantic search)
    * User's configured document folder
  </Step>

  <Step title="Response Generation">
    Combined context and query generate intelligent response
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant U as User
    participant D as Desktop Client
    participant I as Intent Detection
    participant R as RAG System
    participant L as LLM

    U->>D: Input Query
    D->>I: Analyze Intent
    I->>R: Request Context
    R-->>I: Return Documents
    I->>L: Generate Response
    L-->>D: Return Answer
    D-->>U: Display Result
```

## Technology Decisions

### Nx Monorepo

<Card title="Why Nx?" icon="diagram-project">
  Nx provides:

  * Efficient task orchestration
  * Dependency graph visualization
  * Incremental builds
  * Code generation
  * Plugin ecosystem
</Card>

**Commands**:

```bash theme={null}
# Run single app
nx serve electron-client

# Build all apps
nx run-many --target=build --all

# View dependency graph
nx graph
```

### pnpm Workspace

<Card title="Why pnpm?" icon="box">
  pnpm offers:

  * Efficient disk space usage (content-addressable store)
  * Fast installation speeds
  * Strict dependency isolation
  * Monorepo workspace support
</Card>

### Rust Native Modules

<Card title="Why Rust?" icon="gear">
  Rust provides:

  * Memory safety without garbage collection
  * Zero-cost abstractions
  * Performance for compute-intensive tasks
  * Safe FFI with Node.js via napi-rs
</Card>

**Use Cases**:

* File system operations
* Encryption/decryption
* Data parsing and transformation
* Native OS integrations

## Deployment Architecture

### Desktop Client

```mermaid theme={null}
graph LR
    Source[Source Code] --> Build[electron-builder]
    Build --> Windows[Windows Installer]
    Build --> Mac[macOS DMG]
    Build --> Linux[Linux AppImage]
```

**Artifacts**:

* Windows: NSIS installer (.exe)
* macOS: DMG, ZIP
* Linux: AppImage, Snap, DEB

### API Server

```mermaid theme={null}
graph LR
    Source[Source Code] --> Docker[Docker Image]
    Docker --> Registry[Container Registry]
    Registry --> K8s[Kubernetes]
    K8s --> Prod[Production]
```

**Infrastructure**:

* Containerized with Docker
* Orchestrated with Kubernetes
* Redis for caching
* Vector database for RAG
* Load balancing and auto-scaling

## Security Architecture

<CardGroup cols={2}>
  <Card title="Desktop Client" icon="shield-halved">
    * Context isolation enabled
    * Secure IPC communication
    * Native keychain integration (keytar)
    * Sandboxed renderer process
  </Card>

  <Card title="API Server" icon="lock">
    * JWT authentication
    * Rate limiting
    * CORS configuration
    * Input validation
    * Secure secret management
  </Card>
</CardGroup>

## Performance Considerations

### Desktop Client

* **Static Export**: Eliminates Next.js server overhead
* **Lazy Loading**: Components loaded on demand
* **Code Splitting**: Reduced initial bundle size
* **Native Modules**: Performance-critical paths in Rust

### API Server

* **Redis Caching**: Reduced database queries
* **Vector Search**: Efficient semantic similarity
* **Async I/O**: Non-blocking request handling
* **Connection Pooling**: Database optimization

### RAG System

* **Batch Processing**: Bulk document ingestion
* **Incremental Updates**: Only process changes
* **Embedding Cache**: Reuse computed embeddings
* **Query Optimization**: Efficient retrieval strategies

## Development Workflow

```mermaid theme={null}
graph LR
    Dev[Developer] --> Local[Local Dev]
    Local --> Test[Run Tests]
    Test --> Lint[Lint Code]
    Lint --> PR[Create PR]
    PR --> CI[CI/CD Pipeline]
    CI --> Review[Code Review]
    Review --> Merge[Merge]
    Merge --> Deploy[Deploy]
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Electron Client" icon="desktop" href="/apps/electron-client">
    Deep dive into the desktop application
  </Card>

  <Card title="API Server" icon="server" href="/apps/api-server">
    Explore the backend architecture
  </Card>

  <Card title="Development Setup" icon="code" href="/development/setup">
    Set up your development environment
  </Card>

  <Card title="Contributing" icon="hand-holding-heart" href="/development/contributing">
    Learn how to contribute
  </Card>
</CardGroup>