How digidem/earth-defenders-assistant works
Project Overview & Type
• The README explains that Earth Defenders Assistant is a dynamic, voice-first platform that creates WhatsApp bots for low-literate communities. Its design is driven by community empowerment, local data sovereignty, offline-first behavior, and a flexible plugin architecture.
• It is built as a monorepo with various applications (e.g., ai_api, api, dashboard, landingpage, whatsapp), supporting packages (e.g., analytics, jobs, logger), and plugins (e.g., grant_plugin, onboarding). This setup hints at a full-stack, modular system with several distributed components and interrelated services.
Analyzing the File Structure
• Top-Level Directories:
• apps: Contains several applications targeting different functionalities.
• ai_api: Likely the core backend of the AI-powered API including routes (classifier, heartbeat, onboarding, grant) and internal core modules (configuration, event handling, security).
• api: Appears to host Supabase functions and migration scripts; it integrates with the database layer.
• dashboard: Implements the user interface through a Next.js framework for admin or user interactions.
• landingpage: A public-facing website built with React (Vite) for showcasing the project.
• whatsapp: Provides the service that interfaces with WhatsApp, handling messages and communication.
• packages: Contains shared libraries and utilities (analytics, email, jobs, logger, kv, simulator, supabase, ui, types) that the apps rely on.
• plugins: Contains plugins (grant_plugin with opportunity_finder and proposal_writer, onboarding) that extend bot functionality. These are built in a similar fashion, with configuration files and specific module entry points.
• deploy: Contains stack definitions (for langtrace, trigger, zep) that hint at containerized deployments using Docker Compose and other orchestration setups.
• tooling: Contains developer tool configurations (for TypeScript, Next.js, React-library setups, etc.).
• This structure reinforces the modular nature of the platform and suggests distinct layers: APIs, frontends, messaging processors, and shared services.
Key Components & Their Relationships
• Core Services:
• AI API Service (apps/ai_api): Processes AI-related requests and handles voice command interpretation, routing, and business logic.
• WhatsApp Bot Service (apps/whatsapp): Manages interactions with WhatsApp, including message handling and integration with backend APIs.
• API/Supabase Functions (apps/api): Provides data access and integration with the database through Supabase, handling migrations and backend functions.
• Frontend Applications:
• Dashboard (apps/dashboard): Offers an administrative or interactive UI built in Next.js.
• Landing Page (apps/landingpage): A React/Vite-based public website likely serving marketing or informational purposes.
• Documentation (apps/docs): A documentation portal built with Astro, detailing how to use and extend the system.
• Plugin Architecture:
• Plugins (under plugins/*) introduce modular enhancements such as grant discovery, proposal writing, onboarding. They follow a consistent pattern with configuration (agents.yaml, tasks.yaml), core modules, and custom tools.
• Shared Packages:
• Packages (under packages/*): Libraries for analytics, job scheduling, logging, keys/ratelimit controls, and UI components are shared between apps – ensuring a consistent cross-application functionality.
• Deployment & Infrastructure:
• Deployments (under deploy/*): Contain Docker Compose files and environment templates that explain how different stacks (e.g., for langtrace, trigger, zep) are deployed within the distributed system.
Architectural Patterns & Design Principles
• Monorepo Organization: Centralizing multiple apps and packages in one repository ensures consistency and eases dependency management.
• Plugin-Based Modularity: The flexible plugin system allows custom extensions, visible in the structured directories under plugins.
• Decoupled Frontend/Backend: Separation between the frontend interfaces (dashboard, landingpage, docs) and backend services (ai_api, api, whatsapp) with shared services acting as integration layers.
• Offline & Local-First Design: The system is built with offline capability and local deployment in mind to support connectivity-challenged environments.
• Layered and Service-Oriented: Different layers (presentation, core business logic, infrastructure, integration) are clearly delineated within the file tree.