# walphi/auro-app architecture

> Architecture diagram of the GitHub repository walphi/auro-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/walphi/auro-app
- Repository: https://github.com/walphi/auro-app

## Overview

1. This repo is a multi-surface AI real-estate platform, not a single app. The production runtime is centered on Netlify serverless functions, a Supabase-backed data layer, and external AI/communications services. The root also contains extensive operational scripts and diagnostics, but those are support tooling rather than user-facing runtime.

2. There are two main client surfaces:
   - `src/` is the root React app, which includes a dashboard plus marketing pages.
   - `sites/` is a separate Vite React app for generated “agent sites” and their section-based rendering system.
   Both are static frontends that consume APIs and content from the backend layer.

3. The backend is mostly in `netlify/functions/` with one edge function in `netlify/edge-functions/`. These handlers expose the product’s API surface: WhatsApp, VAPI, RAG, listings sync, OCR, site generation, CRM sync, image proxying, booking notifications, and tenant/agent site lookup. This is the primary boundary where all external requests enter the system.

4. Core AI orchestration lives under `lib/`. Important subsystems include:
   - `lib/gemini.ts` for model access.
   - `lib/aiBuilder/` for generating agent sites/content.
   - `lib/rag/` for embeddings, prompts, and retrieval helpers.
   - `lib/agentLogic.ts`, `lib/crmRouter.ts`, `lib/notificationOrchestrator.ts`, and tenant config helpers for routing requests across tenants, channels, and downstream actions.
   These modules are shared by the Netlify handlers rather than serving directly.

5. The main conversational flow is channel-driven. Incoming WhatsApp or VAPI events hit their respective Netlify functions, which then:
   - identify tenant/agent context,
   - fetch relevant knowledge or listing data,
   - call Gemini or other tools,
   - persist lead/session state,
   - and respond back through Twilio/VAPI.
   This is the most important request/response loop in the system.

6. Retrieval-Augmented Generation is a distinct subsystem. It has ingestion, learning, query, delete, and embedding-processing handlers (`rag-ingest`, `rag-learn`, `rag-query`, `rag-delete`, `process-embeddings`) plus supporting SQL/schema files. The knowledge base is tenant-aware and appears to index project/listing documents, campaign history, and other real-estate content used by the assistants.

7. CRM and lead management form another boundary. Functions such as `update-lead`, `crm sync` handlers, HubSpot OAuth/webhook handlers, and Bitrix webhooks connect external sales systems to the platform. The data model tracks leads, intents, bookings, and agent activity so conversational events can be mirrored into CRM workflows.

8. Real-estate listings and media are handled as a separate ingestion/sync pipeline. There are functions for scraping listings and site style, syncing listings, formatting images, proxying images, and updating listing records. This pipeline feeds both the AI assistants and the generated sites, rather than being just a content feed.

9. Agent-site generation is its own product subdomain. The backend can build or rebuild a site from structured data and templates, while the `sites/` app renders the final public-facing experience with reusable sections like hero, services, listings, testimonials, and contact. The generated site content is stored and later served through lookup functions such as `get-agent-site`.

10. Persistence is primarily Supabase/Postgres. The repo includes both `supabase/migrations/` and standalone `sql/` scripts, indicating a mix of formal migrations and one-off schema/data fixes. The schema covers tenants, profiles, projects, RAG chunks, leads, bookings, agent configs, and site-related tables, which makes tenancy a first-class architectural boundary.

11. Operationally, the repository includes many scripts for validation, backfills, simulation, image cleanup, DB checks, and webhook testing. These are important for maintenance and verification, but they sit outside the runtime request path.

12. Deployment is Netlify-centric. The repo ships static frontend builds plus serverless functions, with environment variables for Gemini, Twilio, and optional VAPI verification. External dependencies are therefore not embedded services but runtime integrations orchestrated at the function layer.

Main entry points: [`netlify/functions/orchestrator.ts`](https://github.com/walphi/auro-app/blob/main/netlify/functions/orchestrator.ts) (Netlify API), [`supabase_schema.sql`](https://github.com/walphi/auro-app/blob/main/supabase_schema.sql) (Schema), [`netlify/functions/whatsapp.ts`](https://github.com/walphi/auro-app/blob/main/netlify/functions/whatsapp.ts) (WhatsApp Flow), [`netlify/functions/vapi.ts`](https://github.com/walphi/auro-app/blob/main/netlify/functions/vapi.ts) (VAPI Flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["Frontends"]
  node_src_app["Dashboard<br/>React app<br/>[App.jsx]"]
  node_src_marketing["Marketing<br/>pages<br/>[Home.jsx]"]
  node_sites_app["Agent Sites<br/>Vite app<br/>[App.tsx]"]
  node_sites_sections["Sections<br/>renderer"]
end

subgraph group_runtime["Runtime API"]
  node_netlify_api["Netlify API<br/>functions<br/>[orchestrator.ts]"]
  node_whatsapp_flow["WhatsApp Flow<br/>channel handler<br/>[whatsapp.ts]"]
  node_vapi_flow["VAPI Flow<br/>channel handler<br/>[vapi.ts]"]
  node_rag_api["RAG API<br/>retrieval handlers<br/>[rag-api.ts]"]
  node_crm_api["CRM Sync<br/>lead handlers<br/>[update-lead.ts]"]
  node_site_api["Site Build<br/>site handlers"]
  node_listings_api["Listings Sync<br/>ingestion handlers<br/>[sync-listings.ts]"]
end

subgraph group_core["Shared Core"]
  node_ai_builder["Site Builder<br/>AI orchestration<br/>[buildSite.ts]"]
  node_gemini(("Gemini<br/>model client<br/>[gemini.ts]"))
  node_rag_core["RAG Core<br/>retrieval utils<br/>[rag-utils.ts]"]
  node_tenant_logic["Tenant Logic<br/>routing core<br/>[tenantConfig.ts]"]
  node_crm_logic["CRM Logic<br/>integration core<br/>[crmRouter.ts]"]
  node_media_core["Media Core<br/>image pipeline<br/>[mediaHandler.ts]"]
end

subgraph group_data["Data Layer"]
  node_supabase_schema[("Schema")]
  node_migrations["Migrations"]
  node_sql_scripts["SQL Scripts<br/>schema fixes"]
end

subgraph group_ops["Ops Tooling"]
  node_ops_scripts["Ops Scripts<br/>maintenance<br/>[rag_eval.ts]"]
end

node_src_app -->|"dashboard data"| node_netlify_api
node_src_marketing -->|"lead capture"| node_netlify_api
node_sites_app -->|"render data"| node_site_api
node_sites_sections -->|"compose UI"| node_sites_app
node_netlify_api -->|"route events"| node_whatsapp_flow
node_netlify_api -->|"route events"| node_vapi_flow
node_netlify_api -->|"knowledge ops"| node_rag_api
node_netlify_api -->|"lead sync"| node_crm_api
node_netlify_api -->|"site ops"| node_site_api
node_netlify_api -->|"listing ops"| node_listings_api
node_whatsapp_flow -->|"identify tenant"| node_tenant_logic
node_vapi_flow -->|"identify tenant"| node_tenant_logic
node_whatsapp_flow -->|"retrieve knowledge"| node_rag_core
node_vapi_flow -->|"retrieve knowledge"| node_rag_core
node_whatsapp_flow -->|"generate reply"| node_gemini
node_vapi_flow -->|"generate reply"| node_gemini
node_crm_api -->|"sync leads"| node_crm_logic
node_site_api -->|"build site"| node_ai_builder
node_ai_builder -->|"generate content"| node_gemini
node_listings_api -->|"process media"| node_media_core
node_rag_api -->|"store chunks"| node_supabase_schema
node_crm_api -->|"store leads"| node_supabase_schema
node_site_api -->|"store sites"| node_supabase_schema
node_listings_api -->|"store listings"| node_supabase_schema
node_migrations -->|"evolve schema"| node_supabase_schema
node_sql_scripts -->|"fix schema"| node_supabase_schema
node_ops_scripts -.->|"verify runtime"| node_netlify_api
node_ops_scripts -.->|"inspect data"| node_supabase_schema

click node_src_app "https://github.com/walphi/auro-app/blob/main/src/App.jsx"
click node_src_marketing "https://github.com/walphi/auro-app/blob/main/src/marketing/pages/Home.jsx"
click node_sites_app "https://github.com/walphi/auro-app/blob/main/sites/src/App.tsx"
click node_sites_sections "https://github.com/walphi/auro-app/blob/main/sites/src/components/SectionRenderer.tsx"
click node_netlify_api "https://github.com/walphi/auro-app/blob/main/netlify/functions/orchestrator.ts"
click node_whatsapp_flow "https://github.com/walphi/auro-app/blob/main/netlify/functions/whatsapp.ts"
click node_vapi_flow "https://github.com/walphi/auro-app/blob/main/netlify/functions/vapi.ts"
click node_rag_api "https://github.com/walphi/auro-app/blob/main/netlify/functions/rag-api.ts"
click node_crm_api "https://github.com/walphi/auro-app/blob/main/netlify/functions/update-lead.ts"
click node_site_api "https://github.com/walphi/auro-app/blob/main/netlify/functions/build-site-background.ts"
click node_listings_api "https://github.com/walphi/auro-app/blob/main/netlify/functions/sync-listings.ts"
click node_ai_builder "https://github.com/walphi/auro-app/blob/main/lib/aiBuilder/buildSite.ts"
click node_gemini "https://github.com/walphi/auro-app/blob/main/lib/gemini.ts"
click node_rag_core "https://github.com/walphi/auro-app/blob/main/lib/rag/rag-utils.ts"
click node_tenant_logic "https://github.com/walphi/auro-app/blob/main/lib/tenantConfig.ts"
click node_crm_logic "https://github.com/walphi/auro-app/blob/main/lib/crmRouter.ts"
click node_media_core "https://github.com/walphi/auro-app/blob/main/lib/mediaHandler.ts"
click node_supabase_schema "https://github.com/walphi/auro-app/blob/main/supabase_schema.sql"
click node_migrations "https://github.com/walphi/auro-app/blob/main/supabase/migrations/20260118000000_add_tenants_and_lead_tenant_id.sql"
click node_sql_scripts "https://github.com/walphi/auro-app/blob/main/sql/create_site_tables.sql"
click node_ops_scripts "https://github.com/walphi/auro-app/blob/main/scripts/rag_eval.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_app,node_src_marketing,node_sites_app,node_sites_sections toneBlue
class node_netlify_api,node_whatsapp_flow,node_vapi_flow,node_rag_api,node_crm_api,node_site_api,node_listings_api toneAmber
class node_ai_builder,node_gemini,node_rag_core,node_tenant_logic,node_crm_logic,node_media_core toneMint
class node_supabase_schema,node_migrations,node_sql_scripts toneRose
class node_ops_scripts toneIndigo
```

## Components

### Frontends

Static React surfaces for dashboard, marketing, and generated agent sites.

- [Dashboard](https://github.com/walphi/auro-app/blob/main/src/App.jsx): React app · Root React app with admin/dashboard and marketing pages. · `src/App.jsx`
- [Marketing](https://github.com/walphi/auro-app/blob/main/src/marketing/pages/Home.jsx): pages · Public-facing marketing pages and conversion components. · `src/marketing/pages/Home.jsx`
- [Agent Sites](https://github.com/walphi/auro-app/blob/main/sites/src/App.tsx): Vite app · Generated public agent-site frontend with section-based rendering. · `sites/src/App.tsx`
- [Sections](https://github.com/walphi/auro-app/blob/main/sites/src/components/SectionRenderer.tsx): renderer · Reusable section renderer and page blocks for generated sites. · `sites/src/components/SectionRenderer.tsx`

### Runtime API

Netlify handlers that expose the product's request/response boundary.

- [Netlify API](https://github.com/walphi/auro-app/blob/main/netlify/functions/orchestrator.ts): functions · Primary serverless API boundary for chat, RAG, listings, CRM, OCR, and site generation. · `netlify/functions/orchestrator.ts`
- [WhatsApp Flow](https://github.com/walphi/auro-app/blob/main/netlify/functions/whatsapp.ts): channel handler · WhatsApp entrypoint and downstream messaging handlers. · `netlify/functions/whatsapp.ts`
- [VAPI Flow](https://github.com/walphi/auro-app/blob/main/netlify/functions/vapi.ts): channel handler · Voice assistant entrypoint and webhook handling. · `netlify/functions/vapi.ts`
- [RAG API](https://github.com/walphi/auro-app/blob/main/netlify/functions/rag-api.ts): retrieval handlers · Ingest, learn, query, delete, and embed-processing handlers for tenant knowledge. · `netlify/functions/rag-api.ts`
- [CRM Sync](https://github.com/walphi/auro-app/blob/main/netlify/functions/update-lead.ts): lead handlers · Lead updates, HubSpot/Bitrix sync, and booking notifications. · `netlify/functions/update-lead.ts`
- [Site Build](https://github.com/walphi/auro-app/blob/main/netlify/functions/build-site-background.ts): site handlers · Agent-site generation, lookup, and rebuild handlers. · `netlify/functions/build-site-background.ts`
- [Listings Sync](https://github.com/walphi/auro-app/blob/main/netlify/functions/sync-listings.ts): ingestion handlers · Listing scraping, sync, image formatting, and image proxy handlers. · `netlify/functions/sync-listings.ts`

### Shared Core

Reusable orchestration, AI, tenant, CRM, and media logic used by handlers.

- [Site Builder](https://github.com/walphi/auro-app/blob/main/lib/aiBuilder/buildSite.ts): AI orchestration · Generates agent sites and content from structured data and prompts. · `lib/aiBuilder/buildSite.ts`
- [Gemini](https://github.com/walphi/auro-app/blob/main/lib/gemini.ts): model client · Shared model access layer for LLM calls. · `lib/gemini.ts`
- [RAG Core](https://github.com/walphi/auro-app/blob/main/lib/rag/rag-utils.ts): retrieval utils · Embedding, prompt, and retrieval helpers used by knowledge functions. · `lib/rag/rag-utils.ts`
- [Tenant Logic](https://github.com/walphi/auro-app/blob/main/lib/tenantConfig.ts): routing core · Tenant config, agent logic, and channel routing across subsystems. · `lib/tenantConfig.ts`
- [CRM Logic](https://github.com/walphi/auro-app/blob/main/lib/crmRouter.ts): integration core · HubSpot, Bitrix, and lead-routing helpers. · `lib/crmRouter.ts`
- [Media Core](https://github.com/walphi/auro-app/blob/main/lib/mediaHandler.ts): image pipeline · Image processing, proxying, and media helpers shared by handlers. · `lib/mediaHandler.ts`

### Data Layer

Supabase/Postgres schema, migrations, and SQL scripts that define tenancy and persistence.

- [Schema](https://github.com/walphi/auro-app/blob/main/supabase_schema.sql): Postgres schema · Tenants, profiles, projects, leads, bookings, RAG chunks, and site tables. · `supabase_schema.sql`
- [Migrations](https://github.com/walphi/auro-app/blob/main/supabase/migrations/20260118000000_add_tenants_and_lead_tenant_id.sql): Supabase migrations · Formal schema evolution for tenancy, RAG, profiles, and WhatsApp numbers. · `supabase/migrations/20260118000000_add_tenants_and_lead_tenant_id.sql`
- [SQL Scripts](https://github.com/walphi/auro-app/blob/main/sql/create_site_tables.sql): schema fixes · One-off schema, data, and backfill scripts for production fixes. · `sql/create_site_tables.sql`

### Ops Tooling

Support scripts, diagnostics, and maintenance utilities outside the main runtime path.

- [Ops Scripts](https://github.com/walphi/auro-app/blob/main/scripts/rag_eval.ts): maintenance · Validation, debugging, simulation, and backfill tooling. · `scripts/rag_eval.ts`

## Connections

- Dashboard → Netlify API: dashboard data · Dashboard UI consumes backend APIs for admin and tenant operations.
- Marketing → Netlify API: lead capture · Marketing pages feed waitlist and inquiry traffic into the backend.
- Agent Sites → Site Build: render data · Generated sites fetch agent-site content and configuration from lookup handlers.
- Sections → Agent Sites: compose UI · Section components build the public site experience.
- Netlify API → WhatsApp Flow: route events · Netlify functions route inbound WhatsApp traffic to conversation handlers.
- Netlify API → VAPI Flow: route events · Netlify functions route voice interactions to VAPI handlers.
- Netlify API → RAG API: knowledge ops · API surface exposes tenant-aware RAG ingestion and query endpoints.
- Netlify API → CRM Sync: lead sync · API surface exposes lead and CRM integration endpoints.
- Netlify API → Site Build: site ops · API surface exposes generation, lookup, and rebuild endpoints for agent sites.
- Netlify API → Listings Sync: listing ops · API surface exposes scraping, sync, OCR, and image utilities.
- WhatsApp Flow → Tenant Logic: identify tenant · WhatsApp requests resolve tenant and agent context before responding.
- VAPI Flow → Tenant Logic: identify tenant · Voice requests resolve tenant and agent context before responding.
- WhatsApp Flow → RAG Core: retrieve knowledge · Chat flow queries tenant knowledge and listing context.
- VAPI Flow → RAG Core: retrieve knowledge · Voice flow queries tenant knowledge and listing context.
- WhatsApp Flow → Gemini: generate reply · Chat flow calls the model for response generation and summarization.
- VAPI Flow → Gemini: generate reply · Voice flow calls the model for response generation and tool use.
- CRM Sync → CRM Logic: sync leads · CRM handlers normalize and route events into external sales systems.
- Site Build → Site Builder: build site · Site generation handlers invoke the site builder pipeline.
- Site Builder → Gemini: generate content · Builder uses the model to synthesize content and structure.
- Listings Sync → Media Core: process media · Listing pipeline formats and proxies property images.
- RAG API → Schema: store chunks · Retrieval system persists embeddings and knowledge records in Postgres.
- CRM Sync → Schema: store leads · Lead and booking state is mirrored into the database.
- Site Build → Schema: store sites · Generated site content and configuration are persisted for later lookup.
- Listings Sync → Schema: store listings · Listings and media metadata are written back to the database.
- Migrations → Schema: evolve schema · Migrations define the canonical database evolution path.
- SQL Scripts → Schema: fix schema · One-off SQL scripts patch and backfill production data structures.
- Ops Scripts → Netlify API: verify runtime · Maintenance scripts exercise and diagnose the production handlers.
- Ops Scripts → Schema: inspect data · Support tooling checks tables, columns, and records.