Monorepo Project

Overview

A monorepo built with Bazel that supports multiple languages and frameworks. Uses Skaffold for consistent local and CI/CD development workflows. Contains reusable components, templates, and production applications.

Key Features

• Unified Build System: Consistent builds using Bazel across all projects
• Cross-Language Support: Projects in Python, Java, Go, and more
• Standardized Templates: Common project templates for quick bootstrapping
• Integrated Testing: Streamlined testing infrastructure
• Shared Libraries: Common code shared across projects
• CI/CD Integration: GitHub Actions workflows for continuous integration
• Service Mesh Integration: Istio-based rate limiting and traffic management
• Kubernetes Orchestration: Skaffold-based development and deployment workflows
• Infrastructure as Code: Terraform or Pulumi options to manage essential Kubernetes components

Repository Structure

This monorepo contains multiple projects with different technologies:

• All projects are located in the projects/ directory
• Infrastructure as Code (IaC) is supported through both:
  • Terraform (HCL) in terraform_dev_local/
  • Pulumi (Go) in pulumi_dev_local/
• Each technology stack maintains feature parity to provide flexibility and options for infrastructure management to support local containerized application development

monorepo/
├── projects/                   # All projects organized by category
│   ├── base/                   # Base project templates and utilities
│   │   └── base_fastapi_app/   # Base FastAPI project to extend
│   ├── bazel/                  # Bazel-specific project examples
│   ├── go/                     # Go language projects
│   │   └── devops_go_app/      # Simple Go application example
│   ├── java/                   # Java applications and libraries
│   │   ├── simple_java_app/    # Basic Java application
│   │   ├── example1_java_app/  # Java example application 1
│   │   ├── example2_java_app/  # Java example application 2
│   │   ├── hello_springboot_app/  # Spring Boot hello world application
│   │   └── rs_springboot_app/     # Spring Boot RESTful service application
│   ├── py/                     # Python applications and libraries
│   │   ├── calculator_cli_py_app/  # CLI calculator utility
│   │   ├── calculator_flask_app/   # Flask calculator web app
│   │   ├── devops_fastapi_app/     # FastAPI app with DevOps features
│   │   ├── echo_fastapi_app/       # Simple FastAPI application
│   │   └── helloworld_py_app/      # Basic Python application
│   ├── template/               # Project templates
│   │   ├── template_fastapi_app/    # FastAPI application template with PostgreSQL and Istio
│   │   ├── template_gin_app/        # Gin (Go) application template
│   │   └── template_typer_app/      # Typer CLI application template
│   ├── microservices-demo/     # Microservices demonstration projects
│   └── opentelemetry-demo/     # OpenTelemetry demonstration projects
├── libs/                       # Shared libraries and utilities
├── third_party/                # Third-party dependencies
├── tools/                      # Development and build tools
├── docs/                       # Documentation files and guides
│   ├── infrastructure-comparison.md  # Terraform vs Pulumi implementation analysis
│   ├── quick-start-guide.md          # Quick start guide for new users
│   ├── rate-limiting.md              # Documentation for Istio rate limiting
│   └── contributing/                  # Contribution guidelines
├── terraform_dev_local/        # Terraform configurations for local development
├── pulumi_dev_local/           # Pulumi configurations for local development
├── terraform_lab_gcp/          # Terraform configurations for GCP
├── .bazelignore                # Files and directories to ignore in Bazel builds
├── .bazelrc                    # Bazel configuration
├── BUILD.bazel                 # Root BUILD file
├── MODULE.bazel                # Bazel module definition
├── WORKSPACE                   # Bazel workspace definition (legacy)
└── skaffold.yaml               # Root Skaffold configuration

Project Catalog

Project	Description	Technologies	Status
template_fastapi_app	FastAPI application template with PostgreSQL, JWT auth, Istio rate limiting, and OpenTelemetry	Python, FastAPI, PostgreSQL, K8s, Istio	✅ Active
terraform_dev_local	Local development environment with essential K8s components	Terraform, Kubernetes, Helm	✅ Active
pulumi_dev_local	Local development environment with essential K8s components	Pulumi, Kubernetes, Helm	✅ Active
echo_fastapi_app	Simple FastAPI application	Python, FastAPI	✅ Active
calculator_cli_py_app	Command-line calculator utility	Python	✅ Active
devops_fastapi_app	FastAPI application with DevOps features	Python, FastAPI	✅ Active
calculator_flask_app	Flask-based calculator web application	Python, Flask	✅ Active
helloworld_py_app	Basic Python application	Python	✅ Active
template_gin_app	Gin application template	Go, Gin	✅ Active
template_typer_app	Typer CLI application template	Python, Typer	✅ Active
simple_java_app	Basic Java application	Java	✅ Active
hello_springboot_app	Spring Boot hello world application	Java, Spring Boot	✅ Active
rs_springboot_app	Spring Boot RESTful service application	Java, Spring Boot, REST	✅ Active
base_fastapi_app	Base FastAPI project to extend	Python, FastAPI	✅ Active
devops_go_app	Simple Go application example	Go	✅ Active
microservices-demo	Microservices demonstration projects	Various	✅ Active
opentelemetry-demo	OpenTelemetry demonstration projects	Various	✅ Active

Featured Project: FastAPI Template App

The FastAPI Template App provides a production-ready starting point for building robust API services. It integrates FastAPI, PostgreSQL, JWT authentication, Alembic migrations, Kubernetes deployment via Skaffold, OpenTelemetry, and Istio rate limiting.

For full details, features, and getting started instructions, please see the FastAPI Template App README.

Local Development Environment Options

This repository offers two parallel implementations for provisioning a local Kubernetes development environment populated with essential infrastructure components (like service mesh, cert management, observability, etc.). Both options provide feature parity.

Terraform-based Local Development Environment

Located in the terraform_dev_local directory, this option uses Terraform (HCL) to manage Kubernetes components via Helm charts.

For setup instructions, component details, and usage guidance, refer to the Terraform Local Dev README.

Pulumi-based Local Development Environment

Located in the pulumi_dev_local directory, this option uses Pulumi (Go) to manage the same set of Kubernetes components via Helm charts.

For setup instructions, component details, and usage guidance, refer to the Pulumi Local Dev README.

Managing Infrastructure Components

The specific components available (like Istio, Cert Manager, Argo CD, OpenTelemetry, etc.) and their configuration details are documented within each respective local development environment directory:

• Terraform Components: terraform_dev_local/docs/COMPONENTS.md
• Pulumi Components: pulumi_dev_local/docs/COMPONENTS.md

Both implementations strive to maintain feature and version parity for these components.

For guidance on contributing new or complex infrastructure components applicable to both Terraform and Pulumi, please refer to:

• Infrastructure Comparison: Terraform vs Pulumi - Comprehensive analysis of our implementations
• Contributing Complex IAC Components - Guidelines for adding new components

Getting Started (Application Development)

See the Quick Start Guide for end-to-end environment setup and workflow details. Below is a concise orientation:

1. Install: Bazel, Skaffold, Docker (optionally Colima for local k8s)
2. Provision infra (optional): choose either Terraform local dev or Pulumi local dev
3. Generate a project (service, CLI, etc.): see Project Generation
4. Manage dependencies & drift: see Dependency Management
5. Develop & iterate: use Skaffold profiles (skaffold dev -m <module> -p dev)
6. Validate: run Bazel builds/tests and any template-specific docs

Common Skaffold workflow:

skaffold build     # Build images
skaffold run       # Deploy once
skaffold dev -m template-fastapi-app -p dev  # Iterative dev
skaffold test      # Run tests
skaffold verify    # Smoke/verification
skaffold delete    # Cleanup

Quick Project Creation

For full template matrix, flags, and examples see Project Generation.

Minimal examples:

# Interactive
bazel run //tools:new_project

# FastAPI service
bazel run //tools:new_project -- --language python --project-type fastapi --project-name my_service

# List templates
bazel run //tools:new_project -- --list-templates

Dependency Management

Python dependency model, lock export process, and drift enforcement are documented in Dependency Management. See that doc for update workflow, enforcement layers (pre-commit, Bazel test, CI), and Copier pin alignment.

Python (uv-first workflow)

This repo standardizes on uv for Python dependency resolution & locking:

Artifact	Purpose
third_party/python/pyproject.toml	Declarative spec (runtime + groups)
third_party/python/uv.lock	uv resolver lock (do not edit)
third_party/python/requirements_lock_3_11.txt	Hashed export consumed by Bazel rules_python
//third_party/python:requirements_3_11.update	Bazel target to regenerate lock + export
//third_party/python:requirements_drift_test	Fails if exported requirements drift from spec

Common tasks:

# Add or bump a dependency
$EDITOR third_party/python/pyproject.toml

# Regenerate lock + export
bazel run //third_party/python:requirements_3_11.update

# Verify no drift
bazel test //third_party/python:requirements_drift_test

# (Optional) Local venv for iterative dev (installs uv if missing)
./scripts/setup_uv_env.sh --groups tooling,test,scaffolding
source .uv-venv/bin/activate

See third_party/python/README.md for full details.

Supported Languages and Project Types

Language	Project Type	Status	Template Source	Description
Python	FastAPI	✅ Available	template_fastapi_app	Production-ready FastAPI web service with PostgreSQL, JWT auth, and Kubernetes deployment
Python	CLI	✅ Available	template_typer_app	Command-line application using Typer framework
Python	Flask	🚧 Placeholder	-	Web application using Flask framework
Go	Gin	✅ Available	template_gin_app	Web service using Gin web framework
Go	CLI	🚧 Placeholder	-	Command-line application in Go
Java	Spring Boot	🚧 Placeholder	-	Web service using Spring Boot framework

Legend:

• ✅ Available: Full template with complete project structure
• 🚧 Placeholder: Creates basic project structure; template coming soon

Example Usage

# Interactive mode - prompts for all options
bazel run //tools:new_project

# Follow the prompts to select:
# 1. Language (python, go, java)
# 2. Project type (fastapi, cli, gin, springboot, etc.)
# 3. Project name (e.g., my_awesome_api)

The generator will:

1. Create a new project directory in projects/{language}/{project_name}
2. Copy the appropriate template (if available) or create a placeholder project
3. Customize the project with your chosen name and details
4. Provide next steps for development

Documentation

For comprehensive documentation about this repository:

• Infrastructure Comparison - Analysis of our Terraform and Pulumi implementations
• Quick Start Guide - Getting started with this repository
• Rate Limiting Guide - Documentation for Istio rate limiting
• Bazel Cheat Sheet - Reference for common Bazel commands
• Container Guidelines - Guidelines for working with containers
• Build Fixes - Solutions for common build issues

See the Documentation Index for a complete listing of available documentation.

Contributing

Contributions are welcome! Please follow standard Git workflow (fork, branch, pull request). Ensure Bazel builds and tests pass. Update relevant documentation for any changes.

For contribution guidelines, please see:

• Contributing to Infrastructure Components
• Contributing to Applications
• Contributing to Platform

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.