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

# Development Setup

> Comprehensive development environment setup guide

## Overview

This guide covers setting up a complete development environment for the Olis monorepo, including all necessary tools, configurations, and best practices.

## System Requirements

<CardGroup cols={2}>
  <Card title="Operating Systems" icon="computer">
    * Windows 10/11
    * macOS 12+
    * Ubuntu 20.04+ / Debian-based Linux
  </Card>

  <Card title="Hardware" icon="microchip">
    * 8GB RAM minimum (16GB recommended)
    * 10GB free disk space
    * Multi-core processor
  </Card>
</CardGroup>

## Required Tools

### Core Development Tools

<Tabs>
  <Tab title="Node.js & pnpm">
    ```bash theme={null}
    # Install Node.js v18+ from https://nodejs.org/

    # Verify installation
    node --version  # Should be v18.0.0 or higher

    # Install pnpm globally
    npm install -g pnpm@9.15.4

    # Verify pnpm
    pnpm --version
    ```

    **Why pnpm?**

    * Efficient disk space usage
    * Faster installs than npm/yarn
    * Better monorepo support
    * Strict dependency resolution
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    # Install Python 3.9+ from https://python.org/

    # Verify installation
    python --version  # Should be 3.9.0 or higher

    # Install pip (usually included)
    python -m ensurepip --upgrade

    # Optional: Install poetry for better dependency management
    pip install poetry
    ```
  </Tab>

  <Tab title="Rust">
    ```bash theme={null}
    # Install Rust via rustup
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

    # On Windows, download from: https://rustup.rs/

    # Verify installation
    rustc --version
    cargo --version

    # Add common targets
    rustup target add wasm32-unknown-unknown
    ```
  </Tab>

  <Tab title="Git">
    ```bash theme={null}
    # Install Git from https://git-scm.com/

    # Verify installation
    git --version

    # Configure Git
    git config --global user.name "Your Name"
    git config --global user.email "your.email@example.com"

    # Optional: Set up SSH keys
    ssh-keygen -t ed25519 -C "your.email@example.com"
    ```
  </Tab>
</Tabs>

## IDE Setup

### Visual Studio Code (Recommended)

<Steps>
  <Step title="Install VS Code">
    Download from [code.visualstudio.com](https://code.visualstudio.com/)
  </Step>

  <Step title="Install recommended extensions">
    ```json theme={null}
    // .vscode/extensions.json
    {
      "recommendations": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-python.python",
        "rust-lang.rust-analyzer",
        "bradlc.vscode-tailwindcss",
        "nrwl.angular-console"
      ]
    }
    ```

    Install all at once:

    1. Open Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
    2. Type "Extensions: Show Recommended Extensions"
    3. Click "Install All"
  </Step>

  <Step title="Configure workspace settings">
    ```json theme={null}
    // .vscode/settings.json
    {
      "editor.formatOnSave": true,
      "editor.defaultFormatter": "esbenp.prettier-vscode",
      "editor.codeActionsOnSave": {
        "source.fixAll.eslint": true
      },
      "typescript.tsdk": "node_modules/typescript/lib",
      "python.linting.enabled": true,
      "python.formatting.provider": "black",
      "[rust]": {
        "editor.defaultFormatter": "rust-lang.rust-analyzer"
      }
    }
    ```
  </Step>
</Steps>

## Repository Setup

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/yourusername/olis-monorepo.git
    cd olis-monorepo
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    # Install JavaScript/TypeScript dependencies
    pnpm install

    # Install Python dependencies
    pip install -r requirements.txt

    # Or with poetry
    poetry install
    ```
  </Step>

  <Step title="Set up environment variables">
    ```bash theme={null}
    # Copy example env file
    cp .env.example .env

    # Edit with your values
    nano .env  # or use your preferred editor
    ```

    Key variables to configure:

    ```bash theme={null}
    # API Configuration
    OLIS_API_URL=http://localhost:8000

    # Intent Detection
    OLIS_INTENT_MODEL=phi3
    OLIS_INTENT_REMOTE_URL=http://localhost:11434

    # Document Folder
    OLIS_DOCS_FOLDER=/path/to/your/docs

    # Database (for API server)
    DATABASE_URL=postgresql://user:pass@localhost/olis
    REDIS_URL=redis://localhost:6379
    ```
  </Step>

  <Step title="Build native modules">
    ```bash theme={null}
    cd apps/electron-client
    pnpm run sidecar:build
    cd ../..
    ```
  </Step>

  <Step title="Verify installation">
    ```bash theme={null}
    # Run tests
    pnpm test

    # Lint code
    pnpm lint

    # View project graph
    pnpm nx graph
    ```
  </Step>
</Steps>

## Docker Setup (Optional)

For containerized development:

<Tabs>
  <Tab title="Docker Desktop">
    1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
    2. Verify installation:
       ```bash theme={null}
       docker --version
       docker-compose --version
       ```
    3. Start Docker Desktop
  </Tab>

  <Tab title="Docker Compose Services">
    ```yaml theme={null}
    # docker-compose.local.yml
    version: '3.8'

    services:
      api:
        build: ./apps/api-server
        ports:
          - "8000:8000"
        volumes:
          - ./apps/api-server:/app
        environment:
          - DATABASE_URL=${DATABASE_URL}
          - REDIS_URL=redis://redis:6379

      redis:
        image: redis:7-alpine
        ports:
          - "6379:6379"

      postgres:
        image: postgres:15-alpine
        ports:
          - "5432:5432"
        environment:
          POSTGRES_USER: olis
          POSTGRES_PASSWORD: olis
          POSTGRES_DB: olis

      vector-db:
        image: qdrant/qdrant
        ports:
          - "6333:6333"
    ```

    Start services:

    ```bash theme={null}
    docker-compose -f docker-compose.local.yml up -d
    ```
  </Tab>
</Tabs>

## Workflow Tools

### Nx Console

Nx Console provides a GUI for running Nx commands:

<Steps>
  <Step title="Install extension">
    Search for "Nx Console" in VS Code extensions
  </Step>

  <Step title="Access the console">
    Click the Nx icon in the sidebar or use Command Palette
  </Step>

  <Step title="Run tasks visually">
    * Select a project
    * Choose a task (build, serve, test, lint)
    * Click Run
  </Step>
</Steps>

### Pre-commit Hooks

Set up Git hooks for quality checks:

```bash theme={null}
# Install husky
pnpm add -D husky

# Initialize husky
pnpm husky install

# Add pre-commit hook
pnpm husky add .husky/pre-commit "pnpm lint-staged"
```

Configure lint-staged in `package.json`:

```json theme={null}
{
  "lint-staged": {
    "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"],
    "*.py": ["black", "isort"],
    "*.{json,md,yml,yaml}": ["prettier --write"]
  }
}
```

## Development Workflow

### Daily Development

```mermaid theme={null}
graph LR
    Pull[git pull] --> Branch[Create branch]
    Branch --> Code[Write code]
    Code --> Test[Run tests]
    Test --> Lint[Lint code]
    Lint --> Commit[Commit changes]
    Commit --> Push[Push branch]
    Push --> PR[Create PR]
```

### Running Applications

<Tabs>
  <Tab title="Electron Client">
    ```bash theme={null}
    cd apps/electron-client

    # Development mode with hot reload
    pnpm run electron:dev

    # Or just the Next.js dev server
    pnpm run dev
    ```
  </Tab>

  <Tab title="API Server">
    ```bash theme={null}
    cd apps/api-server

    # With uvicorn
    uvicorn main:app --reload

    # With Docker Compose
    docker-compose -f ../../docker-compose.local.yml up api
    ```
  </Tab>

  <Tab title="Chrome Extension">
    ```bash theme={null}
    cd apps/chrome-extension

    # Build once
    pnpm run build

    # Or watch mode for development
    pnpm run watch
    ```

    Then load from `chrome://extensions/`
  </Tab>
</Tabs>

### Running Tests

```bash theme={null}
# Run all tests
pnpm test

# Run tests for specific app
pnpm nx test electron-client
pnpm nx test api-server

# Watch mode
pnpm nx test electron-client --watch

# With coverage
pnpm nx test electron-client --coverage
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="pnpm install fails">
    ```bash theme={null}
    # Clear pnpm cache
    pnpm store prune

    # Delete node_modules and lockfile
    rm -rf node_modules pnpm-lock.yaml

    # Reinstall
    pnpm install

    # If still failing, check Node version
    node --version  # Should be 18+
    ```
  </Accordion>

  <Accordion title="Rust build errors">
    ```bash theme={null}
    # Update Rust
    rustup update

    # Check for missing build tools
    # Windows: Install Visual Studio Build Tools
    # macOS: xcode-select --install
    # Linux: sudo apt install build-essential

    # Clean and rebuild
    cargo clean
    cargo build --release
    ```
  </Accordion>

  <Accordion title="Python dependency conflicts">
    ```bash theme={null}
    # Use virtual environment
    python -m venv venv
    source venv/bin/activate  # Unix
    .\venv\Scripts\activate   # Windows

    # Upgrade pip
    pip install --upgrade pip

    # Install dependencies
    pip install -r requirements.txt
    ```
  </Accordion>

  <Accordion title="Nx commands not working">
    ```bash theme={null}
    # Clear Nx cache
    pnpm nx reset

    # Reinstall dependencies
    pnpm install

    # Update Nx
    pnpm add -D nx@latest
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Building" icon="hammer" href="/development/building">
    Learn how to build for production
  </Card>

  <Card title="Testing" icon="flask" href="/development/testing">
    Write and run tests
  </Card>

  <Card title="Contributing" icon="hand-holding-heart" href="/development/contributing">
    Contribution guidelines
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/architecture">
    Understand the architecture
  </Card>
</CardGroup>