# nyaruka/rapidpro architecture

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

- Interactive diagram: https://gitdiagram.com/nyaruka/rapidpro
- Repository: https://github.com/nyaruka/rapidpro

## Overview

##### Main Components
- Frontend/Web Layer: Represented by the templates, static assets, and all client-side code (JS, CSS, fonts, images). This is where users interact via browsers or mobile devices.
- Application Server/Backend: The core of RapidPro lives in the “temba” directory and its many submodules (ai, airtime, api, channels, flows, contacts, campaigns, tickets, etc.). This is your Django-based server following the MVT (Model-View-Template) pattern, handling business logic, API endpoints (e.g., temba/api and temba/api/v2), scheduling, and more.
- Database & Data Stores: The README explicitly lists PostgreSQL (the primary relational database); Redis (for caching and task queues); Elasticsearch (for searching and indexing); S3 (object storage for media); DynamoDB (for NoSQL-like operations); and Cloudwatch (for monitoring/logging).
- External Components/Services: The architecture supports related services developed by TextIt such as Mailroom, Courier, Indexer, and Archiver. These can be shown as connected microservices or separate application components that integrate with the core system.

##### Detail the Relationships and Interactions
- For search and indexing features, the Application Server sends events/queries to Elasticsearch.
- Integrations with S3 (for storing media, uploads, etc.) and with DynamoDB if applicable for specific data access patterns.
- External services (Mailroom, Courier, Indexer, Archiver) should be shown as connected to the core application – either consuming data (like outbound messaging or archiving flows) or providing supplementary services. Represent them with separate labels and note that they may interact with other systems or share similar storage backends.
- Optionally, include Cloudwatch as a monitoring/observability layer that gathers logs and system metrics from the Application Server and related services.

##### Architectural Patterns and Design Principles
- Separation between presentation (templates/static), business logic (temba modules), and data persistence (databases and storages) which is inherent in the MVT pattern.
- Integration points with external messaging channels and third-party APIs, especially in the “channels” and “api” modules.

##### Final Touches
- Balance detail and clarity so that all major architectural elements and data flows are captured without overwhelming the viewer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users
    user["User (Browser/Mobile)"]:::client

    %% Frontend/Web Layer
    subgraph "Frontend/Web Layer"
        web["Web Client"]:::frontend
        templates["Templates"]:::frontend
        staticAssets["Static Assets"]:::frontend
        localeFiles["Locale Files"]:::frontend
    end

    %% Application Server (Django)
    subgraph "Application Server (Django)"
        managePy["manage.py (Entry Point)"]:::backend
        tembaCore["Temba Core (Modular Django App)"]:::backend
        apiEndpoints["API Endpoints (temba/api & temba/api/v2)"]:::module
        flowsModule["Flows/Workflows (temba/flows)"]:::module
        contactsModule["Contacts Management (temba/contacts)"]:::module
        campaignsModule["Campaigns (temba/campaigns)"]:::module
        channelsModule["Channels/Integrations (temba/channels)"]:::module
        ticketsModule["Tickets (temba/tickets)"]:::module

        managePy --> tembaCore
        tembaCore --> apiEndpoints
        tembaCore --> flowsModule
        tembaCore --> contactsModule
        tembaCore --> campaignsModule
        tembaCore --> channelsModule
        tembaCore --> ticketsModule
    end

    %% Data Stores
    subgraph "Data Stores"
        pg["((PostgreSQL DB))"]:::database
        redis["((Redis Cache/Queues))"]:::database
        es["((Elasticsearch))"]:::database
        s3["((S3 Object Storage))"]:::database
        dynamodb["((DynamoDB))"]:::database
        cloudwatch["((Cloudwatch Monitoring))"]:::database
    end

    %% External Services
    subgraph "External Services"
        mailroom["Mailroom"]:::external
        courier["Courier"]:::external
        indexer["Indexer"]:::external
        archiver["Archiver"]:::external
    end

    %% Data Flow Connections
    user -->|"HTTP/HTTPS"| web
    web -->|"Loads"| templates
    web -->|"Loads"| staticAssets
    web -->|"Loads"| localeFiles
    web -->|"Sends Request"| managePy

    %% Application Server Interactions with Data Stores
    tembaCore -->|"Queries"| pg
    tembaCore -->|"Uses"| redis
    flowsModule -->|"Search/Index"| es
    contactsModule -->|"Stores Data"| pg
    campaignsModule -->|"Stores Data"| pg
    tembaCore -->|"Media Storage"| s3
    tembaCore -->|"NoSQL Access"| dynamodb
    tembaCore -->|"Logs/Metrics"| cloudwatch

    %% API specific connection (example)
    apiEndpoints -->|"API Calls"| pg
    apiEndpoints -->|"Caching/Task Queue"| redis

    %% External Integrations
    channelsModule -->|"Messaging Integration"| mailroom
    ticketsModule -->|"Ticket Data"| pg
    tembaCore -->|"Archival Data"| archiver
    courier -- "Notification" --> tembaCore
    indexer -- "Indexing" --> es

    %% Click Events for Frontend/Web Layer
    click templates "https://github.com/nyaruka/rapidpro/tree/main/templates/"
    click staticAssets "https://github.com/nyaruka/rapidpro/tree/main/static/"
    click localeFiles "https://github.com/nyaruka/rapidpro/tree/main/locale/"

    %% Click Events for Application Server/Backend
    click managePy "https://github.com/nyaruka/rapidpro/blob/main/manage.py"
    click tembaCore "https://github.com/nyaruka/rapidpro/tree/main/temba/"
    click apiEndpoints "https://github.com/nyaruka/rapidpro/tree/main/temba/api"
    click flowsModule "https://github.com/nyaruka/rapidpro/tree/main/temba/flows"
    click contactsModule "https://github.com/nyaruka/rapidpro/tree/main/temba/contacts"
    click campaignsModule "https://github.com/nyaruka/rapidpro/tree/main/temba/campaigns"
    click channelsModule "https://github.com/nyaruka/rapidpro/tree/main/temba/channels"
    click ticketsModule "https://github.com/nyaruka/rapidpro/tree/main/temba/tickets"

    %% Click Events for External Components
    click mailroom "https://github.com/nyaruka/rapidpro/tree/main/temba/mailroom"
    click archiver "https://github.com/nyaruka/rapidpro/tree/main/temba/archives"

    %% Styles
    classDef client fill:#f9e79f,stroke:#000,stroke-width:2px;
    classDef frontend fill:#aed6f1,stroke:#000,stroke-width:2px;
    classDef backend fill:#a9dfbf,stroke:#000,stroke-width:2px;
    classDef module fill:#d5f5e3,stroke:#000,stroke-width:2px;
    classDef database fill:#fadbd8,stroke:#000,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#000,stroke-width:2px;
```
