-
Notifications
You must be signed in to change notification settings - Fork 0
API_ARCHITECTURE.md
Version: 1.0 Project: CeloHT Architecture: Modular API Architecture Blockchain: Celo
This document defines the conceptual API architecture for the CeloHT ecosystem.
The API layer provides controlled communication between CeloHT applications, databases, blockchain infrastructure, analytics systems, and external services.
The API layer must not bypass security boundaries or expose private credentials.
CLIENTS
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Website dApp Agent App
│ │ │
└──────────────┼──────────────┘
▼
API / Gateway
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Auth Service Core Service Data Service
│ │ │
└─────────────┼─────────────┘
▼
Integration Layer
│ │
▼ ▼
Database Celo
The API layer may provide:
- Application data
- User-facing services
- Agent services
- Educational content
- Impact metrics
- Transaction status
- Blockchain indexing
- Administrative services
The API should not be used to store or process user private keys.
Presentation
│
▼
API Gateway / Routing
│
▼
Authentication
│
▼
Authorization
│
▼
Business Logic
│
├── Database
├── Blockchain
└── External Services
Public endpoints may not require authentication.
Protected endpoints should require appropriate authentication.
Examples:
Public
GET /api/education
Authenticated
GET /api/profile
Authorized
POST /api/agent/operation
Administrative
POST /api/admin/configuration
Authentication and authorization must remain separate concepts.
Authorization should determine whether an authenticated identity may perform an operation.
Potential roles include:
USER
AGENT
PARTNER
MODERATOR
ADMIN
GOVERNANCE
Roles should follow least privilege.
Breaking API changes should use versioning.
Example:
/api/v1/
/api/v2/
Versioning prevents existing clients from unexpectedly breaking.
Every API endpoint should validate:
- Required fields
- Data types
- Allowed values
- Request size
- Authentication state
- Authorization
- Blockchain addresses where applicable
Never trust client-side validation alone.
API responses should use predictable structures.
Conceptual example:
{
"success": true,
"data": {},
"error": null
}Error responses should provide useful information without exposing internal secrets.
API errors should distinguish between:
- Validation errors
- Authentication errors
- Authorization errors
- Not-found errors
- Rate-limit errors
- Internal errors
- Blockchain errors
- External-service errors
Public endpoints should use rate limiting where appropriate.
Potential controls:
- Requests per IP
- Requests per account
- Requests per API key
- Endpoint-specific limits
Sensitive endpoints should have stricter limits.
Cross-origin access should be explicitly configured.
Production APIs should not use unrestricted CORS unless there is a specific reason.
Allowed origins should be documented.
Blockchain-related APIs may provide:
- Transaction status
- Contract information
- Wallet balances
- Event information
- Network status
The API should distinguish:
Transaction Submitted
↓
Transaction Pending
↓
Transaction Confirmed
↓
Transaction Finalized
The exact confirmation model depends on the Celo infrastructure being used.
The API communicates with the application database through a controlled data-access layer.
Client
│
▼
API
│
▼
Service
│
▼
Data Access Layer
│
▼
Database
Clients should never directly access privileged database credentials.
Potential agent endpoints may include:
GET /api/agents
GET /api/agents/{id}
POST /api/agents/register
PATCH /api/agents/{id}
POST /api/agents/operations
Agent permissions must be explicitly controlled.
Potential endpoints:
GET /api/education
GET /api/education/{id}
GET /api/courses
POST /api/progress
Educational records should be protected according to their sensitivity.
Potential endpoints:
GET /api/impact
GET /api/impact/education
GET /api/impact/agents
GET /api/impact/reforestation
Public impact data should use clearly defined metrics.
Logs should capture appropriate operational information:
- Timestamp
- Endpoint
- Request identifier
- Status
- Latency
- Error category
Logs must not contain:
- Private keys
- Seed phrases
- Passwords
- Authentication secrets
- Sensitive personal information
The API architecture should protect against:
- Injection
- Broken authentication
- Broken authorization
- Excessive requests
- Data leakage
- SSRF where applicable
- Malicious payloads
- Dependency vulnerabilities
Monitor:
- Request volume
- Error rate
- Latency
- Availability
- Rate-limit events
- Authentication failures
- Blockchain integration failures
GitHub
│
▼
CI/CD
│
▼
API Build
│
▼
Deployment Platform
│
▼
API Service
│
┌─┼───────────────┐
▼ ▼ ▼
DB Celo External APIs
- Authentication defined
- Authorization defined
- Input validation
- Rate limiting
- CORS configured
- API versioning
- Error handling
- Logging
- Monitoring
- Secrets protected
- Documentation maintained
Document: API Architecture Version: 1.0 Project: CeloHT
© 2026 CeloHT - Open Source. Global Impact. Licensed under Apache.