02 architecture design
System Architecture Overview
The platform is built on a hybrid architecture combining:
On-chain components (Smart Contracts) for immutability and trust
Off-chain components (Backend Services) for performance and user experience
Frontend applications for user interaction
Architecture Layers
Layer 1: Blockchain Layer (On-Chain)
Purpose: Immutable record-keeping and trust anchors
Components:
ProjectRegistry Contract: Stores project records and PoAI anchors
CarbonCredit1155 Contract: Semi-fungible credit units
Retirement Contract: Burn mechanism and retirement events
Governance Contract: DAO voting and policy execution
Key Properties:
Immutable project records
Hard-capped issuance
Permanent retirement records
Public auditability
Layer 2: Backend Services (Off-Chain)
Purpose: Business logic, data processing, and API services
Components:
PoAI Service: Verification workflow and proof generation
Project Management API: CRUD operations and document handling
Marketplace Pricing Engine: Dynamic pricing and fee calculation
Reporting Engine: Certificate generation and ESG report creation
Indexer Service: Blockchain event listening and database sync
Auth & RBAC Service: Authentication and role-based access control
Key Properties:
Fast query performance
Complex business logic
Document storage and encryption
User-friendly APIs
Layer 3: Frontend Applications
Purpose: User interfaces for all personas
Components:
Public Marketplace: Project discovery and browsing
Retail Dashboard: Holdings, purchases, retirement
Enterprise Dashboard: Org management, emissions mapping, reporting
Admin Panel: Project review, PoAI workflow, governance support
Design Principles
Data Flow Architecture
Project Onboarding Flow
Credit Purchase Flow
Retirement Flow
Technology Stack (Recommended)
Smart Contracts
Language: Solidity
Standard: ERC-1155 (semi-fungible), ERC-721 (project records)
Network: EVM-compatible (Ethereum, Polygon, etc.)
Backend
API Framework: Node.js / Python / Go
Database: PostgreSQL (relational data), Redis (caching)
Storage: S3/IPFS (documents and proof bundles)
Indexer: The Graph / Custom event listener
Frontend
Framework: React / Vue / Next.js
Wallet Integration: Web3.js / Ethers.js / WalletConnect
UI Library: Tailwind CSS / Material-UI
Integration Points
External Systems
Verifier Databases: For project verification references
Payment Gateways: For fiat-to-credit purchases
KYC Providers: For compliance checks
Certificate Authorities: For retirement certificates
Internal Systems
Event Bus: For async processing (retirement → certificate generation)
Notification Service: For user alerts and status updates
Analytics Service: For platform metrics and reporting
Scalability Considerations
On-Chain Optimization
Store only essential data (hashes, balances, caps)
Use events for detailed logs
Batch operations where possible
Off-Chain Optimization
Caching frequently accessed data
Database indexing for fast queries
CDN for static assets and documents
Future Extensibility
Modular contract design for upgrades
Plugin architecture for new asset types
API versioning for backward compatibility
Security Architecture
Smart Contract Security
Access control (roles and permissions)
Reentrancy protection
Integer overflow protection
Pause mechanisms for emergencies
Backend Security
API authentication (JWT)
Rate limiting
Input validation
Encrypted document storage
Frontend Security
Wallet connection validation
Transaction signing confirmation
Secure storage of sensitive data
Learn about Semi-Fungible Token System
Understand PoAI Verification System
Review Smart Contract Modules
Last updated