# supabase-community/natural-db architecture

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

- Interactive diagram: https://gitdiagram.com/supabase-community/natural-db
- Repository: https://github.com/supabase-community/natural-db

## Overview

##### Project Type and Purpose
- This is a serverless, cloud-based AI personal assistant built on Supabase.
- It combines Postgres (with pgvector and pg_cron), Supabase Edge Functions, and external services (OpenAI, Telegram, Zapier) to provide persistent memory, scheduled tasks, real-time web search, and multi-channel I/O.

##### File Structure
- Top-level
- README.md – high-level overview and architecture description
- supabase/ – Supabase project directory
- supabase/config.toml – Supabase project config
- supabase/migrations/…_create_initial_schema.sql – DB schema (extensions, memories schema, roles, cron setup)
- supabase/functions/
- natural-db/
– index.ts (main AI brain: orchestration, tool integration, DB operations)
– db-utils.ts (Postgres helpers, execute_sql tool)
– tools.ts (wrappers for web search, Zapier MCP, scheduling, etc.)
- telegram-input/index.ts – webhook handler for incoming Telegram messages
- telegram-outgoing/index.ts – response formatter and delivery

##### Extract Key Architectural Insights from README
- Core building blocks:
- Scoped Postgres schema (“memories”) with a dedicated role
- Three memory types: message history, semantic (pgvector), structured SQL
- Scheduled prompts via pg_cron
- Web Search tool for real-time info
- Zapier MCP integration (emails, calendar, notifications)
- Telegram Bot interface via webhooks
- Edge Functions serve as microservices responding to events or cron triggers

##### Main Components & Interactions
a. Components
1. Telegram Bot (external)
2. Supabase Edge Function: telegram-input
3. Supabase Edge Function: natural-db
4. Supabase Edge Function: telegram-outgoing
5. Postgres Database
– memories schema (structured tables + system_prompts)
– pgvector extension (semantic memory)
– pg_cron extension (scheduled triggers)
6. OpenAI (LLM & web search tool)
7. Zapier MCP (external actions)
b. Relationships & Data Flow
- Telegram user → Telegram Bot webhook → telegram-input function
- telegram-input → calls natural-db for processing
- natural-db
- uses db-utils to execute SQL in memories schema
- calls tools: web search, Zapier MCP, pg_cron schedule
- writes/reads from Postgres (message history, semantic embeddings, structured tables)
- natural-db → emits response to telegram-outgoing
- telegram-outgoing → posts reply back to Telegram Bot
- Cron jobs (pg_cron) automatically invoke natural-db on schedule
- natural-db → calls OpenAI APIs for LLM, embedding, web search

##### Architectural Patterns & Design Principles
- Event-driven microservices (Edge Functions triggered by HTTP/Webhook or cron)
- Single responsibility per function (ingest, core logic, outbound)
- Principle of least privilege (memories_role scoped to memories schema)
- Layered memory architecture (short-term, semantic, structured)
- Tool-oriented integration (each external capability wrapped in a tool interface)

##### Technologies & Frameworks to Highlight
- Supabase Edge Functions (TypeScript on Deno)
- PostgreSQL extensions: pgvector, pg_cron, pg_net (for HTTP calls)
- OpenAI API (LLM, embeddings, web search)
- Telegram Bot API (webhooks)
- Zapier MCP Integration
- Supabase CLI / Dashboard for deployment

##### Detailed Component Breakdown (
- Telegram Interface
- Telegram Bot → HTTPS webhook → telegram-input
- Ingestion Layer
- telegram-input → HTTP → natural-db
- Core Processing
- natural-db
– Calls db-utils (execute_sql)
– Calls tools.ts (LLM, embeddings, web search, Zapier MCP)
– Schedules tasks via pg_cron
- Data Layer
- Postgres
– memories schema tables
– public.system_prompts
– Extensions (pgvector, pg_cron)
- Outgoing Layer
- natural-db → push to telegram-outgoing → Telegram API
- Scheduled Autonomy
- pg_cron → triggers natural-db on schedule

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Project Overview"
        README["README.md"]:::external
        Config["supabase/config.toml"]:::db
        Migration["20250623120000_create_initial_schema.sql\n(supabase/migrations)"]:::db
    end

    subgraph "External Interfaces"
        TelegramBot["Telegram Bot"]:::external
    end

    subgraph "Edge Functions Layer"
        Input["telegram-input"]:::function
        subgraph "natural-db Function"
            Nat["natural-db"]:::function
            DBU["db-utils.ts"]:::function
            Tools["tools.ts"]:::function
        end
        Out["telegram-outgoing"]:::function
    end

    subgraph "Database Layer"
        Postgres["Postgres DB\n(memories schema,\npgvector, pg_cron)"]:::db
    end

    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Zapier["Zapier MCP"]:::external
    end

    TelegramBot -->|"HTTPS webhook"| Input
    Input -->|"invoke HTTP"| Nat
    Nat -->|"execute SQL"| Postgres
    Nat -->|"uses db-utils"| DBU
    Nat -->|"uses tools"| Tools
    DBU -->|"SQL ops"| Postgres
    Tools -->|"call OpenAI"| OpenAI
    Tools -->|"call Zapier"| Zapier
    Nat -->|"invoke"| Out
    Out -->|"HTTP reply"| TelegramBot
    Postgres -->|"cron trigger"| Nat

    click README "https://github.com/supabase-community/natural-db/blob/main/README.md"
    click Config "https://github.com/supabase-community/natural-db/blob/main/supabase/config.toml"
    click Migration "https://github.com/supabase-community/natural-db/blob/main/supabase/migrations/20250623120000_create_initial_schema.sql"
    click Nat "https://github.com/supabase-community/natural-db/blob/main/supabase/functions/natural-db/index.ts"
    click DBU "https://github.com/supabase-community/natural-db/blob/main/supabase/functions/natural-db/db-utils.ts"
    click Tools "https://github.com/supabase-community/natural-db/blob/main/supabase/functions/natural-db/tools.ts"
    click Input "https://github.com/supabase-community/natural-db/blob/main/supabase/functions/telegram-input/index.ts"
    click Out "https://github.com/supabase-community/natural-db/blob/main/supabase/functions/telegram-outgoing/index.ts"

    classDef function fill:#D0E6FF,stroke:#0366d6;
    classDef db fill:#DFFFE0,stroke:#228B22;
    classDef external fill:#FFE0B2,stroke:#FF8C00;
```
