https://github.com/tamylaa/clodo-framework
Cloudflare Workers Automation Framework for Architects, Engineers, Developers and Product Integration Professionals to accelerate Serverless Compute with CLI commands. Reduce development costs and improve productivity with wrangler automation. Irresistible SaaS Infrastructure Toolkit
https://github.com/tamylaa/clodo-framework
automation cloudflare cloudflare-workers deployment edge-computing enterprise framework orchestration saas serverless
Last synced: 4 days ago
JSON representation
Cloudflare Workers Automation Framework for Architects, Engineers, Developers and Product Integration Professionals to accelerate Serverless Compute with CLI commands. Reduce development costs and improve productivity with wrangler automation. Irresistible SaaS Infrastructure Toolkit
- Host: GitHub
- URL: https://github.com/tamylaa/clodo-framework
- Owner: tamylaa
- License: mit
- Created: 2025-09-29T07:01:05.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-11T03:19:59.000Z (12 days ago)
- Last Synced: 2026-02-11T08:36:23.853Z (12 days ago)
- Topics: automation, cloudflare, cloudflare-workers, deployment, edge-computing, enterprise, framework, orchestration, saas, serverless
- Language: JavaScript
- Homepage: https://clodo.dev
- Size: 7.94 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: docs/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: docs/SUPPORT.md
Awesome Lists containing this project
README
# Clodo Framework
[](https://github.com/tamylaa/clodo-framework/actions/workflows/validate-on-pr.yml) [](https://github.com/tamylaa/clodo-framework/actions/workflows/full-tests-nightly.yml) [](https://www.npmjs.com/package/@tamyla/clodo-framework) [](https://www.npmjs.com/package/@tamyla/clodo-framework) [](https://github.com/tamylaa/clodo-framework/blob/main/LICENSE) [](https://github.com/sponsors/tamylaa) [](SUPPORT.md) [](https://www.buymeacoffee.com/yourname) [](https://www.patreon.com/yourname) [](https://paypal.me/yourname)
## ๐ Production-Ready: Promise Delivered
**Framework Status: โ
VALIDATED & PRODUCTION-READY**
**Validation: 10/10 Phases Passed**
**Service Generation: 28+ Files Per Service**
**Test Coverage:** (Latest CI run 2026-02-18) โ **124 test suites passed; 1 skipped; 2328 passed, 2352 total**
A comprehensive framework for building enterprise-grade software architecture on Cloudflare Workers + D1. This framework enables rapid development of autonomous, domain-specific services while maintaining consistency and reusability across your entire ecosystem.
> **โ
VALIDATED PROMISE**: Through comprehensive testing and validation, the Clodo Framework has been proven to deliver on its core promise of automated Cloudflare service creation. See [Framework Evolution Narrative](docs/FRAMEWORK_EVOLUTION_NARRATIVE.md) for the complete development story.
## ๐ Documentation
### ๐ **Quick Start** (5 minutes)
- **[Developer Quick Start](docs/00_START_HERE.md)** - Get running immediately
- **[Simple API Guide](docs/SIMPLE_API_GUIDE.md)** - Quick examples and usage
### ๐ง **API Reference**
- **[Programmatic API](docs/api/PROGRAMMATIC_API.md)** - Complete programmatic usage
- **[Parameter Reference](docs/api/parameter_reference.md)** - All parameters and validation
- **[Error Reference](docs/errors.md)** - Error codes and troubleshooting
- **[Utilities Guide](docs/utilities/README.md)** - Cloudflare API extensions and integrations
### ๐ **Guides & Migration**
- **[Getting Started](docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md)** - Step-by-step tutorial
- **[Migration Guide](docs/MIGRATION.md)** - CLI to programmatic APIs
- **[Framework Overview](docs/overview.md)** - Philosophy and concepts
### ๐๏ธ **Architecture & Security**
- **[Security](docs/SECURITY.md)** - Security considerations
- **[Framework Evolution](docs/FRAMEWORK_EVOLUTION_NARRATIVE.md)** - Development history
## ๐งโ๐คโ๐ง Community & Support
- **Email:** `product@clodo.dev` โ product support, feedback, and security reports
- **Twitter:** [@clodoframework](https://twitter.com/clodoframework) โ follow for updates and announcements
- **Quick ways to help:**
- โญ Star the repository on GitHub
- ๐ Open issues for bugs or feature ideas
- ๐ Submit PRs or reviews (even small documentation fixes are welcome)
- ๐ฃ๏ธ Share your experience on Twitter and tag **@clodoframework**
Your feedback helps prioritize improvements and signals others that this project is useful.
- **Support & SLAs:** See [SUPPORT.md](SUPPORT.md) for response times and escalation procedures.
- **Donate / Sponsor:** If you'd like to support ongoing maintenance and improvements, please see [FUNDING.md](FUNDING.md) for ways to contribute (GitHub Sponsors, Open Collective, PayPal, Buy Me a Coffee, Patreon).
### ๐ **Documentation Structure**
```
โโโ docs/ # ๐ Public documentation (npm package)
โ โโโ 00_START_HERE.md # ๐ Quick start guide
โ โโโ README.md # ๐ Documentation index
โ โโโ overview.md # ๐๏ธ Framework philosophy
โ โโโ api/ # ๐ง API documentation
โ โโโ integration/ # ๐ Integration guides
โ โโโ architecture/ # ๐๏ธ Technical architecture
โโโ i-docs/ # ๐ Internal documentation (private)
โโโ commercialization/ # ๐ผ Business strategy
โโโ roadmap/ # ๐บ๏ธ Development planning
โโโ analysis/ # ๐ Technical analysis
```
### ๐ท๏ธ **Document Types**
- **๐ Public** (`docs/`) - Developer usage, API reference, examples
- **๐ Internal** (`i-docs/`) - Business strategy, implementation details, planning
## ๐ฏ Key Achievements
### โ
**Three-Tier Service Creation**
- **Input Collection**: Intelligent gathering of service requirements
- **Smart Confirmations**: 15 derived values with user review
- **Automated Generation**: 28+ production-ready files instantly
### โ
**Comprehensive Validation**
- **10-Phase Testing**: Complete end-to-end validation framework
- **Production Readiness**: Services deployable to Cloudflare immediately
- **Quality Assurance**: 98.9% test success rate with enterprise standards
### โ
**Professional Features**
- **Deployment Automation**: One-click deployment scripts
- **Service Enhancement**: APIs for customizing generated services
- **Enterprise Integration**: CI/CD pipeline ready
- **Developer Experience**: Interactive wizards and comprehensive docs
## ๐งช Comprehensive Validation Results
The Clodo Framework has undergone rigorous validation to ensure it delivers on its promises:
```
๐ COMPREHENSIVE VALIDATION COMPLETE!
====================================
โ
Service Generation: PASSED (28+ files created)
โ
Structure Validation: PASSED (All required files present)
โ
Package Configuration: PASSED (NPM setup validated)
โ
Worker Code Validation: PASSED (Cloudflare compatibility)
โ
Service Installation: PASSED (Dependencies resolved)
โ
Service Execution: PASSED (Runtime functionality)
โ
Deployment Scripts: PASSED (Automation verified)
โ
API Documentation: PASSED (Complete docs generated)
โ
Service Manifest: PASSED (Metadata tracking)
โ
Enhancement Capabilities: PASSED (Customization APIs)
```
**Validation Framework**: 10-phase comprehensive testing ensuring production readiness.
## ๐ฆ Service Generation Capabilities
**What You Get**: Complete, production-ready Cloudflare services with one command:
### Core Service Files (28+ generated)
- `package.json` - NPM configuration with dependencies
- `wrangler.toml` - Cloudflare deployment configuration
- `src/worker/index.js` - Main Cloudflare Worker implementation
- `src/handlers/service-handlers.js` - CRUD operation handlers
- `src/middleware/service-middleware.js` - Request processing middleware
- `src/utils/service-utils.js` - Service utility functions
- `src/schemas/service-schema.js` - Data validation schemas
### Deployment & Configuration
- `scripts/deploy.ps1` - PowerShell deployment automation
- `scripts/setup.ps1` - Environment setup script
- `scripts/health-check.ps1` - Service health validation
- `config/*.env` - Environment-specific configurations
- `.env.example` - Configuration template
### Documentation & Metadata
- `README.md` - Complete service documentation
- `clodo-service-manifest.json` - Service metadata and tracking
- `API_DOCUMENTATION.md` - API endpoint documentation
### Enhancement Capabilities
- **Handler Customization**: Add/modify CRUD operations
- **Middleware Extension**: Custom request processing
- **Configuration Override**: Environment-specific settings
- **Template Enhancement**: Service-specific customizations
### Cloudflare API Utilities (v4.4.0+)
- **AI Integration**: Workers AI for text generation, analysis, and embeddings
- **Storage Solutions**: R2 object storage and KV key-value store
- **Real-time Features**: Queues for messaging, Durable Objects for state
- **Advanced Analytics**: Custom metrics and performance monitoring
- **Email Processing**: Inbound/outbound email handling
- **Vector Databases**: AI-powered semantic search capabilities
> **๐ก Utilities are optional extensions** - use them when you need advanced Cloudflare features. See [Utilities Guide](docs/utilities/README.md) for integration examples.
## ๐ Three-Tier Service Creation
The Clodo Framework implements a sophisticated three-tier service creation process that transforms your requirements into production-ready Cloudflare services:
### Tier 1: Input Collection
**What happens**: Intelligent gathering of your service requirements
**Inputs collected**: Service name, type, domain, Cloudflare credentials
**Smart features**: Input validation, format checking, credential verification
### Tier 2: Smart Confirmations
**What happens**: Generation of 15 derived configuration values
**Intelligence**: URL formatting, resource naming, dependency calculation
**User control**: Review and modify all generated values before creation
### Tier 3: Automated Generation
**What happens**: Instant creation of complete, production-ready services
**Output**: 28+ files including worker code, configs, scripts, and documentation
**Quality**: Enterprise-grade code with security, monitoring, and best practices
### Usage Examples
#### Interactive Service Creation
```bash
# Start interactive service creation wizard
npx @tamyla/clodo-framework clodo-service
# Framework will guide you through:
# 1. Service name and type selection
# 2. Domain and Cloudflare configuration
# 3. Review of 15 generated configuration values
# 4. Instant service generation
```
#### Programmatic Service Creation
```javascript
import { ServiceOrchestrator } from '@tamyla/clodo-framework';
const orchestrator = new ServiceOrchestrator();
await orchestrator.createService({
serviceName: 'my-api-service',
serviceType: 'data-service',
domain: 'mycompany.com',
cloudflareToken: 'your-token',
cloudflareAccountId: 'account-id',
cloudflareZoneId: 'zone-id'
});
```
#### Service Enhancement
```javascript
import { ServiceCreator } from '@tamyla/clodo-framework';
// Create and configure a new service
const creator = new ServiceCreator();
await creator.createService({
serviceName: 'my-api-service',
serviceType: 'data-service',
domain: 'mycompany.com'
});
```
## Two Ways to Use Clodo Framework
### ๐ฆ As a Library (Public API)
Import framework modules into your project for programmatic use:
```javascript
// Import core services
import { GenericDataService } from '@tamyla/clodo-framework/services';
import { EnhancedRouter } from '@tamyla/clodo-framework/routing';
import { CloudflareAPI } from '@tamyla/clodo-framework/utils/cloudflare';
import { DeploymentOrchestrator } from '@tamyla/clodo-framework/deployment';
// Use framework utilities
const api = new CloudflareAPI(token);
const zones = await api.listZones();
```
**All public exports are defined in `package.json`** - use only these documented paths.
### ๐ง As CLI Tools (Commands)
Run framework commands in your terminal:
```bash
# Create a new service
clodo-service create
# Deploy your service
clodo-service deploy
# Validate service configuration
clodo-service validate
# Preflight health checks before deployment
clodo-service doctor
# Scan for leaked secrets
clodo-service secrets scan
# Validate config files against schemas
clodo-service config-schema validate clodo-deploy.json
# Security auditing
clodo-security audit
```
**CLI tools are for terminal use only** - they use interactive prompts, colored output, and are not meant for programmatic import.
### โ ๏ธ Important: Don't Import from `dist/bin/`
The `bin/` directory contains CLI implementation details and should **never** be imported directly:
```javascript
// โ WRONG - Don't do this
import { healthCheckWithBackoff } from '@tamyla/clodo-framework/dist/bin/shared/monitoring/health-checker.js';
import { deploymentUI } from '@tamyla/clodo-framework/dist/bin/commands/helpers/deployment-ui.js';
// โ
CORRECT - Use public API
import { DeploymentOrchestrator } from '@tamyla/clodo-framework/deployment';
import { CloudflareAPI } from '@tamyla/clodo-framework/utils/cloudflare';
```
If you need functionality that's currently only in `bin/`, please open an issue - we'll consider adding it to the public API.
---
## How to consume (quick)
A short guide and best practices for consuming `@tamyla/clodo-framework` are available in the docs: [docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md](./docs/HOWTO_CONSUME_CLODO_FRAMEWORK.md). This file includes quickstart steps, public export guidance, CLI usage, and troubleshooting tips for packaged artifacts.
If you'd like this information added to `clodo.dev`, I can prepare a small website PR as well.
## Project Structure
The project is organized for maximum clarity and maintainability:
```
clodo-framework/
โโโ docs/ # ๐ Public documentation
โ โโโ strategic/ # Business strategy & planning
โ โโโ utilities/ # Utility integration guides
โ โโโ api/ # API reference & guides
โ โโโ integration/ # Integration & migration guides
โ โโโ phases/ # Framework development phases
โโโ i-docs/ # ๐ Internal documentation (organized by category)
โ โโโ architecture/ # Design docs, audits, specs
โ โโโ development/ # Dev guides, improvements
โ โโโ testing/ # Test plans, validation
โ โโโ deployment/ # Deployment analysis, fixes
โ โโโ roadmap/ # Strategic planning
โ โโโ guides/ # Integration guides
โ โโโ session-reports/ # Development sessions
โ โโโ phases/ # Phase completions
โ โโโ analysis/ # Technical analysis
โ โโโ licensing/ # License information
โโโ src/ # ๐ป Source code
โโโ test/ # โ
Test suites (Latest CI: 124 suites; 2328 tests passed, 24 skipped)
โโโ cli/ # ๐ง CLI tools & commands
โโโ examples/ # ๐ Usage examples & demos
โโโ config/ # โ๏ธ Configuration files & examples
โโโ scripts/ # ๐ ๏ธ Build & utility scripts
โโโ templates/ # ๐ Service templates
โโโ dist/ # ๐ฆ Built distribution
โโโ lib/ # ๐ Compiled libraries
โโโ .logs/ # ๐ Log files (hidden)
โโโ .tmp/ # ๐๏ธ Temporary files (hidden)
โโโ backups/ # ๐พ Backup files
โโโ deployments/ # ๐ Deployment artifacts
โโโ secrets/ # ๐ Secret management
โโโ coverage/ # ๐ Test coverage reports
```
**Quality Metrics:**
- โ
**Latest CI (2026-02-18): 124 test suites passed; 1 skipped; 2328/2352 tests passed**
- โ
**CLI tests:** passing (all CLI-specific tests passed in the latest run)
- โ
**Clean architecture** (organized file structure, no clutter in root)
- โ
**Configuration-based** (no hard-coded values in source)
## ๐ Incremental Adoption
Already have an existing project? The Clodo Framework is designed for **gradual integration** - you don't need to rewrite everything at once. Start with individual components and scale up as needed.
### **Quick Start Options**
- **Greenfield Development**: Use `npx @tamyla/clodo-framework clodo-service` for new projects
- **Existing Projects**: Import individual utilities, then add configuration management, then full deployment automation
- **Migration Path**: Follow our [Integration Guide](./docs/INTEGRATION_GUIDE.md) for step-by-step migration strategies
### **Adoption Phases**
1. **Phase 1**: Import core utilities (logging, validation, error handling)
2. **Phase 2**: Add configuration management and environment handling
3. **Phase 3**: Integrate deployment automation and security validation
4. **Phase 4**: Full framework adoption with orchestration and monitoring
> **Pro Tip**: Most teams start with Phase 1 utilities and gradually adopt more features. See [Adopting Clodo Framework in Existing Projects](./docs/INTEGRATION_GUIDE.md#incremental-adoption) for detailed guidance.
## ๏ฟฝ๐ Security-First Architecture
The Clodo Framework implements **security-by-default** principles, ensuring that insecure configurations cannot reach production environments. Our comprehensive security validation framework automatically detects and prevents:
- **Dummy API Keys**: Prevents deployment of development/test keys to production
- **Weak Secrets**: Blocks passwords shorter than security requirements
- **Insecure URLs**: Enforces HTTPS in production, blocks localhost in live environments
- **JWT Security**: Validates JWT secret strength and entropy
- **Environment Compliance**: Different security rules for dev/staging/production
### Security Integration
Security validation is **automatically applied** to all deployments through framework hooks:
```javascript
// Security validation runs automatically on every deployment
hooks: {
'pre-deployment': async (context) => {
const issues = ConfigurationValidator.validate(config, environment);
if (criticalIssues.length > 0) {
throw new Error('๐ซ Deployment blocked due to critical security issues');
}
}
}
```
### Quick Security Setup
```bash
# Generate secure keys
npx @tamyla/clodo-framework security generate-key jwt
npx @tamyla/clodo-framework security generate-key api content-skimmer
# Validate configuration security
npx @tamyla/clodo-framework security validate customer production
# Scan source code for leaked secrets
clodo-service secrets scan
# Validate secrets against baseline
clodo-service secrets validate
# Run preflight security checks
clodo-service doctor
# Deploy with automatic security validation
npx @tamyla/clodo-framework security deploy customer production
```
## Current Status โ
### **Working Features**
- โ
**Interactive Domain Selection**: Choose domains from discovered services
- โ
**Real Cloudflare Worker Deployment**: Actual wrangler-based deployment
- โ
**Domain Discovery & Validation**: Comprehensive Cloudflare integration
- โ
**API Token Management**: Secure encrypted storage and validation
- โ
**Service Directory Intelligence**: Smart service discovery by domain configuration
- โ
**Production Testing Suite**: Comprehensive post-deployment validation
- โ
**Deployment Auditing**: Complete audit trails and logging
- โ
**Graceful Error Handling**: D1 permission graceful degradation
- โ
**Cross-Platform Support**: Windows PowerShell and Linux compatibility
- โ
**๐ Security Validation Framework**: Automated security validation and deployment blocking
- โ
**๐ก๏ธ Cryptographic Key Generation**: Secure API key and JWT secret generation
- โ
**๐ซ Deployment Security**: Pre-deployment validation that blocks insecure configurations
- โ
**๐ฉบ Doctor / Preflight Checks**: Automated environment, dependency, and connectivity validation before deploy
- โ
**๐ Secret Scanning & Baseline**: Detect leaked secrets in source code with baseline management
- โ
**๐ Config Schema Validation**: Zod-powered schema validation for all CLI config files (create, deploy, validate, update)
- โ
**๐ฅ Customer Configuration Management**: Multi-environment, multi-customer configuration system
- โ
**๐๏ธ Template-Based Customer Onboarding**: Automated customer setup from reusable templates
- โ
**๐ Framework Integration**: Customer configs integrate with domain and feature flag systems
- โ
**๐ TypeScript Support**: Comprehensive type definitions with 500+ lines of TypeScript interfaces
- โ
**โก Performance Caching**: Schema caching, SQL query caching, and validation result caching
- โ
**๐ Enhanced Data Services**: Advanced pagination, relationship loading, and query optimization
### **Core Capabilities**
- **Enterprise Deployment System**: Multi-domain deployment orchestration with validation
- **Domain Configuration Management**: Centralized configuration with runtime discovery
- **API Token Security**: AES-256-CBC encrypted storage with automatic prompting
- **Service Autonomy**: Each service can discover and deploy itself independently
- **Comprehensive Validation**: Network, authentication, configuration, and endpoint validation
- **๐ Security-by-Default**: Automatic detection and prevention of insecure configurations
- **๐ก๏ธ Production Security**: Environment-specific security requirements and validation
- **๐ Cryptographic Utilities**: Secure key generation and secret management
- **๐ฉบ Doctor / Preflight**: Automated pre-deployment environment checks with `--skip-doctor` / `--doctor-strict` flags
- **๐ Secret Scanning**: Source code secret detection, pattern matching, and baseline management
- **๐ Config Schema Validation**: Zod schemas for all config file types with semantic warnings
- **Production Testing**: Health checks, authentication flows, performance monitoring
- **Audit & Compliance**: Detailed deployment logging and reporting
- **๐ฅ Customer Configuration Management**: Multi-environment customer isolation and management
- **๐๏ธ Template-Based Onboarding**: Automated customer setup with reusable configuration templates
- **๐ Framework Integration**: Seamless integration with existing domain and feature flag systems
- **๐ TypeScript First**: Complete type safety with comprehensive type definitions and IDE support
- **โก Performance Optimized**: Intelligent caching system for schemas, SQL queries, and validation results
- **๐ Advanced Data Operations**: Enhanced CRUD with relationships, advanced pagination, and query optimization
## ๐ What's New in v4.5.x
### ๐ฉบ Doctor / Preflight Command (v4.5.x)
Run comprehensive pre-deployment health checks to catch issues before they reach production:
```bash
# Run all preflight checks
clodo-service doctor
# Skip doctor during deploy
clodo-service deploy --skip-doctor
# Fail deploy on doctor warnings
clodo-service deploy --doctor-strict
```
**Checks performed:**
- โ
Node.js version compatibility
- โ
Required dependencies installed (wrangler, etc.)
- โ
Environment variables set
- โ
Cloudflare API connectivity
- โ
Config file schema validation
- โ
Secret baseline compliance
### ๐ Secret Scanning & Baseline Management (v4.5.x)
Detect leaked secrets in your codebase before they reach version control:
```bash
# Scan for secrets in source code
clodo-service secrets scan [directory]
# Validate against a known baseline
clodo-service secrets validate
# Show current baseline
clodo-service secrets baseline show
# Update baseline after review
clodo-service secrets baseline update
# List known secret patterns
clodo-service secrets patterns
```
**Features:**
- 15+ built-in secret patterns (AWS, Stripe, GitHub, JWT, etc.)
- Baseline management for known/accepted findings
- Integration with doctor preflight checks
- Programmatic API via `SecretsManager`
### ๐ Config Schema Validation (v4.5.x)
Validate your CLI config files against Zod schemas with semantic warnings:
```bash
# Validate a config file
clodo-service config-schema validate clodo-deploy.json
# Strict mode (exit code 1 on any error)
clodo-service config-schema validate clodo-create.json --strict
# Show schema for a config type
clodo-service config-schema show deploy
# List all supported config types
clodo-service config-schema types
```
**Supported config types:** `create`, `deploy`, `validate`, `update`
**Semantic warnings detect:**
- Environment variable placeholders left in values
- Duplicate features
- Production configs without security features
- Missing backup strategy with migrations enabled
- Name mismatches between config fields
### ๐ง Enhanced Customer Configuration System
The customer configuration CLI **reads directly from your wrangler.toml** file, providing a single source of truth for deployment configuration:
```bash
# List all customers with complete deployment metadata
npx @tamyla/clodo-framework customer list
# Specify custom config directory
npx @tamyla/clodo-framework customer list --config-dir /path/to/config
```
**What you see now:**
- โ
Account ID from wrangler.toml
- โ
Zone ID from wrangler.toml
- โ
Customer domain from environment config
- โ
Service domain from wrangler.toml
- โ
Worker name and database info
- โ
Secrets status
All **6 core deployment pieces** in one command - no more hunting through multiple files!
### โ๏ธ New CloudflareAPI Utility
Programmatic Cloudflare operations without CLI dependencies:
```javascript
import { CloudflareAPI } from '@tamyla/clodo-framework/utils/cloudflare';
const cf = new CloudflareAPI(apiToken);
// Verify token permissions
const isValid = await cf.verifyToken();
// List all zones/domains
const zones = await cf.listZones();
// Get zone details (account_id, zone_id, etc.)
const details = await cf.getZoneDetails(zoneId);
// List D1 databases
const databases = await cf.listD1Databases(accountId);
// Get complete deployment info
const info = await cf.getDeploymentInfo(zoneId);
```
### ๐ TOML Configuration Writing
Dynamic wrangler.toml updates from code:
```javascript
import {
updateWranglerToml,
addD1Database,
updateEnvironmentConfig
} from '@tamyla/clodo-framework/config/customers';
// Add a new D1 database binding
await addD1Database('production', 'my-database', 'database-uuid-123');
// Update environment config
await updateEnvironmentConfig('production', {
vars: { SERVICE_DOMAIN: 'api.example.com' }
});
// Update any wrangler.toml section
await updateWranglerToml({
name: 'my-worker',
compatibility_date: '2025-01-01'
});
```
### ๐งน Code Quality Improvements
- **Removed 180 lines** of duplicate secret management code
- **Consolidated Cloudflare utilities** under `src/utils/cloudflare/`
- **Single source of truth** for Cloudflare operations (API vs CLI)
- **Better organization** - clear separation between framework and CLI utilities
## ๐งช Downstream Service Testing & Validation
The CLODO Framework provides comprehensive capabilities for testing, validating, and deploying Cloudflare Workers in downstream environments - perfect for ensuring services work correctly in third-party accounts and production environments.
### **Production Testing Suite** ๐งช
Test deployed services across any Cloudflare account:
```javascript
import { ProductionTester } from '@tamyla/clodo-framework/deployment';
const tester = new ProductionTester({
verbose: true,
generateReport: true
});
// Test service in any environment
const results = await tester.runProductionTests('https://your-service.workers.dev', {
testSuites: ['health', 'authentication', 'database', 'performance']
});
```
**Available Test Suites:**
- **Health Checks**: Endpoint availability and response validation
- **Authentication**: JWT tokens, API keys, session management
- **Database**: D1 connectivity, query execution, transactions
- **Performance**: Response times, throughput, resource monitoring
- **Regression**: Compare against baseline metrics
### **Modular Testing Capabilities** ๐ง
For granular control, use individual testing modules:
```javascript
// Test only what you need
import { ApiTester, AuthTester, DatabaseTester } from '@tamyla/clodo-framework/deployment/testers';
// API testing only
const apiResults = await new ApiTester().runApiTests('production');
// Authentication testing only
const authResults = await new AuthTester().runAuthTests(baseUrl, testUser);
// Database testing only
const dbResults = await new DatabaseTester().runDatabaseTests('production');
```
**Individual Modules:**
- `ApiTester` - Endpoint and CRUD operation testing
- `AuthTester` - JWT, API keys, session management
- `DatabaseTester` - D1 connectivity and query validation
- `PerformanceTester` - Response times and throughput
- `LoadTester` - Scalability and concurrent user testing
### **Pre-Deployment Validation** โ
Comprehensive validation before deployment:
```javascript
import { DeploymentValidator } from '@tamyla/clodo-framework/deployment';
const validator = new DeploymentValidator({
validationLevel: 'comprehensive'
});
// Validate deployment readiness
const result = await validator.validateDeployment(['your-service.com'], {
environment: 'production'
});
```
**Validation Categories:**
- **Prerequisites**: Node.js, wrangler CLI, required files
- **Authentication**: Cloudflare API tokens and permissions
- **Network**: Connectivity and DNS resolution
- **Configuration**: Environment variables and wrangler.toml
- **Endpoints**: Service accessibility and response validation
- **Deployment**: Build process and resource availability
### **Third-Party Account Operations** โ๏ธ
Deploy and manage services across multiple Cloudflare accounts:
```javascript
import { CloudflareDomainManager } from '@tamyla/clodo-framework/deployment';
const manager = new CloudflareDomainManager({
apiToken: process.env.CUSTOMER_CLOUDFLARE_TOKEN
});
// Verify authentication in customer account
await manager.verifyAuthentication();
// Deploy to customer environment
await manager.deployService({
serviceName: 'data-service',
domain: 'customer-service.com'
});
```
**Multi-Account Features:**
- **Account Discovery**: Automatically detect available domains
- **Permission Validation**: Verify deployment permissions
- **Service Matching**: Intelligent domain-to-service mapping
- **Cross-Account Coordination**: Deploy across multiple accounts
### **Interactive Developer Involvement** ๐ฅ
When issues are detected, the framework actively involves developers:
```javascript
// Framework detects authentication issues and guides resolution
const authChoice = await askChoice(
'Cloudflare authentication needed. What would you like to do?',
[
'Login to Cloudflare now',
'Provide API token manually',
'Skip verification (limited features)',
'Cancel deployment'
]
);
```
### **Security-First Deployment** ๐
Automatic security validation prevents insecure deployments:
```javascript
import { deployWithSecurity } from '@tamyla/clodo-framework/security';
await deployWithSecurity({
customer: 'your-customer',
environment: 'production',
deploymentUrl: 'https://service.workers.dev'
});
```
**Security Validations:**
- **API Key Validation**: Blocks dummy/test keys in production
- **Secret Strength**: Enforces secure JWT secrets
- **Environment Compliance**: Different rules per environment
- **Configuration Auditing**: Logs all security decisions
### **Integration Examples**
**Post-Deployment Testing:**
```javascript
// Test service after deployment
const testResults = await tester.runProductionTests(deploymentUrl, {
testSuites: ['health', 'authentication', 'endpoints']
});
if (testResults.summary.failed > 0) {
console.error('โ Post-deployment tests failed');
await rollbackManager.rollback(deployment.id);
}
```
**Multi-Account Deployment:**
```javascript
// Deploy across customer accounts
const results = await Promise.allSettled(
customers.map(customer =>
deployToCustomerAccount(customer, serviceConfig)
)
);
```
> **๐ Complete Documentation**: See our [Integration Guide](./docs/INTEGRATION_GUIDE.md) and [Deployment Guide](./docs/deployment/deployment-guide.md) for comprehensive testing and validation documentation.
## ๏ฟฝ For Developers
If you're building services with the Clodo Framework, see our comprehensive [Developer Guide](./docs/guides/developer-guide.md) for:
- Installation and setup instructions
- Service creation and configuration
- Best practices for using public APIs
- Deployment patterns (embedding logic, not calling internal commands)
- Troubleshooting and common issues
### ๐ **Framework Architecture**
For an overview of the framework's architecture and design philosophy, see our [Architecture Overview](./docs/FRAMEWORK-ARCHITECTURE-OVERVIEW.md):
- Core components and usage patterns
- Library vs CLI tool approaches
- Intelligent features and orchestration
- Design principles and benefits
> **Note**: For detailed technical analysis and internal implementation details, see [FRAMEWORK-ARCHITECTURE-ANALYSIS.md](./docs/FRAMEWORK-ARCHITECTURE-ANALYSIS.md) (internal maintainer documentation).
## ๐ TypeScript Support
The Clodo Framework provides comprehensive TypeScript support with 500+ lines of type definitions for complete type safety and enhanced developer experience.
### **TypeScript Setup**
```typescript
// types/index.d.ts provides complete type coverage
import {
SchemaManager,
GenericDataService,
EnhancedRouter,
CustomerConfigurationManager
} from '@tamyla/clodo-framework';
// Full IntelliSense and type checking
const schemaManager = new SchemaManager();
const service = new GenericDataService(d1Client, 'users');
```
### **Key TypeScript Features**
- **Complete API Coverage**: Every exported function and class is fully typed
- **Advanced Generic Types**: Complex data structures with proper generic constraints
- **Validation Types**: Type-safe schema definitions and validation results
- **Cache Types**: Typed caching interfaces with TTL and statistics
- **Security Types**: Comprehensive security validation and key generation types
- **IDE Integration**: Full IntelliSense, auto-completion, and refactoring support
> **Important**: The commands below are for framework development and internal use. External developers should embed deployment logic in their services rather than calling these scripts directly.
## ๏ฟฝ๐ Working Commands
### **Enterprise Deployment (Primary)**
```bash
# Interactive domain deployment (Recommended)
node bin/deployment/enterprise-deploy.js deploy --interactive
# Direct domain deployment
node bin/deployment/enterprise-deploy.js deploy data-service.greatidude.com
# Deployment with custom validation level
node bin/deployment/enterprise-deploy.js deploy --interactive --validation comprehensive
# Dry run deployment
node bin/deployment/enterprise-deploy.js deploy --interactive --dry-run
# Skip production tests
node bin/deployment/enterprise-deploy.js deploy --interactive --no-tests
```
### **๐ Security Validation (Critical)**
```bash
# Validate configuration security before deployment
npx clodo-security validate customer production
# Generate cryptographically secure keys
npx clodo-security generate-key jwt 64
npx clodo-security generate-key api content-skimmer
# Deploy with automatic security validation
npx clodo-security deploy customer production --dry-run
# Check deployment readiness
npx clodo-security check-readiness customer production
```
### **๐ฅ Customer Configuration Management**
```bash
# Create new customer configuration from templates
npm run customer-config create-customer mycompany mycompany.com
# List all configured customers
npm run customer-config list
# Show effective configuration for customer/environment
npm run customer-config show mycompany production
# Validate customer configuration structure
npm run customer-config validate
# Get deployment command for customer
npm run customer-config deploy-command mycompany staging
```
### **Domain Management**
```bash
# List available domains
node bin/deployment/enterprise-deploy.js list
# Discover domain configuration
node bin/deployment/enterprise-deploy.js discover data-service.greatidude.com
# Validate domain setup
node bin/deployment/enterprise-deploy.js validate data-service.greatidude.com
```
### **Multi-Domain Operations**
```bash
# Deploy multiple domains
node bin/deployment/enterprise-deploy.js deploy-multi domain1.com domain2.com
# Deploy entire portfolio
node bin/deployment/enterprise-deploy.js deploy-portfolio
```
## ๐ง Environment Requirements
### **Prerequisites**
```bash
# Required
Node.js >= 18.0.0
npm >= 9.0.0
npx (comes with npm)
wrangler >= 3.0.0
# Verify installation
node --version
npm --version
npx wrangler --version
```
### **Cloudflare Setup**
1. **Cloudflare Account**: Active account with API access
2. **API Token**: Token with permissions:
- `Zone:Read` (for domain discovery)
- `Zone Resources:Edit` (for worker deployment)
- `Account:Read` (optional, for enhanced features)
- `Cloudflare D1:Edit` (optional, for database discovery)
3. **Domain Configuration**: Domains should be added to Cloudflare zones
### **Service Structure**
```
services/
โโโ data-service/ # Service directory
โ โโโ wrangler.toml # Cloudflare configuration
โ โโโ package.json # Service dependencies
โ โโโ src/
โ โโโ config/domains.js # Domain configuration
โ โโโ worker/index.js # Worker entry point
```
## ๐ Quick Start
### **1. First Time Setup**
```bash
# Clone the framework
git clone
cd clodo-framework
# Install dependencies
npm install
# Ensure wrangler is available
npx wrangler --version
```
### **2. Cloudflare Authentication**
```bash
# Login to Cloudflare (first time only)
npx wrangler login
# Or set API token directly (will be prompted automatically)
# The system will securely store your token with encryption
```
### **3. Deploy a Service**
```bash
# Interactive deployment (recommended for first time)
node bin/deployment/enterprise-deploy.js deploy --interactive
# The system will:
# 1. Discover available services
# 2. Let you select a domain
# 3. Validate Cloudflare setup
# 4. Deploy the worker
# 5. Run production tests
# 6. Generate audit reports
```
### **4. Verify Deployment**
The deployment will output the worker URL. Visit it to confirm it's working:
```
โ
Deployment successful: https://your-service.your-domain.com
```
## ๐ฃ๏ธ Automatic Route Configuration
**Clodo Framework's killer feature**: Never manually configure routes again. The framework automatically generates Cloudflare Worker routes from your domain configuration, ensuring consistency across all environments.
### **Zero-Configuration Routing**
Simply define your domains, and routes are generated automatically:
```javascript
// domain-config.json
{
"domains": {
"example.com": {
"cloudflareZoneId": "abc123...",
"environments": {
"production": {
"domain": "api.example.com",
"apiBasePath": "/api"
},
"staging": {
"domain": "staging-api.example.com",
"apiBasePath": "/api"
},
"development": {
"subdomain": "my-service-dev"
}
}
}
}
}
```
**Automatically generates:**
```toml
# Production routes (top-level)
[[routes]]
pattern = "api.example.com/api/*"
zone_id = "abc123..."
# Staging routes (nested)
[env.staging]
[[routes]]
pattern = "staging-api.example.com/api/*"
zone_id = "abc123..."
# Development uses workers.dev automatically
```
### **Multi-Tenant SaaS Made Simple**
Deploy to multiple customer domains automatically:
```javascript
{
"domains": {
"customer1.example.com": { "cloudflareZoneId": "zone1..." },
"customer2.example.com": { "cloudflareZoneId": "zone2..." },
"customer3.example.com": { "cloudflareZoneId": "zone3..." }
}
}
```
All routes generated automatically. Add a new customer? Just add their domain to config.
### **Customization & Control**
Fine-tune routing behavior through `validation-config.json`:
```json
{
"routing": {
"defaults": {
"includeComments": true,
"targetEnvironment": "all",
"orderStrategy": "most-specific-first"
},
"domains": {
"skipPatterns": ["internal.*"],
"complexTLDs": [".co.uk", ".com.au"]
}
}
}
```
### **Key Benefits**
- โ
**Zero Manual TOML Editing**: Routes generated from domain config
- โ
**Multi-Environment Support**: Production, staging, dev automatically configured
- โ
**Multi-Tenant Ready**: Scale to hundreds of customer domains
- โ
**Conflict Detection**: Validates route patterns before deployment
- โ
**Self-Documenting**: Comments explain each route's purpose
### **Learn More**
- **Complete Guide**: [docs/ROUTING_GUIDE.md](./docs/ROUTING_GUIDE.md) - All configuration options explained
- **Migration Guide**: [docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md) - Move from manual routes
- **Examples**: See routing examples for single-domain, multi-tenant, and complex scenarios
> **This is what sets Clodo apart**: Other frameworks require manual route configuration. Clodo generates everything automatically from your domain structure.
## Project Structure
```
clodo-framework/
โโโ bin/ # Executable scripts and CLI tools
โ โโโ service-management/ # Service creation and initialization
โ โโโ deployment/ # Enterprise deployment tools
โ โโโ database/ # Database management tools
โ โโโ portfolio/ # Multi-service portfolio management
โ โโโ shared/ # Shared utility modules
โ โโโ config/ # Configuration management tools
โ โโโ customer-cli.js # Customer configuration CLI
โโโ scripts/ # PowerShell scripts and utilities
โ โโโ service-management/ # Service setup scripts
โ โโโ deployment/ # Deployment scripts
โ โโโ testing/ # Testing utilities
โ โโโ utilities/ # General utilities
โโโ services/ # Generated services directory
โ โโโ my-api-service/ # Individual service directories
โ โโโ auth-service/ # Auto-organized by init-service
โ โโโ data-service/ # Each with complete Cloudflare setup
โโโ docs/ # Documentation
โ โโโ analysis/ # Development analysis and demos
โ โโโ api/ # API documentation
โ โโโ examples/ # Usage examples
โ โโโ guides/ # User guides
โโโ test/ # Test suite
โ โโโ integration/ # Integration tests
โโโ src/ # Framework source code
โ โโโ config/ # Configuration management
โ โโโ customers.js # Customer configuration manager
โ โโโ domains.js # Domain configuration system
โ โโโ features.js # Feature flag system
โโโ templates/ # Service templates
โโโ config-templates/ # Configuration templates
โโโ config/ # Framework configuration
โโโ customers/ # Customer configuration templates
โโโ template/ # Reusable customer config templates
```
## Enterprise Deployment & Orchestration
The Clodo Framework now includes comprehensive enterprise-grade deployment and orchestration capabilities, extracted from production systems and made reusable across all services.
### Orchestration Modules
```javascript
import { MultiDomainOrchestrator, CrossDomainCoordinator } from '@tamyla/clodo-framework/orchestration';
// Multi-domain deployment orchestration
const orchestrator = new MultiDomainOrchestrator({
domains: ['api', 'auth', 'data'],
environment: 'production',
parallelDeployments: 3
});
// Cross-domain coordination for complex deployments
const coordinator = new CrossDomainCoordinator({
portfolioName: 'enterprise-suite',
maxConcurrentDeployments: 5,
enableDependencyResolution: true
});
```
### Deployment Management
```javascript
import { DeploymentValidator, RollbackManager, ProductionTester, DeploymentAuditor } from '@tamyla/clodo-framework/deployment';
// Pre-deployment validation
const validator = new DeploymentValidator();
await validator.validateDeployment(deploymentConfig);
// Production testing suite
const tester = new ProductionTester();
await tester.runProductionTests(deploymentId);
// Rollback management
const rollback = new RollbackManager();
await rollback.createRollbackPoint(deploymentId);
// Comprehensive audit logging
const auditor = new DeploymentAuditor();
auditor.logDeployment(deploymentId, 'started', { domains: ['api', 'auth'] });
```
### Database Orchestration
```javascript
import { DatabaseOrchestrator } from '@tamyla/clodo-framework/database';
// Multi-environment database management
const dbOrchestrator = new DatabaseOrchestrator({
projectRoot: './',
dryRun: false
});
// Run migrations across environments
await dbOrchestrator.runMigrations('production');
await dbOrchestrator.createBackup('production');
```
### Domain Discovery
```javascript
import { DomainDiscovery } from '@tamyla/clodo-framework/config/discovery';
// Runtime domain discovery and configuration
const discovery = new DomainDiscovery({
apiToken: process.env.CLOUDFLARE_API_TOKEN
});
// Discover and cache domain configurations
await discovery.discoverDomains();
const config = await discovery.getDomainConfig('my-domain');
```
### Customer Configuration Management
```javascript
import { CustomerConfigurationManager } from '@tamyla/clodo-framework/config';
// Framework-mode customer management (uses mock values for testing)
const customerManager = new CustomerConfigurationManager();
// Create customer configuration from templates
await customerManager.createCustomer('acmecorp', 'acmecorp.com', {
skipValidation: true,
isFrameworkMode: true
});
// Show effective configuration
const config = customerManager.showConfig('acmecorp', 'production');
// Validate customer configurations
const validation = await customerManager.validateConfigs();
// Get deployment commands
const deployCmd = customerManager.getDeployCommand('acmecorp', 'staging');
```
### Deployment Utilities
```javascript
import { EnhancedSecretManager, ConfigurationCacheManager, askUser, askYesNo } from '@tamyla/clodo-framework/utils/deployment';
// Advanced secret management
const secretManager = new EnhancedSecretManager();
await secretManager.generateSecrets(['database', 'api-keys']);
// Configuration caching
const cache = new ConfigurationCacheManager();
await cache.cacheConfiguration(deploymentId, config);
// Interactive prompts for deployment scripts
const environment = await askChoice('Select environment:', ['staging', 'production']);
const confirmed = await askYesNo('Deploy to production?');
```
## Enterprise CLI Tools
The Clodo Framework now includes powerful command-line tools for enterprise deployment and portfolio management.
### Installation
```bash
npm install -g @tamyla/clodo-framework
# or
npx @tamyla/clodo-framework --help
```
### Available CLI Tools
#### `clodo-deploy` - Enterprise Deployment CLI
Advanced deployment system with multi-domain orchestration, validation, and rollback capabilities.
```bash
# Deploy a single domain
npx clodo-deploy deploy my-domain --environment production
# Deploy multiple domains with coordination
npx clodo-deploy deploy-multi api auth data --parallel
# Validate deployment readiness
npx clodo-deploy validate my-domain
# Run production tests
npx clodo-deploy test my-domain
# Rollback deployment
npx clodo-deploy rollback my-domain
```
#### `clodo-master-deploy` - Master Deployment Orchestrator
Comprehensive deployment orchestrator with enterprise features and portfolio management.
```bash
# Deploy with full orchestration
npx clodo-master-deploy orchestrate --domains api,auth,data
# Run pre-deployment validation
npx clodo-master-deploy validate --portfolio
# Monitor deployment progress
npx clodo-master-deploy monitor
```
#### `clodo-portfolio` - Portfolio Management CLI
Multi-domain portfolio operations with bulk management and analytics.
```bash
# Initialize portfolio
npx clodo-portfolio init --portfolio-name my-enterprise
# Discover all domains
npx clodo-portfolio discover
# Deploy entire portfolio
npx clodo-portfolio deploy
# Get portfolio health status
npx clodo-portfolio health
# Generate portfolio analytics
npx clodo-portfolio analytics
```
#### `clodo-db` - Database Management CLI
Enterprise database operations across multiple environments.
```bash
# Run migrations for domain
npx clodo-db migrate my-domain --environment production
# Synchronize schemas across portfolio
npx clodo-db sync --portfolio
# Create backups
npx clodo-db backup my-domain
```
#### `clodo-secrets` - Secret Scanning & Baseline Management
Detect leaked secrets in source code and manage baselines for known findings.
```bash
# Scan current directory for secrets
clodo-service secrets scan
# Scan a specific directory
clodo-service secrets scan ./src
# Validate against baseline
clodo-service secrets validate
# Show current baseline
clodo-service secrets baseline show
# Update baseline after review
clodo-service secrets baseline update
# List known secret patterns
clodo-service secrets patterns
```
#### `clodo doctor` - Preflight Health Checks
Run comprehensive environment and configuration checks before deployment.
```bash
# Run all checks
clodo-service doctor
# Skip during deploy
clodo-service deploy --skip-doctor
# Strict mode (fail on warnings)
clodo-service deploy --doctor-strict
```
#### `clodo config-schema` - Config File Validation
Validate CLI config files against Zod schemas with semantic analysis.
```bash
# Validate a config file
clodo-service config-schema validate clodo-deploy.json
# Show schema for a config type
clodo-service config-schema show create
# List all supported config types
clodo-service config-schema types
# Strict mode
clodo-service config-schema validate config.json --strict
```
## Quick Start
### Install the Framework
```bash
npm install @tamyla/clodo-framework
```
### Create a New Service
```bash
npx create-clodo-service my-new-service --type data-service
```
### Basic Usage
```javascript
import { initializeService, createFeatureGuard, FeatureFlagManager } from '@tamyla/clodo-framework';
export default {
async fetch(request, env, ctx) {
// Initialize service with domain context
const service = initializeService(env);
// Feature-guarded endpoints
if (request.url.includes('/premium')) {
return createFeatureGuard('premiumFeatures')(
handlePremiumRequest
)(request, env, ctx);
}
return handleRequest(request, env, ctx);
}
};
```
## Deployment Workflow
The Clodo Framework provides a clear **setup-first, deploy-second** workflow to avoid configuration dependency issues.
### Phase 1: Service Initialization (Setup)
Before deployment, initialize your service to generate required configuration files:
```bash
# Initialize a new service with configuration generation
npx clodo-init my-service --type api-gateway --env development
# This creates:
# - wrangler.toml (Cloudflare Workers config)
# - src/config/domains.js (Domain configuration)
# - Validates environment variables
# - Prepares for deployment
```
### Phase 2: Deployment (Deploy)
Once initialized, deploy using the enterprise deployment system:
```bash
# Deploy to production
npx clodo-deploy my-service --env production
# Multi-domain deployment
npx clodo-deploy-multi api auth data --env staging
# Portfolio deployment (all domains)
npx clodo-deploy-portfolio --env production
```
### Environment Variables Required
Set these before deployment:
```bash
export CLOUDFLARE_ACCOUNT_ID="your_account_id"
export CLOUDFLARE_ZONE_ID="your_zone_id"
export CLOUDFLARE_API_TOKEN="your_api_token"
```
### Workflow Order
1. **Init** โ Generate configurations and validate setup
2. **Deploy** โ Deploy with enterprise orchestration
3. **Monitor** โ Use built-in auditing and rollback features
This ensures configurations exist before deployment attempts, eliminating the "expecting wrangler.toml readily available" issue for first-time deployments.
## Architecture
### Core Components
1. **Domain Configuration**: JSON-based configuration with validation
2. **Feature Flags**: Runtime feature management
3. **Worker Integration**: Service initialization helpers
4. **Deployment Framework**: Automated deployment scripts
5. **Service Registry**: Cross-service communication
### Service Structure
```
services/my-service/
โโโ src/
โ โโโ config/
โ โ โโโ domains.js # Service-specific domain configs
โ โ โโโ features.js # Service feature definitions
โ โโโ worker/
โ โ โโโ index.js # Main worker handler
โ โโโ routes/
โโโ scripts/
โ โโโ deploy.ps1 # Deployment script
โ โโโ setup.ps1 # Setup script
โโโ package.json
โโโ wrangler.toml
```
## Configuration
### Domain Configuration
```javascript
// config/domains.js
import { createDomainConfigSchema } from '@tamyla/clodo-framework';
export const domains = {
'my-domain': {
...createDomainConfigSchema(),
name: 'my-domain',
displayName: 'My Domain',
accountId: 'your-cloudflare-account-id',
zoneId: 'your-zone-id',
domains: {
production: 'api.myapp.com',
staging: 'staging-api.myapp.com'
},
features: {
premiumFeatures: true,
analytics: false
}
}
};
```
### Feature Definitions
```javascript
// config/features.js
export const FEATURES = {
PREMIUM_FEATURES: 'premiumFeatures',
ANALYTICS: 'analytics',
FILE_STORAGE: 'fileStorage'
};
```
## Deployment
### Automated Deployment
```powershell
# Deploy to staging
.\scripts\deploy.ps1 -DomainName my-domain -Environment staging
# Deploy to production
.\scripts\deploy.ps1 -DomainName my-domain -Environment production
```
### Interactive Setup
```powershell
# Run interactive setup
.\scripts\setup.ps1
```
## ๏ฟฝ Troubleshooting
### **Common Issues & Solutions**
#### **"Service directory not found for domain"**
```bash
# Problem: No service exists for the domain
# Solution: Check available services
node bin/deployment/enterprise-deploy.js list
# Or create a new service (if service creation tools are available)
# Ensure the service has proper domain configuration in src/config/domains.js
```
#### **"API token required for domain verification"**
```bash
# Problem: No Cloudflare authentication
# Solution: The system will automatically prompt for API token
# Or manually set up wrangler auth:
npx wrangler login
```
#### **"D1 database discovery requires additional permissions"**
```bash
# This is informational only - deployment continues successfully
# To enable D1 discovery, update your API token with:
# - Account:Read permissions
# - Cloudflare D1:Edit permissions
```
#### **Integration tests & DNS: how CI avoids ENOTFOUND**
- Integration tests mock network calls when `TEST_URL` is not provided to avoid DNS resolution failures (ENOTFOUND) in CI and developer environments.
- To run integration tests against an actual deployment set `TEST_URL` to your deployment URL, for example:
```bash
TEST_URL='https://your-service.workers.dev' npm run test:integration
```
- Database integration tests are disabled by default for CI. Enable them by setting `RUN_DB_TESTS=true` (or `RUN_DB_TESTS=1`) when you have a configured database and credentials available:
```bash
TEST_URL='https://your-service.workers.dev' RUN_DB_TESTS=true npm run test:integration
```
This prevents flaky CI failures while still allowing full end-to-end verification when desired.
#### **"npx command not found" on Windows**
```bash
# Problem: Command configuration for cross-platform compatibility
# Solution: The system uses validation-config.json for command mapping
# Ensure npx is in your PATH or update the config file
```
### **Debug Mode**
```bash
# Run with verbose logging
node bin/deployment/enterprise-deploy.js deploy --interactive --validation comprehensive
# Check specific domain configuration
node bin/deployment/enterprise-deploy.js discover your-domain.com
```
## ๏ฟฝ๐ Development Insights & Lessons Learned
### **Key Architecture Decisions**
#### **1. Interactive vs Hardcoded Parameters** โ
- **Problem**: Original system required domain as command argument
- **Solution**: Added `--interactive` flag for domain selection from discovered services
- **Impact**: Much better UX, reduces deployment errors
#### **2. Cross-Platform Command Compatibility** โ
- **Problem**: Hardcoded commands failed on different platforms (Windows vs Linux)
- **Solution**: Configurable command system via `validation-config.json`
- **Impact**: Seamless cross-platform operation
#### **3. API Token Management** โ
- **Problem**: OAuth authentication insufficient for API operations
- **Solution**: Secure API token storage with AES-256-CBC encryption
- **Impact**: Reliable authentication with automated prompting
#### **4. Service Discovery Intelligence** โ
- **Problem**: Expected exact directory names matching domains
- **Solution**: Smart discovery by checking `domains.js` configuration files
- **Impact**: Flexible service organization and deployment
#### **5. Real vs Mock Deployments** โ
- **Problem**: Mock deployments provided false success with undefined URLs
- **Solution**: Actual wrangler execution with URL extraction
- **Impact**: Real deployment validation and working services
### **Production-Ready Improvements Implemented**
#### **Graceful Error Handling**
```javascript
// D1 database discovery with permission graceful degradation
if (error.message.includes('401') || error.message.includes('Unauthorized')) {
console.log(`โน๏ธ D1 database discovery requires additional API token permissions`);
console.log(`๐ก To enable D1 discovery, ensure your API token has 'Account:Read' or 'Cloudflare D1:Edit' permissions`);
} else {
console.log(`โ ๏ธ D1 database discovery failed: ${error.message}`);
}
```
#### **Smart Service Directory Discovery**
```javascript
// Find service directory by domain configuration rather than exact name match
for (const serviceDir of serviceDirs) {
const domainsPath = join(servicesDir, serviceDir, 'src', 'config', 'domains.js');
if (existsSync(domainsPath)) {
const domainsContent = await fs.readFile(domainsPath, 'utf8');
if (domainsContent.includes(domain)) {
servicePath = join(servicesDir, serviceDir);
break;
}
}
}
```
#### **Production Test Resilience**
```javascript
// Wait for deployment propagation before running tests
if (options.tests !== false && deploymentResult.url) {
this.logOutput('โณ Waiting for deployment to propagate...', 'info');
await new Promise(resolve => setTimeout(resolve, 10000)); // 10 second delay
const testResult = await this.modules.productionTester.runProductionTests(deploymentUrl, options);
}
```
## ๐ฎ Future Improvements
### **Phase 1: Service Autonomy**
**Goal**: Each service becomes completely autonomous
#### **Service-Level Integration**
```javascript
// Each service gets its own deployment module
service-repo/
โโโ deployment/
โ โโโ deploy.js # Service-specific deployment
โ โโโ config.js # Service deployment config
โ โโโ validators.js # Service validation logic
โโโ src/config/domains.js # Multi-domain configuration
โโโ package.json # Includes clodo-framework as dependency
```
#### **Reusable Component Library**
```javascript
import {
DomainDiscovery,
CloudflareManager,
DeploymentValidator,
ProductionTester
} from '@tamyla/clodo-framework';
// Each service imports only what it needs
const discovery = new DomainDiscovery({ domain: 'my-service.domain.com' });
await discovery.validateCloudflareSetup();
```
### **Phase 2: Advanced Orchestration**
- **Dependency Resolution**: Services declare dependencies on other services
- **Blue-Green Deployments**: Zero-downtime deployment patterns
- **Canary Releases**: Gradual rollout with automatic monitoring
- **Multi-Region Deployment**: Global service distribution
### **Phase 3: Enterprise Features**
- **Service Mesh Integration**: Inter-service communication patterns
- **Centralized Monitoring**: Unified observability across all services
- **Policy Management**: Governance and compliance automation
- **Cost Optimization**: Resource usage monitoring and optimization
### **Current Framework Purpose**
This framework currently serves as:
1. **Development Environment**: Understanding deployment workflows and requirements
2. **Component Testing**: Validating integration patterns and error handling
3. **Template Generation**: Creating reusable patterns for service codebases
4. **Integration Standards**: Defining how autonomous services should operate
**Next Evolution**: Extract successful patterns into lightweight libraries that individual services can import and use independently.
## ๐ **Recent Major Enhancement: Customer Configuration Management**
The Clodo Framework has successfully incorporated **enterprise-grade customer configuration management** capabilities, transforming it from a single-service framework into a **multi-customer, multi-environment enterprise platform**.
### โ
**Successfully Incorporated Features**
#### **๐ฅ Customer Isolation & Management**
- **Multi-customer support** with isolated configuration namespaces
- **Template-based customer onboarding** from reusable configuration templates
- **Customer registry** with automatic domain registration
- **Framework-safe design** using mock values for development/testing
#### **๐๏ธ Template-Driven Architecture**
- **Environment-specific templates** (development.env.template, staging.env.template, production.env.template)
- **Variable substitution** with customer-specific placeholders (`{{CUSTOMER_NAME}}`, `{{DOMAIN}}`, etc.)
- **Automated configuration generation** from templates to production-ready configs
- **Template inheritance** supporting cross-customer and cross-environment patterns
#### **๐ Framework Integration**
- **Domain system integration** - customers automatically registered as domains
- **Feature flag integration** - customer-specific features managed through existing system
- **Validation framework integration** - customer configs validated using existing patterns
- **CLI tool integration** - customer management accessible via `npm run customer-config`
#### **๐ ๏ธ Developer Experience**
- **CLI tools**: `create-customer`, `show`, `validate`, `list`, `deploy-command`
- **Programmatic API**: Full TypeScript/JavaScript API for customer management
- **Framework mode**: Mock-friendly for development without real infrastructure
- **Service migration path**: Generated configs can be copied to service repositories
### ๐ **Impact & Benefits**
#### **For Framework Users**
- **Zero breaking changes** - all existing functionality preserved
- **Enhanced capabilities** - framework now supports enterprise customer scenarios
- **Better testing** - customer scenarios can be tested in framework environment
- **Migration ready** - smooth path from framework testing to service implementation
#### **For Service Developers**
- **Customer-ready services** - framework provides patterns for multi-customer support
- **Automated onboarding** - customer setup becomes template-driven process
- **Consistent patterns** - same customer management approach across all services
- **Reduced duplication** - shared customer configuration logic
#### **For Enterprise Teams**
- **Multi-customer support** - single framework handles multiple customer deployments
- **Environment isolation** - separate configs for dev/staging/production per customer
- **Scalable architecture** - customer management scales with business growth
- **Governance & compliance** - centralized customer configuration management
### ๐ **Technical Implementation Highlights**
#### **Clean Architecture**
- **Separation of concerns**: Framework provides tools, services manage customer data
- **Mock-friendly**: Framework mode uses placeholders, service mode uses real values
- **Composable**: Customer management integrates with existing domain/feature systems
- **Testable**: Full test coverage without requiring real Cloudflare infrastructure
#### **Developer Workflow**
```bash
# Framework development/testing
npm run customer-config create-customer testcorp testcorp.com
npm run customer-config show testcorp production
# Service implementation (copy generated configs)
cp config/customers/testcorp/* my-service/src/config/customers/testcorp/
# Then customize for production infrastructure
```
#### **API Design**
```javascript
// Framework mode (mock values)
const customerManager = new CustomerConfigurationManager();
await customerManager.createCustomer('acmecorp', 'acmecorp.com', {
skipValidation: true,
isFrameworkMode: true
});
// Service mode (real infrastructure)
const customerManager = new CustomerConfigurationManager();
await customerManager.createCustomer('acmecorp', 'acmecorp.com', {
accountId: 'real-cloudflare-account-id',
zoneId: 'real-cloudflare-zone-id'
});
```
### ๐ฏ **Mission Accomplished**
The Clodo Framework has successfully evolved from a **single-service deployment framework** into a **comprehensive enterprise platform** that supports:
- โ
**Multi-service orchestration** (existing)
- โ
**Multi-environment deployment** (existing)
- โ
**Multi-customer configuration** (newly added)
- โ
**Enterprise-grade security** (existing)
- โ
**Developer experience** (enhanced)
This enhancement maintains backward compatibility while significantly expanding the framework's capabilities for enterprise scenarios. The customer configuration management system is now a core, production-ready feature that enables the framework to support complex, multi-customer enterprise deployments.
**The Clodo Framework is now ready to "snap together" not just services, but entire customer ecosystems! ๐งฑโก๏ธ๐ข**
## Scripts and Tools
The Clodo Framework includes a comprehensive set of scripts and command-line tools, organized by functionality.
### Directory Structure
```
scripts/
โโโ service-management/ # Service creation and setup
โโโ deployment/ # Deployment scripts
โโโ testing/ # Testing utilities
โโโ utilities/ # General utilities
bin/
โโโ service-management/ # Service creation tools
โโโ deployment/ # Enterprise deployment CLI
โโโ database/ # Database management
โโโ portfolio/ # Multi-service management
โโโ shared/ # Shared utility modules
```
### Service Management
**Create services with auto-generated configurations:**
```bash
# Initialize service with multi-domain support
node bin/service-management/init-service.js my-service \
--type api-gateway \
--domains "api.example.com:account1:zone1,staging.example.com:account2:zone2"
# Create service from template
node bin/service-management/create-service.js my-service --type data-service
```
**Interactive setup:**
```powershell
.\scripts\service-management\setup-interactive.ps1 -ServiceName my-service
```
### Deployment
**Enterprise deployment:**
```bash
node bin/deployment/enterprise-deploy.js deploy --service my-service --environment production
```
**Domain-specific deployment:**
```powershell
.\scripts\deployment\deploy-domain.ps1 -DomainName api.example.com -Environment production
```
### Testing
**Run tests:**
```powershell
.\scripts\testing\test.ps1
.\scripts\testing\test-first.ps1 -ServiceName my-service
```
### Database Management
**Database operations:**
```bash
node bin/database/enterprise-db-manager.js migrate --service my-service
node bin/database/enterprise-db-manager.js backup --database my-db
```
### Portfolio Management
**Multi-service orchestration:**
```bash
node bin/portfolio/portfolio-manager.js create --name my-portfolio
node bin/portfolio/portfolio-manager.js deploy --portfolio my-portfolio --environment production
```
## ๐ Documentation & Learning Resources
The CLODO Framework provides comprehensive documentation designed for different learning styles and experience levels. Whether you prefer hands-on tutorials, detailed reference materials, or quick-start templates, we've got you covered.
### ๐ **Quick Start Resources**
Resource
Best For
Time Required
Description
๐ Getting Started Guide
New users, hands-on learners
10-15 minutes
Interactive tutorial with step-by-step examples and real code you can run
๐๏ธ Quick Start Templates
Immediate project needs
5 minutes
Ready-to-use project templates for common patterns (REST API, Auth, etc.)
๐ ๏ธ CLI Tutorial
DevOps, deployment workflows
15-20 minutes
Interactive guide to all CLI commands with real examples and outputs
### ๐ **Comprehensive Documentation**
Documentation
Purpose
Target Audience
๐ API Reference
Complete technical documentation of all classes, methods, and interfaces
Developers building with the framework
๐ป Code Examples Gallery
Real-world code snippets and patterns for common use cases
Developers seeking implementation patterns
๐ Integration Guide
Adding CLODO Framework to existing projects incrementally
Teams with existing codebases
๐๏ธ Architecture Overview
Framework design, principles, and component relationships
Architects and senior developers
### ๐ฏ **Choose Your Learning Path**
**๐จโ๐ป I'm new to CLODO Framework**
1. Start with [Getting Started Guide](./docs/getting-started.md) (10 min interactive tutorial)
2. Try a [Quick Start Template](./docs/quickstart-templates/) for your use case
3. Explore the [Code Examples Gallery](./docs/examples-gallery.md) for patterns
**๐โโ๏ธ I need to build something now**
1. Browse [Quick Start Templates](./docs/quickstart-templates/) for your project type
2. Copy the relevant template and customize
3. Reference [API Documentation](./docs/api-reference.md) as needed
**๐ง I'm focused on deployment & operations**
1. Follow the [CLI Tutorial](./docs/cli-tutorial.md) for hands-on command experience
2. Review deployment patterns in [Code Examples Gallery](./docs/examples-gallery.md#deployment-patterns)
3. Check [Integration Guide](./docs/INTEGRATION_GUIDE.md) for production considerations
**๐ข I have an existing project**
1. Read the [Integration Guide](./docs/INTEGRATION_GUIDE.md) for incremental adoption strategies
2. Start with utilities from [Code Examples Gallery](./docs/examples-gallery.md#utilities--helpers)
3. Gradually adopt more features following the integration phases
**๐๏ธ I want to understand the architecture**
1. Review [Architecture Overview](./docs/FRAMEWORK-ARCHITECTURE-OVERVIEW.md) for design philosophy
2. Study [API Reference](./docs/api-reference.md) for technical depth
3. Examine [Code Examples Gallery](./docs/examples-gallery.md) for implementation patterns
### ๐ก **Documentation Features**
- **๐ฎ Interactive Examples**: All tutorials include runnable code with expected outputs
- **๐ Copy-Paste Ready**: Code examples are production-ready and fully functional
- **๐ Cross-Referenced**: Documents link to each other for seamless navigation
- **๐ฑ Progressive Complexity**: Start simple, drill down as needed
- **๐ ๏ธ Real-World Focus**: Examples address actual development scenarios
- **โก Quick Reference**: Find what you need fast with clear categorization
### ๐ **Need Help?**
- **๐ Found an issue?** [Report a bug](https://github.com/tamyla/clodo-framework/issues/new?template=bug-report.md)
- **๐ก Have a suggestion?** [Request a feature](https://github.com/tamyla/clodo-framework/issues/new?template=feature-request.md)
- **โ Need specific example?** [Request documentation](https://github.com/tamyla/clodo-framework/issues/new?template=example-request.md)
- **๐ฌ Want to discuss?** [Start a discussion](https://github.com/tamyla/clodo-framework/discussions)
> **๐ฏ Pro Tip**: Bookmark the [API Reference](./docs/api-reference.md) and [Code Examples Gallery](./docs/examples-gallery.md) - they're designed as quick-reference resources you'll return to frequently during development.
## Development
### Building the Framework
```bash
npm run build
```
### Running Tests
```bash
npm test
```
### Linting
```bash
npm run lint
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
---
## ๐ Professional Framework Features
The Clodo Framework represents the evolution from a promising concept to a fully validated, enterprise-grade tool for Cloudflare development. Here's what makes it professional:
### โ
**Validated Promise Delivery**
- **10/10 Validation Phases**: Comprehensive testing ensures production readiness
- **28+ Files Generated**: Complete service ecosystems created instantly
- **98.9% Test Coverage**: Enterprise-grade quality assurance
- **Production Deployment**: Services ready for immediate Cloudflare deployment
### ๐๏ธ **Enterprise Architecture**
- **Three-Tier Service Creation**: Input โ Confirmation โ Generation pipeline
- **Modular Handler System**: Separated concerns for maintainability
- **Configuration Management**: Environment-specific settings and overrides
- **Security-First Design**: Built-in security validation and compliance
### ๐ **Developer Productivity**
- **Interactive Wizards**: Guided service creation with smart defaults
- **One-Click Deployment**: Automated deployment scripts and health checks
- **Service Enhancement APIs**: Programmatic customization capabilities
- **Comprehensive Documentation**: Auto-generated API docs and guides
### ๐ง **Professional Tooling**
- **CI/CD Integration**: Pipeline-ready with automated validation
- **Multi-Environment Support**: Dev, staging, and production configurations
- **Error Recovery**: Comprehensive error handling and user guidance
- **Performance Optimization**: Efficient code generation and deployment
### ๐ **Scalability & Reliability**
- **Service Orchestration**: Coordinated multi-service deployments
- **Dependency Management**: Clean package resolution and updates
- **Cross-Platform Compatibility**: Windows, macOS, Linux support
- **Version Management**: Service versioning and rollback capabilities
### ๐ฎ **Future Possibilities**
#### Advanced Service Templates
- **API Gateway Services**: Advanced routing and rate limiting
- **Edge Computing**: Global distribution and edge function templates
- **Microservices Architecture**: Service mesh and orchestration patterns
- **Real-time Services**: WebSocket and streaming service templates
#### Enterprise Integration
- **Multi-Cloud Deployment**: AWS, Azure, GCP integration options
- **Advanced Security**: OAuth, SAML, and enterprise authentication
- **Monitoring & Analytics**: Built-in metrics and performance monitoring
- **Compliance Automation**: SOC2, HIPAA, GDPR compliance templates
#### AI-Powered Features
- **Intelligent Code Generation**: AI-assisted service customization
- **Performance Optimization**: Automated bottleneck detection
- **Security Analysis**: AI-powered vulnerability assessment
- **Smart Defaults**: Context-aware configuration recommendations
#### Developer Experience
- **VS Code Extension**: Integrated development environment support
- **Service Marketplace**: Pre-built service templates and components
- **Team Collaboration**: Shared service libraries and templates
- **Training Platform**: Interactive learning and certification programs
### ๐ฏ **Professional Certification Framework**
#### Quality Assurance Pipeline
- **Automated Code Review**: Static analysis and code quality checks
- **Security Penetration Testing**: Automated vulnerability assessment
- **Performance Load Testing**: Scalability and stress testing
- **Compliance Validation**: Industry standard compliance verification
#### Enterprise Support Services
- **24/7 Technical Support**: Enterprise-grade support agreements
- **Professional Services**: Consulting and custom development
- **Training Programs**: Certification and skill development
- **Migration Services**: Legacy system modernization assistance
---
## ๐ Framework Evolution Narrative
For the complete story of how the Clodo Framework evolved from promise to production-ready reality, see our comprehensive [Framework Evolution Narrative](docs/FRAMEWORK_EVOLUTION_NARRATIVE.md), which documents:
- The initial promise and reality check
- Implementation of the three-tier architecture
- Comprehensive validation and testing
- Issue resolution and optimization
- Professional framework capabilities
- Future roadmap and possibilities
This narrative serves as both a technical reference and a case study in professional framework development.
## License
MIT License - see LICENSE file for details
## Support
For questions and support, please open an issue on GitHub or contact the maintainers.