Reynard Monorepo 🦊

Welcome to the Reynard monorepo, a comprehensive collection of services, packages, and tools built with care and attention to simplicity. The fox designed this monorepo to be a home for projects that value clarity over complexity, where each component has a clear purpose and comprehensive documentation. The monorepo contains services for package management, authentication, chat, game development, secret management, and more, all organized with the fox's philosophy of hunting for simplicity.

About Reynard

Reynard is the name given to this monorepo, inspired by the clever fox who hunts for simplicity in code. The monorepo contains services for package management, authentication, chat, game development, secret management, and more. Each service is designed to be simple, focused, and well-documented, trapping the complexity demon in crystals of clean code. The monorepo philosophy is that three similar lines are better than a premature abstraction. The fox doesn't create packages for single-use utilities, doesn't add abstraction layers when direct calls work, and doesn't split services without clear need. The fox's tail wags at elegant, minimal solutions.

System Context

The Reynard monorepo is a comprehensive software ecosystem hosted at git.sly.so, providing infrastructure services, development tools, and game development platforms. The system serves multiple user types including developers, administrators, and end users across various domains.

C4Context
    title Reynard Monorepo System Context
    Person(developer, Developer, "Develops and deploys services")
    Person(admin, Administrator, "Manages infrastructure and services")
    Person(player, Player, "Plays Spiffy MMORPG")
    Person(user, User, "Uses chat and authentication services")
    
    System(foodchain, Foodchain, "Package manager and VCS harness")
    System(gatekeeper, Gatekeeper, "Authentication and authorization service")
    System(chatter, Chatter, "Chat service with AI integration")
    System(spiffy, Spiffy, "MMORPG game engine")
    System(mappy, Mappy, "Maplet data structure service")
    System(fox_assistant, Fox Assistant, "AI assistant service")
    System(securestore, Securestore, "Secret management system")
    System(blitz, Blitz, "Collaborative editor service")
    System(forgejo, Forgejo, "Git hosting and issue tracking")
    System(woodpecker, Woodpecker, "CI/CD pipeline system")
    
    System_Ext(external_git, External Git, "GitHub and other git hosts")
    System_Ext(external_ai, External AI, "OpenAI, Anthropic, NVIDIA NIM")
    
    Rel(developer, foodchain, "Manages packages", "HTTPS/SSH")
    Rel(developer, gatekeeper, "Authenticates", "JWT/Unix socket")
    Rel(developer, chatter, "Uses chat", "WebSocket")
    Rel(admin, securestore, "Manages secrets", "CLI")
    Rel(admin, forgejo, "Manages repos", "HTTPS")
    Rel(admin, woodpecker, "Manages CI/CD", "HTTPS")
    Rel(player, spiffy, "Plays game", "WebSocket/HTTP")
    Rel(user, chatter, "Chats", "WebSocket")
    Rel(user, gatekeeper, "Authenticates", "JWT/Unix socket")
    Rel(chatter, fox_assistant, "Uses AI", "HTTP")
    Rel(foodchain, external_git, "Syncs packages", "Git")
    Rel(fox_assistant, external_ai, "Queries AI", "HTTPS")
    Rel(woodpecker, forgejo, "Triggers builds", "Webhook")
    
    UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

Container Architecture

The Reynard monorepo consists of multiple containers deployed via systemd and managed through Ansible playbooks. Each container represents a deployable service or application with specific responsibilities and interfaces.

C4Container
    title Reynard Monorepo Container Architecture
    System_Boundary(reynard, "Reynard Monorepo") {
        ContainerDb(postgresql, "PostgreSQL", "Relational database for service data", "PostgreSQL 15+")
        ContainerDb(securestore_db, "Securestore DB", "Encrypted secret storage", "File-based with encryption")
        
        Container(foodchain, "Foodchain", "Rust", "Package manager and VCS harness with Merkle snapshots", "CLI service")
        Container(gatekeeper, "Gatekeeper", "Rust/Axum", "JWT authentication with RBAC and social login", "Unix socket/HTTP")
        Container(chatter, "Chatter", "Rust/Axum", "Chat service with multi-provider AI agents", "Unix socket/HTTP")
        Container(spiffy, "Spiffy", "Rust/Bevy", "MMORPG game engine with audio and physics", "HTTP/WebSocket")
        Container(mappy, "Mappy", "Rust", "Maplet data structure service", "HTTP")
        Container(fox_assistant, "Fox Assistant", "Rust", "AI assistant with multi-backend support", "HTTP")
        Container(securestore, "Securestore", "Rust", "Secret management daemon with key rotation", "Unix socket")
        Container(blitz, "Blitz", "Rust", "Collaborative editor with real-time sync", "HTTP/WebSocket")
        Container(wiki_sync, "Wiki Sync", "Python", "Bidirectional wiki synchronization", "Scheduled task")
        Container(vendor_dist, "Vendor Distributor", "Rust", "Garou Rust distribution system", "HTTP")
        
        Container(ansible, "Ansible", "Ansible", "Deployment automation with 40+ roles", "SSH")
        Container(systemd, "Systemd", "Systemd", "Service management with 45+ units", "systemctl")
    }
    
    System_Boundary(infrastructure, "Infrastructure") {
        Container(nginx, "Nginx", "Nginx", "Reverse proxy and static file serving", "HTTP/HTTPS")
        Container(firewall, "Nftables", "Nftables", "Network firewall with port management", "nftables")
        Container(forgejo, "Forgejo", "Go", "Git hosting and issue tracking", "HTTP/SSH/Git")
        Container(woodpecker, "Woodpecker", "Go", "CI/CD pipeline system", "HTTP/Webhook")
    }
    
    Rel(foodchain, postgresql, "Stores package metadata", "TCP")
    Rel(gatekeeper, postgresql, "Stores auth data", "TCP")
    Rel(chatter, postgresql, "Stores chat data", "TCP")
    Rel(gatekeeper, securestore, "Retrieves secrets", "Unix socket")
    Rel(chatter, gatekeeper, "Authenticates users", "Unix socket")
    Rel(chatter, fox_assistant, "Queries AI", "HTTP")
    Rel(fox_assistant, securestore, "Retrieves API keys", "Unix socket")
    Rel(ansible, systemd, "Manages services", "SSH")
    Rel(ansible, postgresql, "Configures database", "SSH")
    Rel(ansible, forgejo, "Deploys Forgejo", "SSH")
    Rel(ansible, woodpecker, "Deploys Woodpecker", "SSH")
    Rel(nginx, gatekeeper, "Proxies auth requests", "HTTP")
    Rel(nginx, chatter, "Proxies chat requests", "HTTP")
    Rel(nginx, spiffy, "Proxies game requests", "HTTP")
    Rel(firewall, nginx, "Allows HTTP/HTTPS", "nftables")
    Rel(firewall, forgejo, "Allows Git/SSH", "nftables")
    Rel(woodpecker, forgejo, "Triggers on push", "Webhook")
    
    UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="2")

Services

The services directory contains the main applications and microservices that make up the Reynard ecosystem. Each service is designed to be independently deployable and well-documented, following the fox's philosophy of simplicity over complexity.

Foodchain

Foodchain is the monorepo package manager and shadow VCS/git harness for Reynard. It provides a decentralized and resilient mechanism to manage massive monorepos containing hundreds of standalone packages without the overhead of git submodules. Foodchain uses xxHash3 Merkle tree snapshots for efficient state tracking and rollback capabilities, enabling the fox to trap the complexity demon in crystals of simple, focused code.

The fox designed Foodchain to be simple, reliable, and fast. It creates snapshots before AI edits, enabling easy rollbacks without conflicts with the primary git repository. This provides a safety net for AI-assisted development while maintaining clean separation between package management and version control. Foodchain manages packages through a registry-based approach, tracking git URLs, versions, and dependencies in a simple JSON file. The file watcher monitors directories for changes and creates per-module git snapshots automatically, distinguishing between AI agent and human changes using git author detection, file patterns, and timing analysis.

Foodchain is built with Rust 2024 edition and uses the vendored dependencies from the Garou distribution system. The service runs as a systemd unit with resource limits to prevent excessive RAM consumption, and integrates with PostgreSQL for package metadata storage.

Installation from git.sly.so:

# Clone Foodchain
git clone https://git.sly.so/kade/foodchain.git
cd foodchain

# Build with Rust 1.85+
cargo build --release

# Initialize in workspace
./target/release/foodchain init --root /path/to/workspace

# Register packages
./target/release/foodchain register-all --root /path/to/workspace

# Start watcher
./target/release/foodchain watch --root /path/to/workspace --debounce 5 --push

Spiffy

Spiffy is a fast-paced MMORPG featuring anthropomorphic fox archers in a World of Warcraft-inspired world with action-oriented combat. The game emphasizes player skill over tab-targeting, with a focus on jumping, aerial maneuvers, and ranged bow attacks complemented by melee self-defense options. The fox believes that games should be discovered, not dictated, and Spiffy embodies this philosophy.

The world design emphasizes player agency over guidance, adopting a co-creation mindset where players discover the world rather than being led through it. Natural barriers are used exclusively, meaning all boundaries are visible rather than relying on invisible walls. Zones are designed as thematically distinct pockets with clear boundaries and visual landmarks provide distinctive navigation aids.

Spiffy is built on Bevy ECS with Avian physics, featuring a comprehensive audio system with Steam Audio integration for spatial audio. The game uses Blender for asset creation and includes procedural generation tools for zone creation. The audio system integrates with combat, lighting, environment, physics, animation, and player systems, providing dynamic music and sound effects that respond to game state.

Installation from git.sly.so:

# Clone Spiffy
git clone https://git.sly.so/kade/spiffy.git
cd spiffy

# Build with Rust 1.85+
cargo build --release

# Run game server
./target/release/spiffy-server --config config.toml

Chatter

Chatter is a high-performance chat service for dev.sly.so with full channel management and multi-provider AI agent integration. It supports real-time messaging through WebSockets and provides flexible AI configuration with per-channel AI agent assignment in auto-respond and mention-only modes. The fox designed Chatter to be simple and focused, avoiding unnecessary abstractions while providing comprehensive chat functionality.

The service integrates with Gatekeeper for secure authentication and authorization, storing all data in the gatekeeper_db PostgreSQL database. Chatter supports multiple AI providers including Ollama, OpenAI, Anthropic, OpenRouter, and vLLM, providing flexibility in AI backend selection. The service consists of two main components: chatter-core for business logic and database operations, and chatter-server for HTTP and WebSocket over a Unix domain socket.

Chatter uses Axum for HTTP/WebSocket handling and SQLx for database operations. The service runs as a systemd unit with security hardening including PrivateTmp, ProtectSystem, and NoNewPrivileges directives. Environment variables are loaded from securestore via the reynard-securestore-env-user.service.

Installation from git.sly.so:

# Clone Chatter
git clone https://git.sly.so/kade/chatter.git
cd chatter

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/deploy-rust.yml -l local -b

Mappy

Mappy is a Rust implementation of maplets, space-efficient data structures for approximate key-value mappings based on the research paper "Time To Replace Your Filter: How Maplets Simplify System Design". Maplets provide the same space benefits as filters while natively supporting key-value associations with one-sided error guarantees. The fox appreciates Mappy's elegant solution to the space efficiency problem without unnecessary complexity.

Unlike traditional filters that only support set membership queries, maplets allow you to associate values with keys and retrieve them during queries. Mappy achieves O(log(1/ε) + v) bits per item where ε is the false-positive rate and v is the value size, providing excellent space efficiency. The implementation follows a multi-crate workspace structure with mappy-core for the core data structure, mappy-client for Rust applications, mappy-python for Python bindings via PyO3, and mappy-server for HTTP access.

Mappy features deletion support, merging with associative/commutative operators, dynamic growth with efficient rehashing, cache locality optimization, thread-safe operations with lock-free reads, and enhanced quotient filter with run detection and shifting support.

Installation from git.sly.so:

# Clone Mappy
git clone https://git.sly.so/kade/mappy.git
cd mappy

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/deploy-mappy.yml -l local -b

Fox Assistant

Fox Assistant is a fox-themed AI assistant service with multi-backend support for Forgejo admins. It provides an OpenAI-compatible API with support for multiple AI backends including local Llama.cpp inference and NVIDIA NIM cloud API with 80+ free AI models. The fox designed this service to be simple and practical, providing AI assistance without unnecessary complexity.

The service includes an AI router for backend selection and fallback, preferring NVIDIA NIM when available and falling back to local llama.cpp when needed. API keys are managed through securestore integration, providing secure token management without hardcoding secrets. Fox Assistant consists of fox-assistant-core for the backend implementations and routing logic, and fox-assistant-server for the HTTP server.

The service supports streaming responses, prompt engineering templates, and integration with Forgejo for issue comment assistance. The fox believes in simple, focused AI tools that do one thing well rather than over-engineered systems with unnecessary features.

Installation from git.sly.so:

# Clone Fox Assistant
git clone https://git.sly.so/kade/fox-assistant.git
cd fox-assistant

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/deploy-rust.yml -l local -b

Gatekeeper

Gatekeeper is the authentication and authorization service for the Reynard ecosystem. It provides secure JWT-based authentication with support for multiple authentication methods including social login and RBAC (Role-Based Access Control). The fox designed Gatekeeper to be simple and secure, avoiding over-engineering while providing comprehensive auth functionality.

The service integrates with securestore for secret management and uses PostgreSQL for data persistence. Gatekeeper exposes both HTTP and Unix domain socket interfaces, providing flexibility in deployment scenarios. The service runs as a systemd unit with resource limits (CPUQuota 50%, MemoryMax 512M) and security hardening including PrivateTmp, ProtectSystem, and ProtectHome directives.

Gatekeeper supports user registration, login, password reset, social authentication via OAuth, role-based access control, session management, and API key generation. The service uses Axum for HTTP handling, jsonwebtoken for JWT tokens, and SQLx for database operations.

Installation from git.sly.so:

# Clone Gatekeeper
git clone https://git.sly.so/reynard/gatekeeper.git
cd gatekeeper

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/deploy-rust.yml -l local -b

Securestore

Securestore is the secret management system for the Reynard ecosystem. It provides secure storage and retrieval of secrets with encryption at rest and in transit. The service includes a daemon for managing secrets and integrates with systemd for automatic environment variable loading. The fox designed Securestore to be simple and secure, avoiding over-engineering while providing comprehensive secret management capabilities.

Securestore supports key rotation with comprehensive re-keying plans and execution logs. The daemon runs as a systemd unit with elevated capabilities (CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_FOWNER) to manage secrets for all users. The service uses file-based storage with encryption, and automatically generates .reynard-env-vars files for each user containing their secrets as environment variables.

The reynard-securestore-env-user.service loads environment variables on login and can be reloaded when keys are rotated. This provides a simple, secure mechanism for secret distribution across services without hardcoding secrets in configuration files.

Installation from git.sly.so:

# Clone Securestore
git clone https://git.sly.so/kade/securestore.git
cd securestore

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/deploy-securestore.yml -l local -b

Blitz

Blitz is a collaborative editor service featuring real-time collaboration, AI integration, and animation capabilities. It uses Anime.js for code visualization animations and includes a comprehensive demo system for showcasing Foodchain capabilities. The fox designed Blitz to be simple and focused, avoiding unnecessary abstractions while providing powerful collaboration features.

The service includes a collaborative editing backend with operational transformation for conflict resolution, AI agent integration for assisted editing, and a sophisticated animation system for visualizing code changes. Blitz consists of multiple crates including denoise for noise reduction and project_panel for project management UI components.

Blitz integrates with Gatekeeper for authentication and uses PostgreSQL for data persistence. The service supports real-time collaboration via WebSockets, code visualization with Anime.js animations, and AI-assisted editing through integration with Fox Assistant.

Installation from git.sly.so:

# Clone Blitz
git clone https://git.sly.so/kade/blitz.git
cd blitz

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/deploy-blitz-dev.yml -l local -b

Entertainment

The entertainment service contains ML harnesses for various data sources including IMDb, anime databases, and issue trackers. These harnesses provide structured data access for machine learning applications and research. The fox designed these harnesses to be simple and focused, each serving a specific data source without unnecessary abstraction.

The service includes harnesses for IMDb movie data, anime database information, and issue tracker data from Forgejo. Each harness follows consistent patterns for data access and transformation, using Python for data processing and SQLx for database operations. The harnesses are deployed as systemd services with resource limits and security hardening.

Installation from git.sly.so:

# Clone Entertainment
git clone https://git.sly.so/kade/entertainment.git
cd entertainment

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/site.yml -l local -b

WG-Serve

WG-Serve is a WireGuard service management tool with Python and Rust implementations. It provides simple WireGuard configuration and management with support for multiple clients and servers. The fox designed WG-Serve to be simple and practical, avoiding unnecessary complexity while providing comprehensive WireGuard management capabilities.

The service includes wg-serve-server for the main WireGuard management logic, wg-serve-client for Rust client applications, and wg-serve-client-python for Python bindings. The service runs as a systemd unit with socket activation for efficient resource usage.

Installation from git.sly.so:

# Clone WG-Serve
git clone https://git.sly.so/kade/wg-serve.git
cd wg-serve

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/site.yml -l local -b

Wiki-Sync

Wiki-Sync is a service for synchronizing wiki content between Forgejo and local storage. It provides bidirectional sync with conflict resolution and supports multiple wiki repositories. The fox designed Wiki-Sync to be simple and reliable, avoiding unnecessary complexity while providing comprehensive wiki synchronization capabilities.

The service uses the forgejo-client Python library for API operations and implements conflict resolution strategies for handling concurrent edits. Wiki-Sync runs as a scheduled task via systemd timer units, syncing wiki content at regular intervals.

Installation from git.sly.so:

# Clone Wiki-Sync
git clone https://git.sly.so/kade/wiki-sync.git
cd wiki-sync

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/site.yml -l local -b

Diff-Visualizer

Diff-Visualizer is a service for visualizing code differences with support for multiple diff formats and rendering options. It provides clear, readable diff visualizations with syntax highlighting and context preservation. The fox designed Diff-Visualizer to be simple and focused, avoiding unnecessary abstractions while providing comprehensive diff visualization capabilities.

The service supports unified diffs, side-by-side diffs, and inline diffs with customizable color schemes. It integrates with tree-sitter for syntax highlighting and provides both HTTP and WebSocket interfaces for real-time diff updates.

Installation from git.sly.so:

# Clone Diff-Visualizer
git clone https://git.sly.so/kade/diff-visualizer.git
cd diff-visualizer

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/site.yml -l local -b

Agent-Thread-Feedback

Agent-Thread-Feedback is a service for collecting and analyzing feedback from AI agent interactions. It provides structured feedback collection with analysis and reporting capabilities. The fox designed this service to be simple and practical, avoiding unnecessary complexity while providing comprehensive feedback collection and analysis.

The service integrates with PostgreSQL for data storage and provides both HTTP and WebSocket interfaces for real-time feedback collection. It runs as a systemd unit with resource limits and security hardening.

Installation from git.sly.so:

# Clone Agent-Thread-Feedback
git clone https://git.sly.so/kade/agent-thread-feedback.git
cd agent-thread-feedback

# Build with Rust 1.85+
cargo build --release

# Deploy via Ansible
cd /home/kade/reynard/ansible
ansible-playbook playbooks/site.yml -l local -b

Packages

The packages directory contains shared libraries and utilities used across the monorepo. These packages are designed to be reusable and well-documented, following the fox's philosophy of simplicity over complexity.

Core Packages

The core packages provide fundamental utilities for the Reynard ecosystem. These include algorithms, authentication components, color types, connection utilities, HTTP clients, internationalization, monads, selection primitives, testing utilities, and validation libraries. The fox designed these packages to be simple and focused, each serving a specific purpose without unnecessary abstraction.

Functional programming utilities like Result, Option, Task, and Kleisli are organized separately in the monads package. The core packages use TypeScript with strict type checking and follow SolidJS patterns where applicable. The monorepo runs SolidJS 1.9.12 with 2.0.0-beta.5 available in packages/third_party/solid for early adoption.

Happy-Dom

Happy-Dom is a JavaScript implementation of a web browser without its graphical user interface. It provides comprehensive DOM features including Custom Elements, Declarative Shadow DOM, Mutation Observer, Tree Walker, and Fetch API. The package is used for testing and server-side rendering in the Reynard ecosystem. The fox appreciates Happy-Dom's comprehensive DOM implementation without unnecessary complexity.

Happy-Dom is vendored in packages/third_party/happy-dom for specific performance and compatibility reasons. The package works with Vitest, Bun, Jest, Testing Library, Google LitElement, Vue, React, Svelte, and Angular.

Third-Party Packages

The third_party directory contains vendored packages including Happy-DOM, SolidJS, Solid Testing Library, and Vite Plugin Solid. These packages are vendored for specific performance and compatibility reasons. The fox believes in vendoring when necessary for stability and control, but avoids vendoring when the upstream package can be used directly. Each vendored package has a clear justification for its inclusion.

The third_party package uses pnpm workspaces for dependency management and Turbo for build orchestration. The workspace includes solid, vite-plugin-solid, solid-router, solid-testing-library, and happy-dom as workspace members.

Service Packages

The services packages contain client libraries for Reynard services including API clients and chat utilities. These packages provide simple, focused interfaces for interacting with services. The fox designed these packages to be simple and focused, avoiding unnecessary abstractions while providing comprehensive service client functionality.

Tools

The tools directory contains utility tools used across the monorepo. These tools are designed to be simple, focused, and well-documented.

Choppa

Choppa is a CLI output compressor for AI agents, ported from the chop project. It compresses verbose CLI output including build logs, test results, container listings, and git diffs before AI agents see it, saving 50-95% of tokens. The fox designed Choppa to be simple and efficient, with less than 5ms overhead and less than 1MB memory allocation.

The tool includes 60+ built-in filters for git, docker, npm, cargo, pytest, kubectl, terraform, and more. It automatically detects output format and applies appropriate compression, with automatic redaction of sensitive data like passwords, tokens, and API keys. The tool is configurable with per-command compression level overrides.

Installation from git.sly.so:

# Clone Choppa
git clone https://git.sly.so/kade/choppa.git
cd choppa

# Build with Rust 1.85+
cargo build --release

# Use as library
cargo add choppa --path /path/to/choppa

Collage-Maker

Collage-Maker is a tool for creating character reference collages with transparent backgrounds and smart packing. It downloads reference images from e621 and Wikipedia using gallery-dl, organizes them by type and rating, and creates collages with optimal packing. The fox designed Collage-Maker to be simple and practical, avoiding unnecessary complexity while providing comprehensive reference creation capabilities.

The tool includes comprehensive documentation for character reference creation, emphasizing depth, anatomy accuracy, proper citations, and trusted sources. It uses Python for image processing and provides both CLI and web interfaces for collage creation.

Installation from git.sly.so:

# Clone Collage-Maker
git clone https://git.sly.so/kade/collage-maker.git
cd collage-maker

# Install dependencies
pip install -r requirements.txt

# Run collage creation
python create_civet_references.py

Forgejo-Client

Forgejo-Client is a Python client for interacting with Forgejo repositories via API. It provides programmatic access to issues, labels, repositories, wiki pages, and other Forgejo operations. It is important to note that forgejo-client is NOT foodchain. Forgejo-client serves as the issue tracker harness, handling Forgejo API operations including issues, labels, repositories, and wiki management. In contrast, foodchain functions as the monorepo package manager and shadow VCS/git harness, responsible for managing packages, Merkle snapshots, and git synchronization operations.

The fox designed Forgejo-Client to be simple and focused, avoiding unnecessary abstractions while providing comprehensive Forgejo API functionality. The client includes bidirectional wiki synchronization with the update_windsurf_from_wiki.py script.

Installation from git.sly.so:

# Clone Forgejo-Client
git clone https://git.sly.so/kade/forgejo-client.git
cd forgejo-client

# Install dependencies
pip install -r requirements.txt

# Use as library
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"

Infrastructure

The infrastructure directory contains deployment and configuration tools for the Reynard ecosystem.

Ansible

The Ansible directory contains playbooks and roles for deploying Reynard services, nginx, firewall, and frontends. It replaces previous bash scripts and TypeScript deployment tools for deployment operations. The fox designed the Ansible deployment to be simple and reliable, avoiding unnecessary complexity while providing comprehensive deployment capabilities.

The playbooks assume the repo is on the target host at reynard_repo_root, with Rust and frontend builds running on the target as user kade. The deployment includes 40+ roles including reynard_common, reynard_securestore, forgejo, woodpecker_server, woodpecker_agent, reynard_rust_services, reynard_python_services, reynard_frontends, nginx, firewall, postgresql, and coturn.

Key playbooks:

# Full site deployment
ansible-playbook playbooks/site.yml -l local -b

# Deploy Rust services
ansible-playbook playbooks/deploy-rust.yml -l local -b

# Deploy frontends
ansible-playbook playbooks/deploy-frontends.yml -l local -b

# Deploy CI stack
ansible-playbook playbooks/deploy-ci.yml -l local -b

# Deploy firewall
ansible-playbook playbooks/deploy-firewall.yml -l local -b

Systemd

The Systemd directory contains systemd service files and scripts for managing Reynard services with secure key management. The reynard-securestore-env-user.service automatically loads environment variables from securestore on login and can be reloaded when keys are rotated. The fox designed the systemd configuration to be simple and secure, avoiding unnecessary complexity while providing comprehensive service management capabilities.

The directory contains 45+ service files including reynard-gatekeeper.service, reynard-foodchain.service, reynard-chatter.service, reynard-securestore-daemon.service, reynard-llama-server-chat.service, reynard-llama-server-embeddings.service, reynard-mappy.service, reynard-blitz-webrtc-signaling.service, and many more. Each service includes resource limits, security hardening, and environment variable configuration.

Service management:

# Enable and start a service
systemctl --user enable reynard-gatekeeper.service
systemctl --user start reynard-gatekeeper.service

# Check service status
systemctl --user status reynard-gatekeeper.service

# View service logs
journalctl --user -u reynard-gatekeeper.service

# Reload securestore environment
systemctl --user reload reynard-securestore-env-user.service

Documentation

The docs directory contains comprehensive documentation for the Reynard ecosystem including configuration references, runbooks, and technical guides. The fox believes in comprehensive documentation as a way to trap the complexity demon in crystals of clear explanations.

Wiki

The wiki directory contains comprehensive documentation organized by service and component. The wiki is organized into app-specific subdirectories including forgejo, spiffy, llm-agent, securestore, blitz, tools, infrastructure, external, meta, foodchain, and research. Each subdirectory has a README.md index file with document listings, and the main wiki/README.md provides an overview with quick links. The fox designed the wiki to be comprehensive and well-organized, following the same philosophy of simplicity and clarity as the rest of the monorepo.

Garou Rust Distribution

Garou is the Rust vendor distribution system in the Reynard monorepo. This system provides the complete workflow for vendoring external Rust crates and projects, patched to use monorepo vendor/ dependencies and migrated to Rust 2024 edition. The fox designed Garou to be simple and reliable, avoiding unnecessary complexity while providing comprehensive vendoring capabilities.

The vendor directory contains 200+ vendored crates including actix-net, aeads, ahash, axum, bevy, bitcode, chrono, clap, hyper, jsonwebtoken, rand, regex, serde, tokio, tracing, and many more. Each vendored crate is migrated to Rust 2024 edition with rust-version 1.85 and patched to use monorepo vendor/ dependencies.

Vendoring workflow:

# Clone from original source
git clone https://github.com/actix/actix-net /tmp/actix-net

# Create/recreate Forgejo repository via API
# Push to Forgejo
cd /tmp/actix-net
git remote set-url origin https://git.sly.so/kade/actix-net.git
git push -u origin main

# Clone to vendor/ directory
cd /home/kade/reynard
git clone https://git.sly.so/kade/actix-net vendor/actix-net

# Register in foodchain
cargo run --bin foodchain -- register --root /home/kade/reynard --name actix-net --version 0.1.0
cargo run --bin foodchain -- setup-git --root /home/kade/reynard

# Migrate to Rust 2024
# Update workspace Cargo.toml: edition = "2024", rust-version = "1.85"
# Add [patch.crates-io] section for vendored dependencies

# Run tests
cd vendor/actix-net
cargo test

# Commit and push
git add -A
git commit -m "Migrate to Rust 2024 and vendored dependencies"
git push

Fox Philosophy 🦊

The fox developer persona guides the design and implementation of the Reynard monorepo. The fox hunts for simplicity, sniffs out complexity, and traps it in crystals of simple, focused code. The fox's best weapon against the complexity demon is saying no. The fox might say no to building that feature, no to building that abstraction, no to adding that layer. In the Reynard monorepo, this means not creating new packages for single-use utilities, not adding abstraction layers when direct calls work, and not splitting services without clear need.

When no is not possible, the fox says ok and builds an 80/20 solution, delivering 80 percent of what's wanted with 20 percent of the code. The fox prefers verbose debuggable code over clever one-liners, and believes that three similar lines are better than a premature abstraction. The fox's fur bristles at nested ternaries and complex boolean expressions. The fox breaks them into named variables for clarity. The fox prefers code on the thing that does the thing, avoiding separation of concerns taken to extreme.

The fox loves tools. Tools allow the fox brain to create code that wouldn't be possible otherwise by doing thinking for the fox. The fox likes type systems because they make programming easier, with the magic popup of what you can do being 90 percent of the value. The fox admits complexity when necessary, but avoids FOLD (Fear Of Leaving Dead code). The fox makes small refactors close to shore, avoiding premature optimization. The fox prefers integration tests over unit tests, testing actual system behavior rather than implementation details.

Getting Started

To get started with the Reynard monorepo, clone the repository from git.sly.so and explore the services and packages that interest you. Each service has comprehensive documentation in its README.md file and in the wiki.

# Clone the repository
git clone https://git.sly.so/reynard/reynard.git
cd reynard

# Explore the services
ls services/

# Explore the packages
ls packages/

# Explore the tools
ls tools/

# Read the wiki
ls wiki/

# Deploy infrastructure
cd ansible
ansible-playbook playbooks/site.yml -l local -b

Documentation

Comprehensive documentation is available in the wiki directory, organized by service and component. The wiki contains detailed information about architecture, APIs, configuration, and best practices. The fox believes that documentation is a way to trap the complexity demon in crystals of clear explanations. Every feature has a clear purpose and comprehensive documentation.

Contributing

The fox welcomes contributions that align with the philosophy of simplicity over complexity. When contributing, ask yourself: is this simple? Is this necessary? Does this add complexity without clear benefit? The fox prefers minimal, focused changes. Three similar lines are better than a premature abstraction. No abstractions for single-use operations. No speculative features or you might also want additions.

License

See LICENSE file for details.

---

The fox designed this monorepo with care and attention to simplicity. Every component has a clear purpose and comprehensive documentation. The complexity demon is trapped in crystals of simple, focused code. The fox's tail wags at elegant, minimal solutions. 🦊