-
Notifications
You must be signed in to change notification settings - Fork 0
DEPLOYMENT_ARCHITECTURE.md
Version: 1.0 Project: CeloHT Deployment Model: Cloud + Blockchain + GitHub CI/CD Blockchain: Celo
This document describes the production deployment architecture for CeloHT applications and services.
The deployment model separates source control, continuous integration, application hosting, databases, APIs, blockchain infrastructure, and monitoring.
DEVELOPERS
│
▼
┌─────────────┐
│ GITHUB │
│ Repositories│
└──────┬──────┘
│
▼
┌─────────────┐
│ GitHub │
│ Actions CI │
└──────┬──────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Frontend Backend Contracts
│ │ │
▼ ▼ ▼
Hosting API/Server Celo Network
│ │ │
└─────────────┼─────────────┘
▼
Data Services
│
▼
Monitoring
GitHub is the primary source-control environment.
Repositories contain:
- Application source code
- Smart contracts
- Tests
- Documentation
- Configuration templates
- CI/CD workflows
Production deployments should be traceable to a specific Git commit.
Every production-capable repository should use automated validation.
Git Push / Pull Request
│
▼
GitHub Actions
│
├── Install
├── Lint
├── Type Check
├── Test
├── Build
├── Security
└── Artifact
│
▼
Deployment
Only validated builds should proceed toward production.
A CeloHT frontend may be deployed on a modern web-hosting platform.
Conceptually:
GitHub
│
▼
CI/CD
│
▼
Frontend Build
│
▼
Hosting Platform
│
▼
CDN
│
▼
User Browser
The frontend should use environment-specific configuration.
Where backend services are required:
Frontend
│
▼
API Endpoint
│
▼
Backend Service
│
┌─┼─────────────┐
▼ ▼ ▼
DB API Blockchain
│ │
└──────┬──────┘
▼
Response
Backend services should be stateless where practical to simplify scaling.
Off-chain application data should use a managed database where appropriate.
Conceptually:
Application
│
▼
Database API / ORM
│
▼
PostgreSQL
│
├── Users / Profiles
├── Program Data
├── Agent Data
├── Content Metadata
└── Analytics Data
Database credentials must never be exposed to the browser.
Blockchain components are deployed independently of the web application.
Developer
│
▼
Contract Repository
│
▼
Tests
│
▼
Deployment Script
│
▼
Celo Network
│
▼
Contract Address
│
▼
Verification
Every production contract should have a documented deployment record.
The frontend communicates with wallet infrastructure.
User Browser
│
▼
CeloHT dApp
│
▼
Wallet
│
▼
User Approval
│
▼
Celo Network
The application should never receive or store a user's private key.
CeloHT deployments should distinguish:
ENVIRONMENTS
Development ───► Testing ───► Staging ───► Production
Used for local implementation.
Used for automated and integration testing.
Used to validate production-like deployments.
Used by real users.
Developer
│
▼
Pull Request
│
▼
Code Review
│
▼
CI Checks
│
▼
Merge
│
▼
Production Build
│
▼
Deployment
│
▼
Health Checks
│
▼
Production
Every production deployment should be associated with:
- Git commit
- Build identifier
- Deployment timestamp
- Environment
- Version
- Deployment status
For smart contracts:
- Contract address
- Network
- Deployment transaction
- Contract version
- Verification status
Sensitive values must be managed outside source control.
Examples:
DATABASE_URL
PRIVATE_DEPLOYER_KEY
RPC_URL
API_SECRET
AUTH_SECRET
Production secrets should be stored in the deployment platform's secure environment configuration or another dedicated secrets manager.
Never place secrets inside:
- Git commits
- README files
- Public documentation
- Screenshots
- Client-side JavaScript
The deployment pipeline should protect against:
- Secret exposure
- Unauthorized deployments
- Dependency compromise
- Malicious pull requests
- Supply-chain attacks
- Unreviewed production changes
Recommended controls include:
- Protected branches
- Required reviews
- Environment protection
- Limited deployment permissions
- Secret isolation
- Dependency scanning
- Code scanning
CeloHT infrastructure should maintain clear boundaries:
┌────────────────────┐
│ Source Control │
└─────────┬──────────┘
│
┌─────────▼──────────┐
│ CI/CD │
└─────────┬──────────┘
│
┌───────────────┼────────────────┐
▼ ▼ ▼
Frontend Backend Blockchain
│ │ │
▼ ▼ ▼
CDN API Celo
│ │
└───────┬───────┘
▼
Database
This separation reduces operational coupling.
Production systems should monitor:
- Availability
- Response times
- Errors
- Traffic
- Request failures
- Latency
- Error rates
- Availability
- Connection errors
- Performance
- Transaction failures
- Confirmation delays
- RPC availability
- Contract errors
Services should expose appropriate health information.
Conceptually:
Health Check
│
├── Application
├── API
├── Database
└── Blockchain Connectivity
A failed dependency should be distinguishable from a failed application.
If a deployment causes a critical failure:
Production
│
▼
Incident Detected
│
▼
Deployment Identified
│
▼
Rollback / Fix
│
▼
Validation
│
▼
Production Restored
Rollback procedures should be tested before they are needed.
Smart-contract deployments require additional safeguards.
Before mainnet deployment:
- Tests passing
- Deployment parameters reviewed
- Network confirmed
- Contract permissions reviewed
- Security review completed where appropriate
- Deployment wallet secured
- Transaction reviewed
- Contract verified
- Address documented
Production databases should have an appropriate backup strategy.
Backups should be:
- Automated
- Protected
- Tested
- Retained according to operational requirements
A backup that has never been restored should not be assumed to be reliable.
The recovery model should cover:
Application Failure
│
▼
Redeploy Application
│
▼
Database Failure
│
▼
Restore Backup
│
▼
Blockchain Integration Failure
│
▼
Switch / Restore RPC Infrastructure
Blockchain state itself is externally maintained by the Celo network, but application-side indexing and databases still require recovery procedures.
Production web applications should use:
- HTTPS
- Secure cookies where applicable
- Proper domain configuration
- Security headers
- DNS protection
The public CeloHT domain should point to the production deployment.
Static assets should be delivered through a CDN where practical.
User
│
▼
CDN
│
├── HTML
├── JavaScript
├── CSS
├── Images
└── Static Assets
Dynamic API requests should be routed separately.
Every production deployment should answer:
- What version is running?
- Which Git commit produced it?
- When was it deployed?
- Who authorized it?
- Did health checks pass?
- Are errors increasing?
- Are blockchain transactions functioning?
- Build succeeds
- Tests pass
- Lint passes
- Type checks pass
- Dependencies audited
- Secrets protected
- Authentication configured
- Authorization reviewed
- Security scanning enabled
- Domain configured
- HTTPS enabled
- Database configured
- Monitoring configured
- Backups configured
- Correct Celo network
- Contract addresses documented
- Contracts verified
- Wallet integration tested
- Transaction monitoring configured
- Rollback procedure documented
- Incident procedure documented
- Deployment traceability enabled
- Health checks verified
┌──────────────┐
│ GitHub │
└──────┬───────┘
│
▼
┌──────────────┐
│ GitHub CI/CD │
└──────┬───────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
Frontend Backend Contracts
│ │ │
▼ ▼ ▼
Hosting API/Server Celo
│ │ │
└────────────┼────────────┘
▼
Database
│
▼
Monitoring
│
▼
Users
CeloHT deployment should prioritize:
- Reproducibility
- Security
- Traceability
- Automation
- Minimal downtime
- Fast rollback
- Infrastructure isolation
- Blockchain transparency
- Data protection
- Operational simplicity
Document: Deployment Architecture Version: 1.0 Project: CeloHT Deployment Model: CI/CD + Cloud Infrastructure + Celo Blockchain
© 2026 CeloHT - Open Source. Global Impact. Licensed under Apache.