-
Notifications
You must be signed in to change notification settings - Fork 0
DATA_FLOW.md
This document describes how information, blockchain transactions, application requests, and impact data move through the CeloHT ecosystem.
The architecture distinguishes between on-chain data, off-chain application data, and public impact information.
┌───────────────┐
│ USER │
└───────┬───────┘
│
▼
┌───────────────────┐
│ CeloHT Interface │
└─────────┬─────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
Wallet API/Data Education
│ │ │
▼ ▼ ▼
Celo Application Content
Network Data
│ │
└───────────────┼───────────────┘
▼
Impact & Reporting
CeloHT data can be divided into three major categories.
Data permanently recorded on the Celo blockchain.
Examples:
- Wallet addresses
- Transaction hashes
- Transaction amounts
- Contract events
- Contract state
- Blockchain timestamps
Data required for application operation.
Examples:
- User preferences
- Educational progress
- Agent information
- Program administration
- Application settings
- Public content
Data used to measure ecosystem outcomes.
Examples:
- People trained
- Training completion
- Agent activity
- Transactions
- Remittance activity
- Communities reached
- Trees planted
- Environmental activities
User
│
▼
CeloHT Interface
│
├───────────────┐
│ │
▼ ▼
Application Wallet
Data Interaction
│ │
│ ▼
│ Celo Blockchain
│ │
└───────┬───────┘
▼
User Feedback
The system should collect only information necessary for the relevant service.
User
│
▼
Transaction Request
│
▼
CeloHT Application
│
▼
Wallet
│
▼
User Signs Transaction
│
▼
Celo Network
│
▼
Transaction Confirmation
│
▼
Transaction Hash
│
▼
CeloHT Interface
The transaction hash can be used as an auditable reference.
CeloHT applications should interact with wallets through supported wallet interfaces.
Application
│
▼
Wallet Connection
│
▼
Wallet Address
│
▼
Transaction Request
│
▼
User Approval
│
▼
Signed Transaction
│
▼
Blockchain
Private keys and seed phrases must remain under the user's control.
Community User
│
▼
Local Agent
│
▼
Agent Interface
│
├──────────────┐
▼ ▼
Application Wallet
Data │
│ ▼
│ Celo
│ │
└─────┬──────┘
▼
Transaction
│
▼
Confirmation
The agent system can combine physical community services with digital blockchain infrastructure.
Participant
│
▼
Training Program
│
▼
Educational Content
│
▼
Learning Activity
│
▼
Completion Record
│
▼
Impact Metrics
Education records should be stored off-chain unless a specific blockchain use case requires otherwise.
Community
│
▼
Reforestation Program
│
▼
Planting Activity
│
▼
Field Verification
│
▼
Impact Record
│
▼
Public Impact Reporting
Potential records include:
- Planting activity
- Location at an appropriate level of precision
- Number of seedlings
- Participating community
- Program date
- Verification status
Sensitive location information should not be unnecessarily exposed.
Blockchain and application systems may need synchronization.
Celo Blockchain
│
▼
Blockchain Events
│
▼
Indexing / API Layer
│
▼
Application Database
│
▼
Frontend
The application should treat blockchain data as the authoritative source for blockchain transactions.
Smart-contract events can trigger application-side processing.
Smart Contract
│
▼
Blockchain Event
│
▼
Event Listener / Indexer
│
▼
Application Service
│
▼
Database / Cache
│
▼
Frontend / Dashboard
Examples:
- Payment event
- Treasury event
- Agent event
- Program funding event
CeloHT should distinguish between:
Information directly verifiable on-chain.
Information generated or stored by application systems.
Information submitted by participants or field teams.
Information that has undergone an appropriate verification process.
This distinction is important for transparency.
Privacy-sensitive information should remain off-chain.
Avoid storing unnecessary:
- Personal identification data
- Private documents
- Passwords
- Private keys
- Seed phrases
- Sensitive personal information
on public blockchain networks.
Application data should be protected through:
- Authentication
- Authorization
- Encryption where appropriate
- Secure database configuration
- Secret management
- Access logging
- Backup procedures
- Dependency security
- Regular security reviews
Data retention should depend on the purpose of the information.
Data Created
│
▼
Purpose Identified
│
▼
Retention Requirement
│
├── Required → Retain Securely
│
└── No Longer Required → Delete / Anonymize
Blockchain data cannot generally be deleted after confirmation. Therefore, sensitive data should not be placed on-chain unnecessarily.
CeloHT can expose appropriate public metrics without exposing sensitive personal information.
Examples:
- Number of people trained
- Number of completed trainings
- Number of transactions
- Agent activity
- Communities reached
- Reforestation activity
- Public treasury transactions where appropriate
Public metrics should be accompanied by clear definitions.
On-Chain Data
│
├──────────────┐
│ │
▼ ▼
Application Data Impact Data
│ │
└───────┬──────┘
▼
Analytics Layer
│
▼
Reports / Dashboards
│
▼
Community / Partners
Analytics should distinguish measured facts from estimates.
Data pipelines should account for:
- Failed transactions
- Delayed confirmations
- Duplicate events
- API failures
- Database failures
- Incorrect user input
- Network interruptions
- Inconsistent off-chain records
Blockchain transaction status should be confirmed independently rather than assuming that a submitted transaction succeeded.
Important financial and operational events should be traceable.
Action
│
▼
Timestamp
│
▼
Actor / System
│
▼
Transaction or Record
│
▼
Verification
│
▼
Audit Trail
For blockchain transactions, the transaction hash should be preserved as an audit reference.
- Minimize collected data.
- Keep private information off-chain.
- Never collect private keys.
- Validate external inputs.
- Authenticate privileged operations.
- Log important system events.
- Separate public and private datasets.
- Verify blockchain transactions independently.
- Protect application credentials.
- Document data ownership and responsibility.
The complete conceptual flow is:
USER
│
▼
CELOHT PLATFORM
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
EDUCATION AGENTS SERVICES
│ │ │
└─────────────┼─────────────┘
│
▼
WALLET
│
▼
CELO BLOCKCHAIN
│
┌─────────┼─────────┐
▼ ▼ ▼
CELO cUSD Contracts
│ │ │
└─────────┼─────────┘
▼
DATA / EVENTS
│
▼
IMPACT METRICS
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Community Partners Reporting
CeloHT data architecture follows these principles:
- Blockchain data should remain verifiable.
- Sensitive data should remain off-chain.
- Data collection should be purpose-driven.
- Public reporting should protect privacy.
- Impact metrics should be clearly defined.
- Critical financial data should be auditable.
- Application databases should not replace blockchain truth.
- Analytics should distinguish facts from estimates.
Document: Data Flow Architecture Version: 1.0 Project: CeloHT Blockchain: Celo Primary Data Domains: Blockchain • Application • Education • Agent Network • Impact
© 2026 CeloHT - Open Source. Global Impact. Licensed under Apache.