System Architecture

Overview

EarthTeam follows a three-tier architecture with a React Native mobile frontend and a Next.js 15 web platform consuming a shared Django REST API backed by PostgreSQL with PostGIS for geospatial data. The platform integrates with the Solana blockchain for token and rewards management and with LLM endpoints for the gAIa conversational assistant.

| Tier | Technology | Purpose | |------|-----------|---------| | Presentation | React Native (Expo) + Next.js 15 | Mobile app and web platform user interfaces | | Application | Django 5 + Django REST Framework | RESTful API, business logic, authentication, verification workflows | | Data | PostgreSQL + PostGIS | Relational data, geospatial queries, content storage |

Architecture Diagram Gallery

High-Level Architecture

Microservices Layout

gAIa Architecture

Verification Flow

Data Flow

Gold Reserve Certificate Design

High-Level Architecture

The EarthTeam platform is built around a centralized API that serves two distinct frontend clients and integrates with external blockchain and AI services.

┌─────────────────────┐     ┌─────────────────────┐
│   React Native App  │     │   Next.js Web App   │
│   (Expo / Mobile)   │     │   (Next.js 15)      │
└─────────┬───────────┘     └──────────┬──────────┘
          │                            │
          └──────────┬─────────────────┘
                     │ HTTPS / JWT
                     ▼
          ┌─────────────────────┐
          │   Django REST API   │
          │   (DRF / Gunicorn)  │
          └─────────┬───────────┘
                    │
         ┌──────────┼──────────┐
         ▼          ▼          ▼
   ┌──────────┐ ┌────────┐ ┌──────────┐
   │PostgreSQL│ │ Solana │ │ LLM APIs │
   │+ PostGIS │ │  RPC   │ │ (Claude) │
   └──────────┘ └────────┘ └──────────┘

Key Design Decisions

Shared API: Both frontends consume the same Django REST API, ensuring consistent business logic and data access patterns across platforms.
JWT Authentication: Access tokens with configurable expiry (15 minutes for mobile, 7 days for web) with refresh token rotation.
Geospatial Foundation: PostGIS enables efficient location-based queries for the interactive 3D globe, proximity searches, and geotagged content.
Blockchain Integration: Solana RPC calls are handled server-side through web3.py, keeping private keys and signing operations on the backend.

Microservices Layout

The current architecture is primarily a monolithic Django application with clear module boundaries, supplemented by Celery workers for async task processing. Several additional services (including a planned RAG service for gAIa, push notification delivery, and a blockchain indexer) are being developed as independent microservices.

gAIa Architecture

The gAIa provides conversational AI assistance to users directly within the mobile app. It enables conservation-related Q&A, project recommendations, verification guidance, and contextual help.

Architecture Overview

┌──────────────┐      ┌─────────────────┐      ┌──────────────┐
│  Mobile App  │─────▶│ Django API      │─────▶│  Claude API  │
│  (Chat UI)   │◀────│ (ai_oracle app) │◀────│  (Anthropic) │
└──────────────┘      └────────┬────────┘      └──────────────┘
                               │
                     ┌─────────▼─────────┐
                     │  PostgreSQL       │
                     │  (Conversation    │
                     │   History + Cache)│
                     └───────────────────┘

Request Flow

User sends a message from the mobile chat interface
Django API receives the request and constructs a prompt with relevant context (user profile, recent activity, project data)
The prompt is sent to the Claude API via the Anthropic SDK
Claude’s response is streamed back through the Django API to the mobile client
Conversation history is persisted in PostgreSQL for context continuity across sessions

Planned Enhancements (Sprint 3)

Prompt Caching: Cache frequently used system prompts to reduce API costs and latency
Conversation Memory: Multi-turn dialogue with summarization for long conversations
Context Injection: Dynamically inject project data, verification guidelines, and user statistics into prompts
RAG Service: Standalone microservice using vector search over the conservation knowledge base

Verification Flow

The verification workflow is a core EarthTeam feature that enables citizen scientists to submit proof of conservation actions and earn Stars rewards.

End-to-End Flow

Step 1: User Submits Verification Post

User creates a post with photos and text describing their conservation action. The post is tagged with location data and associated with a conservation project.

Step 2: Post Enters Verification Queue

The post is added to the verification marketplace where registered verifiers can browse and claim pending tasks.

Step 3: Verifier Claims & Reviews

A verifier claims the task, reviews the submitted evidence (photos, location data, description), and either approves or rejects the submission.

Step 4: Reward Distribution

On approval, Stars are credited to the user’s wallet. The transaction is recorded on-chain via Solana. On rejection, the user receives feedback and can resubmit.

Verification States

| State | Description | |-------|------------| | pending | Submitted and awaiting a verifier to claim | | claimed | A verifier has claimed the task and is reviewing | | approved | Verified as authentic — Stars rewarded | | rejected | Evidence insufficient — user may resubmit | | disputed | Under admin review due to verifier disagreement |

Data Flow

Both read and write operations flow from the frontend clients through the Django REST API to PostgreSQL. Frontends use TanStack Query for caching, background refetch, and optimistic updates. Side effects such as blockchain transactions and push notifications are dispatched as asynchronous tasks. Images uploaded by users are validated server-side, with thumbnails generated asynchronously.

Gold Reserve Certificate Design

The Gold Reserve Certificate (GRC) is a planned NFT-style digital certificate minted on the Solana blockchain for each completed verification. It serves as immutable proof of conservation impact.

Certificate Structure

| Field | Description | |-------|------------| | Token Standard | SPL NFT (Metaplex) | | Metadata | Timestamp, GPS coordinates, project ID, verifier ID, Star reward amount | | Media | Verification photos stored on Arweave / IPFS | | On-chain | Mint address stored in PostgreSQL linking user to certificate |

Planned Features (Sprint 4)

Automatic minting on verification approval
Gallery view on user profiles (mobile + web)
Shareable certificate card with QR code for off-chain verification
Verifiable via Solana block explorer

Tech Stack

| Layer | Technology | Version | Purpose | |-------|-----------|---------|---------| | Mobile Frontend | React Native (Expo) | SDK 52 | Cross-platform mobile application | | Web Frontend | Next.js | 15 | Server-rendered web platform with Turbopack | | Web UI Framework | Tailwind CSS | 4 | Utility-first styling with dark theme | | API Framework | Django REST Framework | Latest | RESTful API endpoints and serialization | | Backend Runtime | Django | 5 | Application server and ORM | | Database | PostgreSQL | 16 | Primary relational data store | | Geospatial | PostGIS | 3.4 | Geospatial queries and indexing | | Cache / Queue | Redis | 7 | Celery broker and cache backend | | Async Tasks | Celery | Latest | Background job processing | | Blockchain | Solana | — | Token ($ETC) and rewards ledger | | Blockchain SDK | web3.py | Latest | Solana RPC integration (server-side) | | AI | Claude API (Anthropic) | — | gAIa conversational assistant | | Vector Search | pgvector | Planned | Semantic search for RAG knowledge base | | Push Notifications | Firebase FCM / APNs | — | Mobile push notification delivery | | HTTP Client (Frontend) | Axios | Latest | HTTP client with JWT interceptors | | Server State | TanStack Query | 5 | Data fetching, caching, and synchronization | | Containerization | Docker | — | Development and deployment containers | | Reverse Proxy | Nginx | — | TLS termination and request routing |

API Conventions

The EarthTeam API follows RESTful conventions:

| Convention | Detail | |-----------|--------| | Base URL | Hosted on the EarthTeam servers | | Endpoint Versioning | Stable and newer endpoints are versioned for backward compatibility | | Auth | JWT Bearer tokens in Authorization header | | Content Type | application/json (multipart for image uploads) | | Pagination | Cursor-based for feeds, page-based for lists | | Error Format | { "detail": "...", "code": "..." } | | Rate Limiting | Tiered per endpoint group (auth, reads, writes) |

API Documentation

Interactive Swagger/OpenAPI documentation provides full endpoint listings, request/response schemas, and the ability to test API calls directly from the browser.

Security Architecture

| Aspect | Implementation | |--------|---------------| | Authentication | JWT (access + refresh tokens) with rotation | | Authorization | DRF permissions, role-based access (user, verifier, admin, org) | | Transport | HTTPS with TLS 1.3 | | API Protection | Rate limiting, input validation, CSRF for web | | Data Storage | Passwords hashed (bcrypt), sensitive config in .env | | Blockchain | Server-side signing, never expose private keys to clients |

This architecture documentation is a living document and will be updated as the platform evolves. Last updated: June 2026.