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

1

Non-Custodial First

Users control their wallets and assets. Custodial options available for enterprises.

2

Compliance by Design

• Transfer policies configurable per project

• KYC/AML gates where required

• Audit trails built-in

3

Scalability

• ERC-1155 multi-token design supports millions of credits

• Off-chain indexing for fast queries

• Efficient on-chain storage (hashes only)

4

Security

• PoAI gating prevents unverified issuance

• Hard caps prevent inflation

• Retirement is irreversible

5

User Experience

• Abstracted blockchain complexity

• Fractional ownership for accessibility

• Enterprise-grade precision

Data Flow Architecture

Project Onboarding Flow

Issuer → Backend API → PoAI Service → Governance → Smart Contract

Credit Purchase Flow

User → Frontend → Backend API → Smart Contract → Indexer → Database

Retirement Flow

User → Frontend → Smart Contract (Burn) → Event → Indexer → Certificate Generator

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