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

# Repository Layout

> Understanding the Cowboy monorepo structure

## Introduction

The Cowboy project is organized as a **monorepo** containing the core protocol implementation, SDK, documentation, and tooling. This guide helps you navigate the codebase.

<Tip>
  **Repository**: [github.com/cowboyinc/cowboy](https://github.com/cowboyinc/cowboy)
</Tip>

## Repository Structure

```
cowboy/
|-- crates/                                  # Rust implementation
|   \-- cowboy-core/
|       |-- src/
|       |   |-- actor_simulator.rs
|       |   |-- consensus.rs
|       |   |-- metering.rs
|       |   |-- lib.rs
|       |   |-- simulator.rs
|       |   |-- state.rs
|       |   |-- types.rs
|       |   |-- runtime/                     # Actor VM runtime
|       |   |-- runner/                      # Off-chain runner
|       |   \-- bin/                         # Executables
|       \-- Cargo.toml
|
|-- sdk/                                     # Language SDKs
|   \-- python/
|       |-- cowboy_sdk.egg-info/
|       |-- cowboy_sdk/
|       |-- examples/
|       |-- tests/
|       |-- README.md
|       |-- README_SDK.md
|       |-- SETUP.md
|       |-- pyproject.toml
|       |-- pytest.ini
|       |-- requirements.txt
|       \-- test_manual.py
|
|-- docs/                                    # Documentation
|   |-- architecture/
|   |-- assets/
|   |-- cips/
|   |-- contributing/
|   |-- developers/
|   |-- economics/
|   |-- getting-started/
|   |-- governance/
|   |-- images/
|   |-- introduction/
|   |-- overview/
|   |-- references/
|   |-- security/
|   |-- style/
|   |-- versioning/
|   |-- testing/
|   |-- LICENSE
|   |-- README.md
|   |-- docs.json            # Mintlify config
|   |-- docs.backup.json
|   |-- favicon.svg
|   |-- index.mdx
|   \-- quickstart.mdx
|
|-- dashboard/                               # Explorer UI
|   \-- index.html
|
|-- Cargo.toml                               # Rust workspace
|-- package.json                             # Node.js config
|-- package-lock.json
|-- README.md                                # Project overview
|-- README_TESTING.md
|-- cursor-extensions.txt
|-- .gitignore
\-- Cowboy Documentation Plan(v0.1) Milestone.md
```

## Core Components

### 1. Rust Implementation (`crates/cowboy-core/`)

The heart of Cowboy, written in Rust for performance and safety.

<Tabs>
  <Tab title="Runtime">
    **Path**: `crates/cowboy-core/src/runtime/`

    **Contents**:

    * `pvm.rs` - Python VM implementation
    * `executor.rs` - VM execution driver
    * `context.rs` - Execution context and I/O
    * `mod.rs` - Module declarations
  </Tab>

  <Tab title="Consensus">
    **Path**: `crates/cowboy-core/src/consensus.rs`

    **Purpose**: HotStuff BFT consensus implementation

    **Key Components**:

    * Block proposal
    * Vote aggregation
    * QC (Quorum Certificate) verification
    * Safety and liveness guarantees
  </Tab>

  <Tab title="Off-Chain Runner">
    **Path**: `crates/cowboy-core/src/runner/`

    **Purpose**: Off-chain computation executor (CIP-2)

    **Files**:

    * `http_executor.rs` - HTTP-based runner
    * `llm_executor.rs` - LLM integrations
    * `job_queue.rs` - Job scheduling
    * `openrouter.rs` - OpenRouter client
    * `mod.rs`
  </Tab>
</Tabs>

### 2. Python SDK (`sdk/python/`)

Developer-facing SDK for building actors.

<Tabs>
  <Tab title="Core SDK">
    **Path**: `sdk/python/cowboy_sdk/`
  </Tab>

  <Tab title="Examples">
    **Path**: `sdk/python/examples/`
  </Tab>

  <Tab title="Tests">
    **Path**: `sdk/python/tests/`
  </Tab>
</Tabs>

### 3. Documentation (`docs/`)

This documentation site, built with Mintlify.

```
docs/
|-- architecture/
|-- assets/
|-- cips/
|-- contributing/
|-- developers/
|-- economics/
|-- getting-started/
|-- governance/
|-- images/
|-- introduction/
|-- overview/
|-- references/
|-- security/
|-- style/
|-- versioning/
|-- LICENSE
|-- README.md
|-- docs.json        # Mintlify config
|-- favicon.svg
|-- index.mdx
\-- quickstart.mdx
```

## Key Files

### Configuration Files

| File             | Purpose                      |
| ---------------- | ---------------------------- |
| `Cargo.toml`     | Rust workspace configuration |
| `package.json`   | Node.js dependencies         |
| `docs/docs.json` | Documentation structure      |

### Important READMEs

| File                    | Description                      |
| ----------------------- | -------------------------------- |
| `/README.md`            | Project overview and quick start |
| `/sdk/python/README.md` | SDK installation and usage       |
| `/docs/README.md`       | Documentation contribution guide |

## Contributing Areas

<CardGroup cols={2}>
  <Card title="Core Protocol" icon="code">
    **Language**: Rust

    **Areas**:

    * VM implementation
    * Consensus algorithms
    * Scheduler optimization
    * Security improvements

    **Path**: `crates/cowboy-core/`
  </Card>

  <Card title="Python SDK" icon="python">
    **Language**: Python

    **Areas**:

    * SDK features
    * Developer tools
    * Testing utilities
    * Example actors

    **Path**: `sdk/python/`
  </Card>

  <Card title="Documentation" icon="book">
    **Language**: Markdown (MDX)

    **Areas**:

    * Technical guides
    * Tutorials
    * API reference
    * Diagrams

    **Path**: `docs/`
  </Card>

  <Card title="Tooling" icon="wrench">
    **Language**: Various

    **Areas**:

    * CLI tools
    * Explorer UI
    * Development scripts
    * CI/CD

    **Path**: Multiple
  </Card>
</CardGroup>

## Finding Your Way Around

### Looking for...

<AccordionGroup>
  <Accordion title="VM implementation" icon="microchip">
    **Path**: `crates/cowboy-core/src/runtime/pvm.rs`

    Core Python VM bytecode interpreter.
  </Accordion>

  <Accordion title="Gas metering logic" icon="gauge">
    **Path**: `crates/cowboy-core/src/metering.rs`

    Cycle and Cell calculation implementation.
  </Accordion>

  <Accordion title="Off-chain runner" icon="server">
    **Path**: `crates/cowboy-core/src/runner/`

    Off-chain task execution logic (CIP-2).
  </Accordion>

  <Accordion title="Actor base class" icon="user">
    **Path**: `sdk/python/cowboy_sdk/actor.py`

    Python Actor base class that developers inherit from.
  </Accordion>

  <Accordion title="Example actors" icon="code">
    **Path**: `sdk/python/examples/`

    Ready-to-use actor templates.
  </Accordion>

  <Accordion title="Protocol specs" icon="file-lines">
    **Path**: `docs/cips/`

    Formal CIP (Cowboy Improvement Proposal) specifications.
  </Accordion>
</AccordionGroup>