Blueberry IDP Components

This directory contains detailed documentation for each major component of the Blueberry Internal Developer Platform.

Component Overview

Core Components

Application Components

Frontend (UI)

• Technology: HTMX + Alpine.js + Tailwind CSS
• Purpose: Server-side rendered web interface
• Key Features:
• Real-time updates via Server-Sent Events
• Minimal JavaScript footprint
• Progressive enhancement
• Mobile-responsive design

Backend API

• Technology: Python FastAPI
• Purpose: RESTful API and business logic orchestration
• Key Features:
• Async request handling
• OpenAPI documentation
• Firebase authentication
• Dependency injection

Service Components

Environment Manager

• Purpose: Manages the lifecycle of ephemeral environments
• Responsibilities:
• Create/update/delete environments
• Monitor environment health
• Handle cleanup and teardown
• Manage ArgoCD applications

Config Manager

• Purpose: Handles configuration and overrides
• Features:
• Configuration sets
• Environment-specific overrides
• Secret management
• Template rendering

Auth Service

• Purpose: Authentication and authorization
• Features:
• Firebase Auth integration
• API token management
• Role-based access control
• Session management

Webhook Handler

• Purpose: Processes Git provider webhooks
• Features:
• PR open/close events
• Push notifications
• Status updates
• Auto-cleanup triggers

Data Components

Redis Cache

• Purpose: High-performance caching layer
• Use Cases:
• Session storage
• Environment status caching
• Rate limiting
• Temporary data

Firestore Database

• Purpose: Primary data persistence
• Collections:
• Environments
• Users
• API Tokens
• Audit Logs
• Configuration Sets

Google Cloud Storage

• Purpose: Object storage for artifacts
• Use Cases:
• Build artifacts
• Application logs
• Backup data
• Static assets

Secret Manager

• Purpose: Secure secret storage
• Features:
• API token storage
• Service account keys
• Database credentials
• Third-party integrations

Infrastructure Components

ArgoCD

• Purpose: GitOps deployment controller
• Features:
• Application synchronization
• Automated rollouts
• Drift detection
• Multi-environment support

Kubernetes (GKE)

• Purpose: Container orchestration platform
• Features:
• GKE Autopilot (serverless)
• Namespace isolation
• Network policies
• Resource quotas

Crossplane

• Purpose: Cloud resource provisioning
• Features:
• Infrastructure as Code
• Cloud-native APIs
• Resource composition
• Provider abstraction

Component Interactions

Request Flow

1. User/CI makes request to Frontend/API
2. API authenticates request via Firebase
3. API delegates to appropriate service
4. Service interacts with data layer
5. Service creates Kubernetes resources via ArgoCD
6. Response returned to user

Data Flow

1. Metadata stored in Firestore
2. Transient data cached in Redis
3. Artifacts stored in GCS
4. Secrets stored in Secret Manager
5. Configurations synced via Git

Deployment Flow

1. ArgoCD monitors Git repository
2. Changes trigger application sync
3. Kubernetes resources created/updated
4. Crossplane provisions cloud resources
5. Environment becomes available

Component Guidelines

Design Principles

• Single Responsibility: Each component has one clear purpose
• Loose Coupling: Components communicate via well-defined interfaces
• High Cohesion: Related functionality grouped together
• Stateless Design: No local state in application components
• Fault Tolerance: Graceful degradation on component failure

Communication Patterns

• Synchronous: REST API calls for immediate responses
• Asynchronous: Background jobs for long-running operations
• Event-Driven: Webhooks and SSE for real-time updates
• Polling: Health checks and status monitoring

Security Considerations

• Authentication: All components verify identity
• Authorization: Role-based access control
• Encryption: TLS for all network communication
• Secrets: Never stored in code or logs
• Audit: All actions logged with user context

Adding New Components

When adding a new component:

1. Document Purpose: Clear explanation of why it exists
2. Define Interface: API contracts and data schemas
3. Security Review: Authentication and authorization requirements
4. Integration Points: How it connects to existing components
5. Monitoring: Metrics, logs, and health checks
6. Testing Strategy: Unit, integration, and E2E tests

Component Health

Each component should provide:
- Health check endpoint
- Readiness probe
- Metrics exposure
- Structured logging
- Error reporting

Related Documentation

• System Architecture
• Deployment Architecture
• Security Architecture
• API Reference