12 backend modules

Overview

The backend provides APIs, services, and business logic that power the platform. It handles off-chain processing, data management, and integration with on-chain components.

Module Architecture

Core Services

• Auth & RBAC Service

• Project Management Service

• PoAI Service

• Marketplace Pricing Engine

• Reporting Engine

• Indexer Service

Supporting Services

• Document Storage Service

• Notification Service

• Analytics Service

• Payment Processing Service

---

Auth & RBAC Service

Purpose: Authentication and role-based access control

Features

Authentication:

• JWT token generation and validation

• OAuth integration (optional)

• Wallet signature verification

• Session management

Authorization:

• Role-based access control (RBAC)

• Permission checking

• API endpoint protection

• Resource-level permissions

User Management:

• User registration

• User profile management

• Password reset

• Email verification

Roles Supported

• Retail User

• Enterprise User (with sub-roles: Admin, Finance, Auditor, Viewer)

• Project Owner / Issuer

• PoAI Reviewer

• Governance Member

• Platform Admin

API Endpoints

POST   /auth/register
POST   /auth/login
POST   /auth/logout
POST   /auth/refresh
POST   /auth/verify-wallet
GET    /auth/me
PUT    /auth/profile
POST   /auth/reset-password

---

Project Management Service

Purpose: CRUD operations for projects and project lifecycle management

Features

Project CRUD:

• Create project

• Read project details

• Update project (limited, based on status)

• List projects with filters

Document Management:

• Upload project documents

• Store documents (encrypted)

• Generate document hashes

• Document retrieval

Status Management:

• Status transitions

• Status validation

• Status history

Project Search:

• Full-text search

• Filter by type, geography, vintage, etc.

• Sort and pagination

Data Model

• Projects table

• Project documents table

• Project status history

• Project metadata

API Endpoints

POST   /projects
GET    /projects
GET    /projects/:id
PUT    /projects/:id
DELETE /projects/:id
POST   /projects/:id/documents
GET    /projects/:id/documents
DELETE /projects/:id/documents/:docId
POST   /projects/:id/submit-poai
GET    /projects/:id/status

---

PoAI Service

Purpose: Proof-of-Asset-Integrity verification workflow and proof generation

Features

PoAI Case Management:

• Create PoAI cases

• Assign reviewers

• Track case status

• Case history

Integrity Checks:

• Asset integrity validation

• Data integrity validation

• Process integrity validation

• Automated checks (optional)

• Manual reviewer checks

Proof Generation:

• Compile proof bundle JSON

• Generate proof hashes (bundle, asset, data, process)

• Sign proof bundle (optional)

• Store proof bundle (encrypted)

Reviewer Workflow:

• Case assignment

• Check completion

• Approval/rejection

• Change requests

Data Model

• PoAI cases table

• PoAI checks table

• PoAI proofs table

• Audit logs table

API Endpoints

GET    /poai/cases
GET    /poai/cases/:id
POST   /poai/cases/:id/assign
POST   /poai/cases/:id/checks
PUT    /poai/cases/:id/checks/:checkId
POST   /poai/cases/:id/request-changes
POST   /poai/cases/:id/approve
POST   /poai/cases/:id/reject
GET    /poai/cases/:id/proof

---

Marketplace Pricing Engine

Purpose: Dynamic pricing and fee calculation

Features

Pricing Calculation:

• Base price per project/vintage

• Market-based pricing (optional)

• Dynamic pricing adjustments

• Price history

Fee Management:

• Platform fees

• Enterprise custom fees

• Payment processing fees

• Fee distribution

Price Display:

• Real-time price updates

• Price per unit

• Total price calculation

• Currency conversion (if multi-currency)

Pricing Factors

• Project type

• Vintage year

• Verifier reputation

• Supply and demand

• Market conditions

API Endpoints

GET    /marketplace/projects
GET    /marketplace/projects/:id/price
GET    /marketplace/projects/:id/availability
POST   /marketplace/calculate-price
GET    /marketplace/fees

---

Reporting Engine

Purpose: Certificate generation and ESG report creation

Features

Certificate Generation:

• Retirement certificate PDF generation

• Certificate JSON metadata

• Certificate templates

• Custom certificate fields

ESG Reports:

• Period-based ESG summaries

• Project-level reports

• Audit trail reports

• Custom report generation

Report Formats:

• PDF (human-readable)

• CSV (spreadsheet)

• JSON (machine-readable)

• Excel (formatted)

Export Management:

• Report generation queue

• Report storage

• Download links

• Email delivery

Certificate Contents

• Project details

• Retirement quantity

• Retirement timestamp

• Transaction hash

• PoAI proof hash reference

• Certificate ID

• Platform branding

API Endpoints

POST   /reports/certificates/generate
GET    /reports/certificates/:id
POST   /reports/esg/generate
GET    /reports/esg/:id
POST   /reports/audit/generate
GET    /reports/audit/:id
GET    /reports/history

---

Indexer Service

Purpose: Listen to blockchain events and sync to database

Features

Event Listening:

• Listen to smart contract events

• Parse event data

• Store in database

• Handle event ordering

Events Tracked:

• ProjectRecordMinted

• CreditsMinted

• CreditsTransferred (if transfers enabled)

• CreditsRetired

• ProjectConfigured

• ProjectSuspended

• Governance events

Database Sync:

• Update project records

• Update credit balances

• Update retirement records

• Maintain transaction history

Error Handling:

• Handle missed events (re-sync)

• Handle reorgs

• Handle contract upgrades

Event Processing Flow

Blockchain Event Emitted
    ↓
Indexer Listens
    ↓
Parse Event Data
    ↓
Validate Event
    ↓
Update Database
    ↓
Trigger Actions (e.g., certificate generation)

API Endpoints

GET    /indexer/status
POST   /indexer/sync/:blockNumber
GET    /indexer/events
GET    /indexer/events/:txHash

---

Document Storage Service

Purpose: Secure document storage and retrieval

Features

Document Upload:

• Encrypted storage (S3/IPFS)

• Document hash generation

• Metadata storage

• Access control

Document Retrieval:

• Secure download links

• Presigned URLs (time-limited)

• Access logging

• Document versioning

Document Types:

• Project documents

• PoAI proof bundles

• Certificates

• Reports

• User-uploaded files

Storage Options

• AWS S3 (encrypted)

• IPFS (with encryption)

• Local storage (for development)

API Endpoints

POST   /storage/upload
GET    /storage/:fileId
GET    /storage/:fileId/download
DELETE /storage/:fileId

---

Notification Service

Purpose: User notifications and alerts

Features

Notification Types:

• Email notifications

• In-app notifications

• SMS notifications (optional)

• Push notifications (optional)

Notification Triggers:

• Project status changes

• PoAI case updates

• Purchase confirmations

• Retirement completions

• Certificate ready

• Governance proposals

• Scheduled retirement reminders

Notification Preferences:

• User-configurable preferences

• Notification frequency

• Notification channels

API Endpoints

GET    /notifications
GET    /notifications/:id
PUT    /notifications/:id/read
PUT    /notifications/preferences

---

Analytics Service

Purpose: Platform metrics and analytics

Features

Metrics Tracking:

• User activity

• Purchase volume

• Retirement volume

• Project metrics

• Platform health

Analytics Dashboards:

• Admin dashboard

• Enterprise analytics

• Public statistics (optional)

Reporting:

• Daily/weekly/monthly reports

• Custom date ranges

• Export capabilities

Metrics Tracked

• Total projects

• Total credits issued

• Total credits retired

• Active users

• Purchase volume

• Retirement volume

• Platform revenue

---

Payment Processing Service

Purpose: Handle payment processing (if off-chain payments supported)

Features

Payment Methods:

• Credit card

• Bank transfer

• Crypto payments

• Invoice (for enterprises)

Payment Processing:

• Payment gateway integration

• Payment validation

• Payment confirmation

• Refund handling

Payment Records:

• Payment history

• Receipts

• Invoice generation

API Endpoints

POST   /payments/process
GET    /payments/:id
POST   /payments/:id/refund
GET    /payments/history

---

Database Schema (Summary)

Core Tables

• users - User accounts

• organizations - Enterprise organizations

• projects - Project records

• project_documents - Project documents

• poai_cases - PoAI verification cases

• poai_checks - PoAI integrity checks

• poai_proofs - PoAI proof bundles

• credit_balances - Credit balances (synced from chain)

• orders - Purchase orders

• retirements - Retirement records

• certificates - Retirement certificates

• governance_proposals - Governance proposals

• audit_logs - Audit trail

---

API Architecture

REST API

• RESTful endpoints

• JSON request/response

• Standard HTTP status codes

• Error handling

Authentication

• JWT tokens

• API key (for services)

• Wallet signature (for on-chain actions)

Rate Limiting

• Per-user rate limits

• Per-endpoint rate limits

• Abuse prevention

Error Handling

• Standard error format

• Error codes

• Error messages

• Stack traces (development only)