# anhsirksai/luma-connects architecture

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

- Interactive diagram: https://gitdiagram.com/anhsirksai/luma-connects
- Repository: https://github.com/anhsirksai/luma-connects

## Overview

Luma Connects turns a Luma event URL into an analyzed attendee shortlist: the web app starts and tracks a backend run, which ingests event and public-web evidence, classifies people, and exposes a room snapshot and natural-language chat. The graph also retains documented login, messaging/payment webhook, and CLI capabilities. Some pipeline and integration internals are unsampled; edges below are limited to README statements, visible excerpts, or SOURCE INDEX references.

Main entry points: [`src/invite_finder/pipeline.py`](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/pipeline.py) (Analysis pipeline), [`src/invite_finder/api/routes_events.py`](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_events.py) (Event routes), [`src/invite_finder/api/app.py`](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/app.py) (FastAPI service), [`src/invite_finder/api/routes_chat.py`](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_chat.py) (Chat routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web interface"]
  node_webapp["Next.js app<br/>[page.tsx]"]
  node_event_detail["Event detail<br/>[page.tsx]"]
  node_chat_ui["Chat and cards<br/>[ConnectorChat.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_api_types["API shapes<br/>[api-shape.ts]"]
end

subgraph group_api["API and access"]
  node_api_service["FastAPI service<br/>[app.py]"]
  node_event_routes["Event routes<br/>[routes_events.py]"]
  node_chat_routes["Chat routes<br/>[routes_chat.py]"]
  node_run_routes["Run progress routes<br/>[routes_runs.py]"]
  node_auth_routes["Login routes<br/>[routes_auth.py]"]
  node_webhook_routes["Webhook routes<br/>[routes_webhooks.py]"]
  node_cli["Discovery CLI<br/>[cli.py]"]
end

subgraph group_research["Event research"]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_luma_ingest["Luma ingestion<br/>[luma.py]"]
  node_discovery_agent["Web discovery agent<br/>[agent.py]"]
  node_brightdata["Bright Data APIs<br/>[brightdata.py]"]
end

subgraph group_insights["People and insights"]
  node_classification["People classification<br/>[classify.py]"]
  node_snapshot["Room snapshot<br/>[snapshot.py]"]
  node_chat_engine["Chat assistant<br/>[chat.py]"]
end

subgraph group_state["Persistence and integrations"]
  node_database[("SQLite database<br/>[db.py]")]
  node_event_store["Event records<br/>[event_store.py]"]
  node_people_store["People records<br/>[people_store.py]"]
  node_run_store["Run records<br/>[run_store.py]"]
  node_cache["Response cache<br/>[cache.py]"]
  node_auth_store["Auth records<br/>[auth_store.py]"]
  node_linq["Linq messaging<br/>[linq.py]"]
  node_commerce_store["Commerce records<br/>[commerce_store.py]"]
end

node_operator(("Event researcher"))

node_operator -->|"submits URL"| node_webapp
node_webapp -->|"starts run"| node_api_client
node_api_client -->|"normalizes data"| node_api_types
node_api_client -->|"calls API"| node_api_service
node_api_service -->|"registers routes"| node_event_routes
node_api_service -->|"registers routes"| node_chat_routes
node_api_service -->|"registers routes"| node_run_routes
node_api_service -->|"registers routes"| node_auth_routes
node_api_service -->|"registers routes"| node_webhook_routes
node_event_routes -->|"starts analysis"| node_pipeline
node_pipeline -->|"fetches event"| node_luma_ingest
node_pipeline -->|"discovers profiles"| node_discovery_agent
node_discovery_agent -->|"searches and fetches"| node_brightdata
node_luma_ingest -->|"fetches page"| node_brightdata
node_pipeline -->|"classifies people"| node_classification
node_pipeline -->|"computes snapshot"| node_snapshot
node_pipeline -->|"uses records"| node_event_store
node_pipeline -->|"uses records"| node_people_store
node_pipeline -->|"updates status"| node_run_store
node_event_routes -->|"reads events"| node_event_store
node_event_routes -->|"reads people"| node_people_store
node_event_routes -->|"reads runs"| node_run_store
node_event_routes -->|"builds snapshot"| node_snapshot
node_run_routes -->|"streams events"| node_run_store
node_chat_routes -->|"answers query"| node_chat_engine
node_chat_routes -->|"checks event"| node_event_store
node_chat_routes -->|"checks people"| node_people_store
node_chat_engine -->|"returns cards"| node_chat_ui
node_run_routes -->|"streams progress"| node_event_detail
node_event_routes -->|"serves event data"| node_event_detail
node_auth_routes -->|"manages sessions"| node_auth_store
node_auth_routes -->|"sends passcode"| node_linq
node_webhook_routes -->|"settles payment"| node_commerce_store
node_webhook_routes -->|"handles messages"| node_linq
node_cli -.->|"runs discovery"| node_discovery_agent
node_event_store -.->|"persists data"| node_database
node_people_store -.->|"persists data"| node_database
node_run_store -.->|"persists data"| node_database
node_cache -.->|"caches responses"| node_brightdata

click node_webapp "https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/events/page.tsx"
click node_event_detail "https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/events/%5Bid%5D/page.tsx"
click node_chat_ui "https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/components/event/ConnectorChat.tsx"
click node_api_client "https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/lib/api.ts"
click node_api_types "https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/lib/api-shape.ts"
click node_api_service "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/app.py"
click node_event_routes "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_events.py"
click node_chat_routes "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_chat.py"
click node_run_routes "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_runs.py"
click node_auth_routes "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_auth.py"
click node_webhook_routes "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_webhooks.py"
click node_cli "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/cli.py"
click node_pipeline "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/pipeline.py"
click node_luma_ingest "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/luma.py"
click node_discovery_agent "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/agent.py"
click node_brightdata "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/brightdata.py"
click node_classification "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/classify.py"
click node_snapshot "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/snapshot.py"
click node_chat_engine "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/chat.py"
click node_database "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/db.py"
click node_event_store "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/event_store.py"
click node_people_store "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/people_store.py"
click node_run_store "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/run_store.py"
click node_cache "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/cache.py"
click node_auth_store "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/auth_store.py"
click node_linq "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/linq.py"
click node_commerce_store "https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/commerce_store.py"

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_webapp,node_event_detail,node_chat_ui,node_api_client,node_api_types toneBlue
class node_api_service,node_event_routes,node_chat_routes,node_run_routes,node_auth_routes,node_webhook_routes,node_cli toneAmber
class node_pipeline,node_luma_ingest,node_discovery_agent,node_brightdata toneMint
class node_classification,node_snapshot,node_chat_engine toneRose
class node_database,node_event_store,node_people_store,node_run_store,node_cache,node_auth_store,node_linq,node_commerce_store,node_operator toneIndigo
```

## Components

### Web interface

- [Next.js app](https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/events/page.tsx): `invite_viewer/app/events/page.tsx`
- [Event detail](https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/events/%5Bid%5D/page.tsx): `invite_viewer/app/events/[id]/page.tsx`
- [Chat and cards](https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/components/event/ConnectorChat.tsx): `invite_viewer/app/components/event/ConnectorChat.tsx`
- [API client](https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/lib/api.ts): `invite_viewer/app/lib/api.ts`
- [API shapes](https://github.com/anhsirksai/luma-connects/blob/main/invite_viewer/app/lib/api-shape.ts): `invite_viewer/app/lib/api-shape.ts`

### API and access

- [FastAPI service](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/app.py): `src/invite_finder/api/app.py`
- [Event routes](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_events.py): `src/invite_finder/api/routes_events.py`
- [Chat routes](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_chat.py): `src/invite_finder/api/routes_chat.py`
- [Run progress routes](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_runs.py): `src/invite_finder/api/routes_runs.py`
- [Login routes](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_auth.py): `src/invite_finder/api/routes_auth.py`
- [Webhook routes](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/api/routes_webhooks.py): `src/invite_finder/api/routes_webhooks.py`
- [Discovery CLI](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/cli.py): `src/invite_finder/cli.py`

### Event research

- [Analysis pipeline](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/pipeline.py): `src/invite_finder/pipeline.py`
- [Luma ingestion](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/luma.py): `src/invite_finder/luma.py`
- [Web discovery agent](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/agent.py): `src/invite_finder/agent.py`
- [Bright Data APIs](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/brightdata.py): `src/invite_finder/brightdata.py`

### People and insights

- [People classification](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/classify.py): `src/invite_finder/classify.py`
- [Room snapshot](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/snapshot.py): `src/invite_finder/snapshot.py`
- [Chat assistant](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/chat.py): `src/invite_finder/chat.py`

### Persistence and integrations

- [SQLite database](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/db.py): `src/invite_finder/db.py`
- [Event records](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/event_store.py): `src/invite_finder/store/event_store.py`
- [People records](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/people_store.py): `src/invite_finder/store/people_store.py`
- [Run records](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/run_store.py): `src/invite_finder/store/run_store.py`
- [Response cache](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/cache.py): `src/invite_finder/cache.py`
- [Auth records](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/auth_store.py): `src/invite_finder/store/auth_store.py`
- [Linq messaging](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/linq.py): `src/invite_finder/linq.py`
- [Commerce records](https://github.com/anhsirksai/luma-connects/blob/main/src/invite_finder/store/commerce_store.py): `src/invite_finder/store/commerce_store.py`

### Other components

- **Event researcher**

## Connections

- Event researcher → Next.js app: submits URL (evidence: `README.md`)
- Next.js app → API client: starts run (evidence: `invite_viewer/app/events/page.tsx`)
- API client → API shapes: normalizes data (evidence: `invite_viewer/app/lib/api.ts`)
- API client → FastAPI service: calls API (evidence: `README.md`)
- FastAPI service → Event routes: registers routes (evidence: `src/invite_finder/api/app.py`)
- FastAPI service → Chat routes: registers routes (evidence: `src/invite_finder/api/app.py`)
- FastAPI service → Run progress routes: registers routes (evidence: `src/invite_finder/api/app.py`)
- FastAPI service → Login routes: registers routes (evidence: `src/invite_finder/api/app.py`)
- FastAPI service → Webhook routes: registers routes (evidence: `src/invite_finder/api/app.py`)
- Event routes → Analysis pipeline: starts analysis (evidence: `src/invite_finder/api/routes_events.py`)
- Analysis pipeline → Luma ingestion: fetches event (evidence: `src/invite_finder/pipeline.py`)
- Analysis pipeline → Web discovery agent: discovers profiles (evidence: `src/invite_finder/pipeline.py`)
- Web discovery agent → Bright Data APIs: searches and fetches (evidence: `README.md`)
- Luma ingestion → Bright Data APIs: fetches page (evidence: `README.md`)
- Analysis pipeline → People classification: classifies people (evidence: `src/invite_finder/pipeline.py`)
- Analysis pipeline → Room snapshot: computes snapshot (evidence: `src/invite_finder/pipeline.py`)
- Analysis pipeline → Event records: uses records (evidence: `src/invite_finder/pipeline.py`)
- Analysis pipeline → People records: uses records (evidence: `src/invite_finder/pipeline.py`)
- Analysis pipeline → Run records: updates status (evidence: `src/invite_finder/pipeline.py`)
- Event routes → Event records: reads events (evidence: `src/invite_finder/api/routes_events.py`)
- Event routes → People records: reads people (evidence: `src/invite_finder/api/routes_events.py`)
- Event routes → Run records: reads runs (evidence: `src/invite_finder/api/routes_events.py`)
- Event routes → Room snapshot: builds snapshot (evidence: `src/invite_finder/api/routes_events.py`)
- Run progress routes → Run records: streams events (evidence: `src/invite_finder/api/routes_runs.py`)
- Chat routes → Chat assistant: answers query (evidence: `src/invite_finder/api/routes_chat.py`)
- Chat routes → Event records: checks event (evidence: `src/invite_finder/api/routes_chat.py`)
- Chat routes → People records: checks people (evidence: `src/invite_finder/api/routes_chat.py`)
- Chat assistant → Chat and cards: returns cards (evidence: `README.md`)
- Run progress routes → Event detail: streams progress (evidence: `invite_viewer/app/events/[id]/page.tsx`)
- Event routes → Event detail: serves event data (evidence: `invite_viewer/app/events/[id]/page.tsx`)
- Login routes → Auth records: manages sessions (evidence: `src/invite_finder/api/routes_auth.py`)
- Login routes → Linq messaging: sends passcode (evidence: `src/invite_finder/api/routes_auth.py`)
- Webhook routes → Commerce records: settles payment (evidence: `src/invite_finder/api/routes_webhooks.py`)
- Webhook routes → Linq messaging: handles messages (evidence: `src/invite_finder/api/routes_webhooks.py`)
- Discovery CLI → Web discovery agent: runs discovery (evidence: `README.md`)
- Event records → SQLite database: persists data
- People records → SQLite database: persists data
- Run records → SQLite database: persists data
- Response cache → Bright Data APIs: caches responses
