A modern Bazel monorepo supporting Python, Go, and embedded C++ firmware development with automated release management, Helm chart generation, and multi-platform container builds.
- Multi-Language Support: Python, Go, and embedded C++ with shared libraries
- Automated Releases: Intelligent change detection and selective app releases
- Container Native: Multi-platform Docker images (AMD64/ARM64) with OCI standards
- Helm Integration: Automatic Kubernetes chart generation from app metadata
- CI/CD Pipeline: GitHub Actions with parallel builds and comprehensive testing
- Bazel-First: Fast, cacheable builds with dependency management
everything/
├── manman/ # ManMan - Game server orchestration system
│ ├── src/ # Python services (APIs, workers, migrations)
│ └── management-ui/ # Go-based HTMX management interface
├── friendly_computing_machine/ # Slack bot with Temporal workflows
├── firmware/ # Embedded C++ application layer (board-agnostic)
│ ├── sensor/ # ISensor interface + host-side test mocks
│ ├── mqtt/ # MQTTWriter (zero-allocation) + IPublisher
│ ├── network/ # Wi-Fi + MQTT state machine (non-blocking)
│ └── timing/ # pw_chrono-based loop timer (replaces delay())
├── demo/ # Example applications
│ ├── blink/ # ESP32 blink demo (pw_log + esptool flash target)
│ └── hello_*/ # Go / Python / gRPC examples
├── libs/ # Shared libraries
│ ├── python/ # Python libs (alembic, cli, gunicorn, logging, postgres, rmq, retry)
│ └── go/ # Go libs (htmxauth)
├── generated/ # Generated OpenAPI clients (py/, go/)
├── tools/ # Build and release tooling
│ ├── firmware/ # ESP32 cc_toolchain, board constraints, flash infra
│ ├── bazel/ # Shared Bazel macros (esp32_firmware(), etc.)
│ ├── helm/ # Helm chart generation
│ ├── release_helper/ # Release automation
│ └── tilt/ # Local development with Tilt
├── docs/ # Documentation
├── .github/workflows/ # CI/CD pipelines
├── BUILD.bazel # Root build configuration
└── MODULE.bazel # External dependencies (incl. Pigweed, Xtensa GCC)
Core Principles:
- Bazel-First Architecture: All operations use Bazel for consistency
- True Cross-Compilation: Platform transitions for correct ARM64 wheel selection
- Monorepo Structure: Multiple apps and shared libraries in a single repository
- Release Automation: Comprehensive CI/CD with intelligent change detection
| Project | Description | Documentation |
|---|---|---|
| ManMan | Game server orchestration (V2 Go + V1 Python legacy) | MANMAN_STRUCTURE.md, manmanv2/README.md |
| Friendly Computing Machine | Slack bot with Temporal workflow support | friendly_computing_machine/README.md |
| Firmware | ESP32 embedded firmware (Pigweed + Arduino core + Bazel cc_toolchain) | tools/firmware/README.md, firmware/README.md |
- Bazel 8.3+ with bzlmod support
- usbipd-win (WSL2 only, for ESP32 flashing — see tools/firmware/README.md)
- Docker (for container images)
- Git (for version control)
- Python Virtual Environment (recommended)
# Install Bazelisk (manages Bazel versions)
brew install bazelisk
# Verify installation
bazel version
# Create Python virtual environment
uv venv && source .venv/bin/activate# Build everything
bazel build //...
# Run tests
bazel test //...
# Run example apps
bazel run //demo/hello_python:hello-python
bazel run //demo/hello_go:hello-go# Check Bazel version
bazel version
# Test build system
bazel build //demo/hello_python:hello-python
# Verify release system
bazel query "kind('app_metadata', //...)"For complete setup instructions, see: docs/SETUP.md
Comprehensive guides for working with the monorepo:
- Setup Guide - Installation and prerequisites
- Dependencies - Managing Python and Go dependencies
- Development - Adding new apps and shared libraries
- Helm Charts - Kubernetes chart generation
- Testing - Running and writing tests
- Configuration - Bazel settings and remote cache
- CI/CD Pipeline - Continuous integration details
- Docker Images - Container image building
- Release Management - Automated releases and versioning
Additional resources:
- Helm Release System - Helm chart releases
- Release Tool Cleanup - Tool cleanup summary
mkdir my_python_app
cd my_python_app
# Create main.py, test_main.py, __init__.py, BUILD.bazelSee the complete guide: docs/DEVELOPMENT.md
# Add to pyproject.toml
uv lock --python 3.13
# Use @pypi//:package-name in BUILD.bazelSee the complete guide: docs/DEPENDENCIES.md
# Build an app
bazel build //path/to/app:app_name
# Run an app
bazel run //path/to/app:app_name
# Test an app
bazel test //path/to/app:test_target# Host-side tests — runs on your machine, no board needed
bazel test //firmware/...
bazel test //demo/blink:blink_logic_test
# Build flashable image (requires --config=esp32)
bazel build //demo/blink:blink_bin --config=esp32
# Flash to board (WSL2: attach CP2102 via usbipd first)
bazel run //demo/blink:flash -- /dev/ttyUSB0See tools/firmware/README.md for toolchain details and adding new boards.
Use GitHub Actions UI (recommended):
- Go to Actions → Release workflow
- Specify apps and version
- Run with or without dry-run
See the complete guide: docs/RELEASE.md
- Setup Issues: See docs/SETUP.md for installation troubleshooting
- Build Issues: Check docs/CONFIGURATION.md for Bazel settings
- Release Problems: See docs/RELEASE.md for release troubleshooting
├── manman/ # ManMan - Game server orchestration
├── friendly_computing_machine/ # Slack bot with Temporal
├── demo/ # Example applications
├── libs/ # Shared libraries (python/, go/)
├── generated/ # Generated OpenAPI clients
├── tools/ # Build and release tooling
├── docs/ # Documentation
├── .github/workflows/ # CI/CD workflows
├── BUILD.bazel # Root build configuration
└── MODULE.bazel # External dependencies
Areas that could be enhanced:
- Enhanced Go Support: Enable gazelle rules for better Go dependency management
- Testing Strategy: Expand test utilities and integration testing capabilities
- Documentation: Auto-generation from code for better consistency