# digidem/earth-defenders-assistant architecture

> Architecture diagram of the GitHub repository digidem/earth-defenders-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/digidem/earth-defenders-assistant
- Repository: https://github.com/digidem/earth-defenders-assistant

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD

    %% Core Backend Services
    subgraph "Core Backend Services"
        WA("WhatsApp Bot Service"):::backend
        APIA("AI API Service"):::backend
        APIS("API / Supabase Functions"):::backend
        WA -->|"message_data"| APIA
        APIA -->|"data_queries"| APIS
    end

    %% Frontend Applications
    subgraph "Frontend Applications"
        DB("Dashboard Frontend"):::frontend
        LP("Landing Page Frontend"):::frontend
        DOC("Documentation Portal"):::frontend
        DB -->|"REST_API"| APIS
        LP -->|"REST_API"| APIS
        DOC -->|"REST_API"| APIS
    end

    %% Plugin System
    subgraph "Plugin System"
        GP_OF("Grant Plugin: Opportunity Finder"):::plugin
        GP_PW("Grant Plugin: Proposal Writer"):::plugin
        OG("Onboarding Plugin"):::plugin
        GP_OF -->|"extends"| APIA
        GP_PW -->|"extends"| APIA
        OG -->|"extends"| APIA
    end

    %% Shared Packages
    subgraph "Shared Packages"
        AN("Analytics"):::package
        JB("Jobs"):::package
        LG("Logger"):::package
        KV("KV (rate_limiting)"):::package
        SU("Supabase Client/Utilities"):::package
        TY("Types"):::package
        UI("UI Components"):::package
        EM("Email"):::package
        SIM("Simulator"):::package
    end

    %% Dependencies from Shared Packages to Core Backend Services
    AN -->|"dep"| APIA
    JB -->|"dep"| APIA
    LG -->|"dep"| APIA
    KV -->|"dep"| APIA
    SU -->|"dep"| APIA
    TY -->|"dep"| APIA
    EM -->|"dep"| APIA
    SIM -->|"dep"| APIA
    UI -->|"dep"| DB

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        DEP("Deploy Infrastructure"):::deployment
    end

    %% Deployment manages various applications
    DEP -->|"manages"| WA
    DEP -->|"manages"| APIA
    DEP -->|"manages"| APIS
    DEP -->|"manages"| DB
    DEP -->|"manages"| LP
    DEP -->|"manages"| DOC

    %% Click Events
    click WA "https://github.com/digidem/earth-defenders-assistant/tree/main/apps/whatsapp"
    click APIA "https://github.com/digidem/earth-defenders-assistant/tree/main/apps/ai_api"
    click APIS "https://github.com/digidem/earth-defenders-assistant/tree/main/apps/api/supabase"
    click DB "https://github.com/digidem/earth-defenders-assistant/tree/main/apps/dashboard"
    click LP "https://github.com/digidem/earth-defenders-assistant/tree/main/apps/landingpage"
    click DOC "https://github.com/digidem/earth-defenders-assistant/tree/main/apps/docs"
    click GP_OF "https://github.com/digidem/earth-defenders-assistant/tree/main/plugins/grant_plugin/opportunity_finder"
    click GP_PW "https://github.com/digidem/earth-defenders-assistant/tree/main/plugins/grant_plugin/proposal_writer"
    click OG "https://github.com/digidem/earth-defenders-assistant/tree/main/plugins/onboarding"
    click AN "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/analytics"
    click JB "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/jobs"
    click LG "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/logger"
    click KV "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/kv"
    click SU "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/supabase"
    click TY "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/types"
    click UI "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/ui"
    click EM "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/email"
    click SIM "https://github.com/digidem/earth-defenders-assistant/tree/main/packages/simulator"
    click DEP "https://github.com/digidem/earth-defenders-assistant/tree/main/deploy"

    %% Styles
    classDef backend fill:#AED6F1,stroke:#1F618D,stroke-width:2px,color:#000000;
    classDef frontend fill:#A9DFBF,stroke:#1E8449,stroke-width:2px,color:#000000;
    classDef plugin fill:#F9E79F,stroke:#B7950B,stroke-width:2px,color:#000000;
    classDef package fill:#F5CBA7,stroke:#9C640C,stroke-width:2px,color:#000000;
    classDef deployment fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px,color:#000000;
```
