Status
Back to Developer Docs

Blueberry IDP Architecture

Comprehensive insights into how the Internal Developer Platform is designed, deployed, and operates.

Overview

The Blueberry IDP is built as a modern, cloud-native platform that automates the creation and management of ephemeral development environments using GitOps principles.

Architecture Diagrams

App-of-Apps Pattern

App of Apps Architecture

The platform uses ArgoCD's App-of-Apps pattern to manage multiple applications and environments in a hierarchical structure.

Core Components

🌐

Networking & Ingress

Learn about the networking architecture, static IP management, ingress setup, and traffic flow.

🔐

Authentication & Security

Firebase Auth integration, API tokens, RBAC, and comprehensive security policies.

🚀

GitOps & ArgoCD

Coming Soon - How ArgoCD manages deployments using the App-of-Apps pattern.

🐳

Container Management

Coming Soon - Artifact Registry, image management, and container security.

☁️

Infrastructure

Coming Soon - GKE Autopilot, Terraform modules, and cloud resource management.

⚙️

Configuration & Secrets

Comprehensive guide to configuration management and secrets handling with Google Secret Manager.

System Architecture

Infrastructure

  • Kubernetes: GKE Autopilot (serverless Kubernetes)
  • CI/CD: ArgoCD with App-of-Apps pattern, GitLab
  • IaC: Terraform for base infrastructure
  • Storage: Firestore (metadata) + GCS (artifacts/logs)
  • Auth: Firebase Auth (internal + external users)

Application Layer

  • Backend: Python FastAPI
  • Frontend: HTMX + Alpine.js (server-side rendered)
  • Templates: Jinja2
  • Cache: Redis (deployed as Helm sub-chart)

Key Design Principles

GitOps First: All deployments through ArgoCD, no direct kubectl operations
Ephemeral by Design: Environments are temporary and easily cleaned up
Cost Conscious: Leverages free tiers and minimal resource allocation
Developer Experience: Simple API with intuitive web interface

Environment Lifecycle

Main Lifecycle Flow

1
Pull Request
Created
→
2
Webhook
Triggered
→
3
Generate
Config
→
4
Create ArgoCD
Application
↓
5
Start Resource
Provisioning
→
6
Environment
Active
→
7
Delete
Request
→
8
Resources
Cleaned Up

Error Handling

Provisioning Failed

If step 5 fails:

  • • Manual cleanup option
  • • Retry provisioning
  • • Error notification sent

Retry Mechanism

Automatic retry logic:

  • • Returns to step 5
  • • Limited retry attempts
  • • Exponential backoff

Environment lifecycle from creation to deletion with error handling

Resource Organization

Naming Conventions

  • Environments: pr-{number} or {custom-name}
  • Namespaces: {env-id}
  • ArgoCD Apps: env-{env-id}
  • DNS: {env-name}.ephemeral.blueberry.florenciacomuzzi.com

Directory Structure

blueberry-terraform/     # Infrastructure as Code
argocd-apps/            # ArgoCD application definitions
blueberry/              # Core application code
  src/                  # FastAPI backend
  helm/                 # Helm charts
  templates/            # Jinja2 templates for ArgoCD apps
charts/                 # Helm charts
tests/                  # Test suites

Getting Started

To understand how all these components work together:

  1. 1. Start with Networking & Ingress to understand traffic flow
  2. 2. Review the Authentication & Security setup
  3. 3. Dive into GitOps workflows (coming soon)
  4. 4. Explore infrastructure provisioning (coming soon)

This documentation is continuously updated as the platform evolves. For the latest technical details, check the GitLab repository.