# arjundivecha/curate-my-world architecture

> Architecture diagram of the GitHub repository arjundivecha/curate-my-world, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arjundivecha/curate-my-world
- Repository: https://github.com/arjundivecha/curate-my-world

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-powered personalized event curation system (“Squirtle”).
- Frontend: React + TypeScript (Vite).
- Backend: Node.js + Express (`curate-events-api/`).
- Persistence: Supabase (Postgres + edge functions).
- Orchestration of 5 external data sources + Claude Sonnet 4 for conversation analysis and dynamic prompt generation.

##### File Structure
- Top-level directories:
- `src/` – React app with pages, components, hooks, UI library (shadcn-ui).
- `curate-events-api/` – Express server integrating multi-source clients, pipeline, managers, parsers.
- `supabase/functions/` – Serverless functions for collecting, deduplicating, orchestrating event ingestion.
- `supabase/migrations/` – Database schema migrations.
- `public/` – Static assets for the frontend.
- Config & scripts:
- `.env.example` + `curate-events-api/.env.example` – env var templates.
- `scripts/` – start/stop scripts, health monitors, cleanup, port management.
- `supabase/config.toml` – Supabase project config.
- External integrations indicated by `src/clients/` under the backend: Perplexity, Apyflux, PredictHQ, Exa, SerpApi, Ticketmaster, etc.

##### README for Additional Insights
- Architectural pattern:
- Multi-source parallel ingestion → aggregation pipeline → AI categorization → deduplication → location filtering → response to frontend.
- “Venue learning” and “category management” components.
- Real-time UI: dashboard, calendar, filtering.
- Key technologies:
- Claude Sonnet 4 (Anthropic) for conversation analysis.
- Supabase edge functions for serverless event collectors.
- Express for REST API on port 8765.
- React/Vite dev server on port 8766.

##### Detail
- Supabase functions folder as an orchestration layer that may be invoked by cron or directly by the backend.
- Caching, logging, environment/config modules as side utilities.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Frontend Layer"
        ReactSPA["React SPA"]:::frontend
    end

    subgraph "Backend Layer"
        ExpressAPI["Express API (8765)"]:::backend

        subgraph "API Routes"
            eventsRoute["events.js"]:::backend
            healthRoute["health.js"]:::backend
            personalizationRoute["personalization.js"]:::backend
            previewRoute["preview.js"]:::backend
            rulesRoute["rules.js"]:::backend
        end

        subgraph "Clients (Adapters)" 
            Apyflux["ApyfluxClient"]:::external
            Exa["ExaClient"]:::external
            Perplexity["PerplexityClient"]:::external
            PredictHQ["PredictHQClient"]:::external
            SerpApi["SerpApiClient"]:::external
            Serper["SerperClient"]:::external
            Ticketmaster["TicketmasterClient"]:::external
        end

        subgraph "Pipeline & Managers"
            EventPipeline["EventPipeline"]:::backend
            CategoryManager["CategoryManager"]:::backend
            VenueManager["VenueManager"]:::backend
        end

        Parser["EventParser"]:::backend

        subgraph "Utilities"
            Cache["cache.js"]:::backend
            Dedup["eventDeduplicator.js"]:::backend
            LocFilter["locationFilter.js"]:::backend
            Logger["logger.js"]:::backend
        end
    end

    subgraph "Supabase"
        Functions["Supabase Functions"]:::serverless
        DB["Supabase Postgres"]:::db
    end

    subgraph "AI Services"
        Claude["Claude Sonnet 4"]:::ai
        OpenAI["OpenAI"]:::ai
    end

    %% External Data Sources
    subgraph "External Data Sources"
        Apyflux
        Exa
        Perplexity
        PredictHQ
        SerpApi
        Serper
        Ticketmaster
    end

    %% Flows
    User-->|"interacts"|ReactSPA
    ReactSPA-->|"GET /api/events"|ExpressAPI

    ExpressAPI-->eventsRoute
    ExpressAPI-->healthRoute
    ExpressAPI-->personalizationRoute
    ExpressAPI-->previewRoute
    ExpressAPI-->rulesRoute

    eventsRoute-->EventPipeline
    personalizationRoute-->Claude
    personalizationRoute-->OpenAI

    EventPipeline-->|"uses"|Parser
    EventPipeline-->|"parallel fetch"|Apyflux
    EventPipeline-->|"parallel fetch"|Exa
    EventPipeline-->|"parallel fetch"|Perplexity
    EventPipeline-->|"parallel fetch"|PredictHQ
    EventPipeline-->|"parallel fetch"|SerpApi
    EventPipeline-->|"parallel fetch"|Serper
    EventPipeline-->|"parallel fetch"|Ticketmaster

    EventPipeline-->CategoryManager
    EventPipeline-->VenueManager
    EventPipeline-->Dedup
    EventPipeline-->LocFilter

    CategoryManager-->DB
    VenueManager-->DB
    Dedup-->DB
    LocFilter-->DB

    ExpressAPI-->Cache
    ExpressAPI-->Logger

    ExpressAPI-->Functions
    Functions-->DB

    ReactSPA-->|"fetch data"|DB

    %% Click Events
    click ReactSPA "https://github.com/arjundivecha/curate-my-world/tree/main/src/"
    click ExpressAPI "https://github.com/arjundivecha/curate-my-world/tree/main/curate-events-api/"
    click EventPipeline "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/pipeline/EventPipeline.js"
    click CategoryManager "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/managers/CategoryManager.js"
    click VenueManager "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/managers/VenueManager.js"
    click Apyflux "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/clients/ApyfluxClient.js"
    click Exa "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/clients/ExaClient.js"
    click Perplexity "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/clients/PerplexityClient.js"
    click PredictHQ "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/clients/PredictHQClient.js"
    click SerpApi "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/clients/SerpApiClient.js"
    click Serper "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/clients/SerperClient.js"
    click Ticketmaster "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/clients/TicketmasterClient.js"
    click Parser "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/parsers/EventParser.js"
    click eventsRoute "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/routes/events.js"
    click healthRoute "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/routes/health.js"
    click personalizationRoute "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/routes/personalization.js"
    click previewRoute "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/routes/preview.js"
    click rulesRoute "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/routes/rules.js"
    click Cache "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/utils/cache.js"
    click Dedup "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/utils/eventDeduplicator.js"
    click LocFilter "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/utils/locationFilter.js"
    click Logger "https://github.com/arjundivecha/curate-my-world/blob/main/curate-events-api/src/utils/logger.js"
    click Functions "https://github.com/arjundivecha/curate-my-world/tree/main/supabase/functions/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E6FFED,stroke:#28a745,color:#28a745
    classDef external fill:#FFE8D6,stroke:#fc7a1e,color:#fc7a1e
    classDef db fill:#F0F0F0,stroke:#636363,color:#636363
    classDef ai fill:#F3E5F5,stroke:#9C27B0,color:#9C27B0
    classDef serverless fill:#FFF3CD,stroke:#FFB300,color:#FFB300
```
