-
Notifications
You must be signed in to change notification settings - Fork 0
TECH_STACK.md
Document Type: Technical Architecture Reference Project: CeloHT Status: Active / Evolving Last Updated: August 2026 Authors: Johnny Dubic & CeloHT Community
CeloHT uses a modern Web3-oriented technology architecture designed to support decentralized applications, financial education, community programs, environmental initiatives, and open-source development.
The technology stack is intentionally modular so individual components can evolve without requiring unnecessary changes throughout the ecosystem.
CeloHT technology decisions should prioritize:
- Security
- Reliability
- Maintainability
- Performance
- Interoperability
- Open-source development
- Developer experience
- User accessibility
- Long-term sustainability
Technology should serve the project mission rather than become an objective by itself.
The CeloHT stack can be represented as:
Users
│
▼
Web / Mobile Interfaces
│
▼
React / Next.js
│
▼
TypeScript Application Layer
│
├──────────────┐
▼ ▼
Backend/API Wallet Integration
│ │
▼ ▼
Database Celo Network
│ │
│ ┌────┴────┐
│ ▼ ▼
│ CELO cUSD
│
▼
Analytics / Operations
CeloHT web applications may use:
- React
- Next.js
- TypeScript
- Tailwind CSS
- shadcn/ui
- Lucide Icons
The frontend should prioritize accessibility, performance, responsiveness, and security.
Next.js may serve as the primary framework for CeloHT web applications.
Potential capabilities include:
- App Router
- Server Components
- Client Components
- Server-side rendering
- Static generation
- API endpoints
- Metadata and SEO
- Route handling
The specific Next.js version should be pinned in each repository's package configuration.
React provides the component-based user-interface architecture.
CeloHT interfaces should favor:
- Reusable components
- Clear state management
- Predictable data flow
- Accessible interactions
- Minimal unnecessary rendering
TypeScript should be preferred for application code where supported.
Benefits include:
- Static type checking
- Better developer tooling
- Safer refactoring
- Explicit interfaces
- Reduced runtime errors
CeloHT interfaces may use Tailwind CSS for utility-based styling.
Design systems should maintain consistency across:
- Typography
- Spacing
- Components
- Responsive layouts
- Accessibility
- Brand elements
shadcn/ui may be used for reusable interface components.
Potential components include:
- Buttons
- Dialogs
- Forms
- Cards
- Tables
- Navigation
- Dropdowns
- Tabs
Components should remain accessible and adaptable to CeloHT's visual identity.
Lucide Icons may be used for interface icons.
Icons should:
- Communicate clearly
- Include accessible labels where necessary
- Avoid replacing important textual information
Framer Motion may be used where animation improves user experience.
Animation should not:
- Reduce accessibility
- Create unnecessary distraction
- Significantly increase page weight
- Interfere with critical actions
CeloHT's Web3 infrastructure is centered on the Celo ecosystem.
Potential blockchain integrations include:
- Celo mainnet
- Celo test environments
- CELO
- cUSD
- Smart contracts
- Blockchain RPC endpoints
CELO is the native asset of the Celo blockchain.
Within CeloHT applications, CELO may be used for supported blockchain transactions and network gas requirements.
CeloHT should clearly distinguish CELO from any CeloHT project token.
cUSD may be supported for stable-value digital transactions within compatible CeloHT applications.
Applications must clearly communicate that stable-value assets remain subject to the risks and characteristics of their underlying ecosystem.
CeloHT does not require a proprietary token.
The technology stack should therefore not imply that users need to purchase a CeloHT token to access the ecosystem.
See:
NO_TOKEN_POLICY.md
CeloHT applications may integrate with compatible wallets, including:
- Valora
- MiniPay
- WalletConnect-compatible wallets
Wallet integrations should use established standards and should never require users to disclose private keys.
WalletConnect may provide interoperability with compatible wallet applications.
Integration should clearly identify:
- Network
- Account
- Transaction
- Requested permissions
Where decentralized logic is required, CeloHT may use Solidity-based smart contracts.
Smart contracts should follow:
- Minimalism
- Least privilege
- Testing
- Security review
- Source verification
See SMART_CONTRACTS.md.
Solidity is the primary language for EVM-compatible smart contracts where CeloHT requires custom on-chain logic.
Compiler versions should be explicitly pinned.
Example:
Solidity
↓
Contract Source
↓
Compiler
↓
Bytecode + ABI
↓
Celo Network
OpenZeppelin libraries may be used for established smart-contract patterns.
Examples include:
- Access control
- Security utilities
- Standard interfaces
- Contract modules
Dependencies should be version-pinned and reviewed.
CeloHT backend services may use JavaScript/TypeScript-compatible server environments.
Potential responsibilities include:
- API endpoints
- Authentication
- Authorization
- Data processing
- Blockchain indexing
- Notifications
- Program management
APIs should follow consistent principles:
- Input validation
- Authentication
- Authorization
- Rate limiting
- Error handling
- Logging
- Versioning
Sensitive API endpoints should require appropriate authorization.
A relational database may be used for application data.
Potential data domains include:
- Users
- Agents
- Courses
- Lessons
- Quizzes
- Communities
- Programs
- Events
- Analytics
Database schemas should be version-controlled.
Where appropriate, CeloHT projects may use Supabase for backend infrastructure.
Potential services include:
- PostgreSQL
- Authentication
- Storage
- APIs
- Realtime functionality
Supabase credentials must never be committed to public repositories.
PostgreSQL may serve as the primary relational database for structured application data.
Database design should emphasize:
- Referential integrity
- Appropriate indexing
- Constraints
- Query performance
- Backup and recovery
- Least-privilege access
Authentication may combine conventional application authentication with wallet-based authentication depending on the application.
Authentication architecture should be documented independently.
See:
AUTHENTICATION_ARCHITECTURE.md
Authorization should enforce permissions according to user roles and application requirements.
The principle of least privilege should apply throughout the system.
See:
AUTHORIZATION_MODEL.md
CeloHT should avoid storing unnecessary personal information.
Sensitive data should be:
- Minimized
- Protected
- Access-controlled
- Encrypted where appropriate
- Deleted when no longer required
See:
DATA_PRIVACY.md
CeloHT applications may use modern cloud hosting platforms.
Hosting decisions should consider:
- Reliability
- Security
- Cost
- Performance
- Geographic availability
- Vendor dependency
Vercel may be used for compatible Next.js applications.
Potential capabilities include:
- Application deployment
- Edge delivery
- Serverless functions
- Preview deployments
- Environment management
- Web analytics
Specific projects should document their actual deployment provider rather than assuming Vercel.
GitHub may serve as a central platform for:
- Source code
- Documentation
- Issues
- Pull requests
- Releases
- Discussions
- Collaboration
Repositories should follow appropriate branch protection and access controls.
GitHub Actions may automate:
- Tests
- Linting
- Type checking
- Builds
- Security checks
- Deployment
Example pipeline:
Push / Pull Request
↓
Lint
↓
Type Check
↓
Tests
↓
Security Checks
↓
Build
↓
Deploy
Projects should use automated quality checks where practical.
Possible tools include:
- ESLint
- Prettier
- TypeScript
- Commitlint
- Husky
The exact tool configuration belongs to each repository.
Testing should cover multiple layers:
- Unit tests
- Integration tests
- End-to-end tests
- Smart-contract tests
- Security tests
See TESTING.md.
Security tooling may include:
- CodeQL
- Dependency scanning
- Secret scanning
- Static analysis
- Smart-contract analysis
Automated tooling does not replace manual security review.
Dependencies should be:
- Pinned or appropriately constrained
- Regularly reviewed
- Updated responsibly
- Checked for vulnerabilities
Dependabot or equivalent tooling may be used.
Different environments should use separate configurations.
Typical environments:
Development
↓
Testing
↓
Staging
↓
Production
See ENVIRONMENT_CONFIGURATION.md.
Secrets must never be committed to public source repositories.
Examples include:
- API keys
- Database credentials
- Deployment tokens
- Private infrastructure credentials
- Authentication secrets
Use appropriate environment-variable or secret-management systems.
Blockchain applications require RPC access to interact with the Celo network.
Applications should:
- Validate chain IDs
- Handle provider failures
- Avoid exposing provider secrets
- Consider redundancy for critical services
Blockchain explorers can provide public transaction and contract visibility.
Where applicable, CeloHT documentation should link to authoritative explorer records for official contract deployments.
Where an application needs efficient access to blockchain history, an indexing layer may be used.
Indexing can reduce unnecessary direct blockchain queries.
Indexed data should remain distinguishable from canonical blockchain state.
Off-chain storage may be used for:
- Documents
- Images
- Educational materials
- Program records
- Application assets
Storage permissions should be explicitly configured.
A CDN may improve delivery of:
- Static assets
- Images
- Public content
- JavaScript bundles
- CSS
Caching rules should not accidentally expose private information.
Production applications should monitor:
- Availability
- Latency
- Error rates
- Database health
- API usage
- Blockchain provider status
Alerts should focus on actionable problems.
Logs should provide enough information to investigate operational issues.
Logs should not unnecessarily contain:
- Passwords
- Private keys
- Seed phrases
- Authentication tokens
- Sensitive personal data
Performance engineering should focus on:
- Core Web Vitals
- API latency
- Database performance
- Bundle size
- Image optimization
- Blockchain request efficiency
See PERFORMANCE.md.
CeloHT interfaces should strive to meet modern accessibility standards.
Important considerations include:
- Keyboard navigation
- Screen-reader compatibility
- Color contrast
- Focus states
- Form labels
- Error messages
- Responsive design
CeloHT may support multiple languages.
Potential languages include:
- Haitian Creole
- French
- English
Translations should preserve technical meaning and avoid mixing languages unnecessarily.
Technical documentation should include:
- Setup instructions
- Architecture
- API references
- Deployment procedures
- Security requirements
- Troubleshooting
- Contribution guidelines
Documentation should evolve with implementation.
CeloHT should make it easy for contributors to:
- Clone repositories
- Install dependencies
- Configure environments
- Run tests
- Start development servers
- Understand architecture
- Submit changes
A typical development workflow may resemble:
Clone Repository
↓
Install Dependencies
↓
Configure Environment
↓
Run Development Server
↓
Run Tests
↓
Create Branch
↓
Submit Pull Request
Exact commands belong in repository-specific documentation.
Releases should be reproducible and documented.
Release processes should define:
- Version
- Changes
- Testing
- Approval
- Deployment
- Rollback
See RELEASE_PROCESS.md.
Software versions should follow a consistent strategy.
Where Semantic Versioning is appropriate:
MAJOR.MINOR.PATCH
See VERSIONING.md.
The technology stack is not permanent.
Components may be replaced when:
- Security requires it
- Performance requires it
- Costs become unreasonable
- Better standards emerge
- Maintenance becomes impractical
- Community requirements change
New technologies should be evaluated based on:
- Security
- Reliability
- Community support
- Maintainability
- Cost
- Performance
- Interoperability
- Strategic fit
Popularity alone is not sufficient justification.
CeloHT should understand the risks associated with external providers.
Critical systems should have migration strategies where practical.
Open-source development allows contributors and researchers to inspect and improve CeloHT technology.
Public code should therefore maintain appropriate standards for:
- Quality
- Documentation
- Security
- Licensing
- Contribution
Each repository should clearly state its applicable software and documentation licenses.
Licensing decisions should be reviewed where third-party dependencies or external intellectual property are involved.
CeloHT should track significant technical debt.
Technical debt may include:
- Outdated dependencies
- Temporary architecture
- Missing tests
- Legacy code
- Performance limitations
- Documentation gaps
Technical debt should be prioritized according to risk and impact.
Technology priorities should align with CeloHT's broader roadmap.
Potential priorities include:
- Improved wallet integrations
- Better education tools
- Agent infrastructure
- Security improvements
- Analytics
- Environmental tracking
- Developer tooling
- Mobile accessibility
Technology should remain a means to accomplish CeloHT's mission.
The goal is not to maximize the number of technologies used.
The goal is to build a system that is:
Secure. Reliable. Open. Accessible. Maintainable. Useful.
Document Status: Active / Evolving Maintained By: CeloHT Community Primary Authors: Johnny Dubic & CeloHT Community
© 2026 CeloHT - Open Source. Global Impact. Licensed under Apache.