Colibri Repository Directory Structure: Complete Guide to the JustVugg/colibri Codebase

The Colibri repository follows a polyglot architecture that separates Python backend logic in colibri/, React web UI in web/, and Rust desktop components in desktop/, with extensive documentation under docs/ and deployment configurations at the repository root.

The directory structure of the Colibri repository reflects a modern multi-platform architecture designed for AI/ML workflows. This open-source project organizes its Python CLI tools, TypeScript frontend, and Rust desktop bindings into distinct top-level folders that enforce clear separation of concerns. Understanding this layout is essential for contributing to the codebase or deploying the software across different environments.

Core Python Package (colibri/)

The colibri/ directory houses the main Python package implementing the command-line interface and core library functions. The primary entry point for CLI operations resides in colibri/cli.py, which handles argument parsing and command routing. Package initialization and version metadata are defined in colibri/__init__.py.

Web Frontend (web/)

Built with React and TypeScript, the web/ folder contains the browser-based user interface. The application bootstrap occurs in web/src/main.tsx, while build tooling and development server configuration are managed through web/vite.config.ts using the Vite toolchain.

Desktop Client (desktop/)

The desktop application leverages Tauri to combine a Rust backend with the web frontend. Rust build scripts and crate dependencies are defined in desktop/src-tauri/Cargo.toml, with platform-specific documentation available in desktop/README.md. This structure allows the web UI to run within a native application shell.

Documentation Architecture (docs/)

Human-readable documentation covers installation procedures, GPU backend configuration, and API references. The docs/quickstart.md file provides onboarding instructions for new users, while docs/api.md details programmatic interfaces for library consumption.

Experimental results and hardware-specific benchmarks reside in the docs/experiments/ subdirectory. For example, docs/experiments/glm52-4xa6000-2026-08-02.md contains benchmark logs for specific GPU configurations.

Deployment and Static Assets

Container Support (docker/)

Docker support enables reproducible deployment across environments. The docker/Dockerfile defines runtime images for the backend services, while docker/docker-compose.yml provides orchestration configurations for multi-container deployments.

Web Presence (site/ and assets/)

Static site assets for the project landing page live in site/, including site/index.html and vector graphics like site/colibri.svg. Shared graphic resources such as assets/colibri-logo.svg are referenced by both the web UI and documentation to prevent asset duplication.

Build Configuration and Environment Setup

Root-level configuration files manage the build process and development environments. The pyproject.toml file defines Python package metadata, dependencies, and build settings, while the Makefile provides common development task automation.

For reproducible development environments, the repository includes flake.nix and flake.lock for Nix-based package management. These files ensure consistent tooling across different developer machines.

Additional root-level documentation includes README.md for project overview, CONTRIBUTING.md for contribution guidelines, and GPU_BACKENDS.md which enumerates supported GPU backends including CUDA and Metal compatibility matrices.

Summary

• The repository strictly partitions implementation languages into dedicated directories: Python (colibri/), TypeScript (web/), and Rust (desktop/)
• Documentation is extensive and hierarchical, with user guides in docs/ and experimental logs in docs/experiments/
• Docker and Nix configurations provide reproducible deployment and development environments
• Static assets are organized between site/ (landing pages) and assets/ (shared graphics) to maintain consistency across interfaces
• Build configuration is centralized at the repository root through pyproject.toml, Makefile, and flake.nix

Frequently Asked Questions

What is the main entry point for the Colibri CLI?

The command-line interface is implemented in colibri/cli.py within the core Python package, while package initialization occurs in colibri/__init__.py. These files handle argument parsing and core library initialization when users invoke the colibri command.

How does the Colibri repository handle frontend and desktop code sharing?

The project uses Tauri to wrap the React/TypeScript web UI defined in web/src/main.tsx within a Rust-based desktop shell configured in desktop/src-tauri/Cargo.toml. This architecture allows the web/ directory to serve both browser-based and desktop deployments, with the desktop/ folder containing only the native Rust bindings and window configuration.

Where are GPU backend configurations documented?

GPU support matrices and backend compatibility information are documented in GPU_BACKENDS.md at the repository root, while detailed tuning guides and hardware-specific experiments reside in docs/ and docs/experiments/ respectively. The docs/experiments/glm52-4xa6000-2026-08-02.md file provides concrete examples of benchmark configurations for specific hardware setups.

What files control the Docker deployment of Colibri?

Container orchestration is managed through docker/docker-compose.yml, while image definitions are specified in docker/Dockerfile. These files enable reproducible backend deployment and mirror the source code structure for consistent runtime environments across different platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}