# ehewes/firealarm-budget architecture

> Architecture diagram of the GitHub repository ehewes/firealarm-budget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ehewes/firealarm-budget
- Repository: https://github.com/ehewes/firealarm-budget
- Video tour (about a minute): https://gitdiagram.com/ehewes/firealarm-budget/video

## Overview

Eden Matrix turns a store URL into a categorized, rules-filtered shopping session that shoppers can hand to an agent, then supports an approval-gated purchase. The deployed product is represented by the FastAPI and Next.js trees; the README identifies the root `src/` Next.js API as a prototype, so it is not mapped as runtime. Component roles and integrations below follow the README and file paths; sampled source was limited to that prototype, so internal deployed call wiring is not asserted where it was not documented.

Main entry points: [`apps/web/lib/api.ts`](https://github.com/ehewes/firealarm-budget/blob/main/apps/web/lib/api.ts) (API client), [`apps/api/app/services/scraper.py`](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/scraper.py) (Scraping coordination), [`apps/api/app/routers/mcp.py`](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/mcp.py) (MCP access), [`apps/api/app/routers/sessions.py`](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/sessions.py) (Session endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Shopper web"]
  node_web_prefix["Prefix and session pages<br/>[page.tsx]"]
  node_web_session["Session view<br/>[session-view.tsx]"]
  node_web_dashboard["Session history<br/>[page.tsx]"]
  node_web_confirm["Purchase confirmation<br/>[page.tsx]"]
  node_web_api["API client<br/>[api.ts]"]
  node_api_accounts["Account access<br/>[account.py]"]
end

subgraph group_api["Session processing"]
  node_api_sessions["Session endpoints<br/>[sessions.py]"]
  node_api_fetch["Store fetching<br/>[fetch.py]"]
  node_api_extract["Product extraction<br/>[extract.py]"]
  node_api_scraper["Scraping coordination<br/>[scraper.py]"]
  node_api_taxonomy["Category tree<br/>[taxonomy.py]"]
  node_api_rules["Rules and ranking<br/>[rules.py]"]
  node_api_sessions_service["Session service<br/>[sessions.py]"]
end

subgraph group_agents["Agent access"]
  node_api_mcp["MCP access<br/>[mcp.py]"]
  node_api_rulesets["Rules management<br/>[rulesets.py]"]
end

subgraph group_purchase["Purchase approval"]
  node_api_purchases["Purchase endpoints<br/>[purchases.py]"]
  node_purchase_service["Purchase handling<br/>[purchases.py]"]
end

node_shopper(("Shopper"))
node_brightdata{{"Bright Data"}}
node_jev{{"Jev classification"}}
node_supabase[("Supabase")]
node_agent(("Connected agent"))
node_grok{{"Grok / Grok Bot"}}

node_shopper -->|"prefixes link"| node_web_prefix
node_web_prefix -->|"requests session"| node_web_api
node_web_api -->|"calls API"| node_api_sessions
node_api_sessions -->|"starts scraping"| node_api_scraper
node_api_scraper -->|"fetches page"| node_api_fetch
node_api_fetch -.->|"retrieves page"| node_brightdata
node_api_scraper -->|"extracts products"| node_api_extract
node_api_scraper -->|"categorizes products"| node_api_taxonomy
node_api_taxonomy -.->|"classifies"| node_jev
node_api_rules -.->|"ranks preferences"| node_jev
node_api_sessions -->|"manages sessions"| node_api_sessions_service
node_api_sessions_service -->|"stores sessions"| node_supabase
node_api_rulesets -->|"stores rules"| node_supabase
node_web_api -->|"manages rules"| node_api_rulesets
node_web_api -->|"requests account"| node_api_accounts
node_api_accounts -->|"reads account data"| node_supabase
node_web_session -->|"loads session"| node_web_api
node_web_dashboard -->|"loads history"| node_web_api
node_agent -->|"requests session data"| node_api_mcp
node_api_mcp -->|"accesses sessions"| node_api_sessions_service
node_api_mcp -->|"requests filtered items"| node_api_rules
node_grok -->|"connects over MCP"| node_api_mcp
node_agent -->|"requests purchase"| node_api_purchases
node_api_purchases -->|"creates intent"| node_purchase_service
node_purchase_service -->|"stores purchase"| node_supabase
node_shopper -->|"approves purchase"| node_web_confirm
node_web_confirm -->|"submits approval"| node_web_api
node_web_api -->|"confirms intent"| node_api_purchases

click node_web_prefix "https://github.com/ehewes/firealarm-budget/blob/main/apps/web/app/%5B...url%5D/page.tsx"
click node_web_session "https://github.com/ehewes/firealarm-budget/blob/main/apps/web/components/session-view.tsx"
click node_web_dashboard "https://github.com/ehewes/firealarm-budget/blob/main/apps/web/app/dashboard/page.tsx"
click node_web_confirm "https://github.com/ehewes/firealarm-budget/blob/main/apps/web/app/confirm/%5Bid%5D/page.tsx"
click node_web_api "https://github.com/ehewes/firealarm-budget/blob/main/apps/web/lib/api.ts"
click node_api_sessions "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/sessions.py"
click node_api_fetch "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/fetch.py"
click node_api_extract "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/extract.py"
click node_api_scraper "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/scraper.py"
click node_api_taxonomy "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/taxonomy.py"
click node_api_rules "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/rules.py"
click node_api_sessions_service "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/sessions.py"
click node_api_mcp "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/mcp.py"
click node_api_rulesets "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/rulesets.py"
click node_api_purchases "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/purchases.py"
click node_purchase_service "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/purchases.py"
click node_api_accounts "https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/account.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_web_prefix,node_web_session,node_web_dashboard,node_web_confirm,node_web_api,node_api_accounts toneBlue
class node_api_sessions,node_api_fetch,node_api_extract,node_api_scraper,node_api_taxonomy,node_api_rules,node_api_sessions_service,node_supabase toneAmber
class node_api_mcp,node_api_rulesets toneMint
class node_api_purchases,node_purchase_service toneRose
class node_shopper,node_brightdata,node_jev,node_agent,node_grok toneIndigo
```

## Components

### Shopper web

- [Prefix and session pages](https://github.com/ehewes/firealarm-budget/blob/main/apps/web/app/%5B...url%5D/page.tsx): `apps/web/app/[...url]/page.tsx`
- [Session view](https://github.com/ehewes/firealarm-budget/blob/main/apps/web/components/session-view.tsx): `apps/web/components/session-view.tsx`
- [Session history](https://github.com/ehewes/firealarm-budget/blob/main/apps/web/app/dashboard/page.tsx): `apps/web/app/dashboard/page.tsx`
- [Purchase confirmation](https://github.com/ehewes/firealarm-budget/blob/main/apps/web/app/confirm/%5Bid%5D/page.tsx): `apps/web/app/confirm/[id]/page.tsx`
- [API client](https://github.com/ehewes/firealarm-budget/blob/main/apps/web/lib/api.ts): `apps/web/lib/api.ts`
- [Account access](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/account.py): `apps/api/app/routers/account.py`

### Session processing

- [Session endpoints](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/sessions.py): `apps/api/app/routers/sessions.py`
- [Store fetching](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/fetch.py): `apps/api/app/services/fetch.py`
- [Product extraction](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/extract.py): `apps/api/app/services/extract.py`
- [Scraping coordination](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/scraper.py): `apps/api/app/services/scraper.py`
- [Category tree](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/taxonomy.py): `apps/api/app/services/taxonomy.py`
- [Rules and ranking](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/rules.py): `apps/api/app/services/rules.py`
- [Session service](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/sessions.py): `apps/api/app/services/sessions.py`

### Agent access

- [MCP access](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/mcp.py): `apps/api/app/routers/mcp.py`
- [Rules management](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/rulesets.py): `apps/api/app/routers/rulesets.py`

### Purchase approval

- [Purchase endpoints](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/routers/purchases.py): `apps/api/app/routers/purchases.py`
- [Purchase handling](https://github.com/ehewes/firealarm-budget/blob/main/apps/api/app/services/purchases.py): `apps/api/app/services/purchases.py`

### Other components

- **Shopper**
- **Bright Data**
- **Jev classification**
- **Supabase**
- **Connected agent**
- **Grok / Grok Bot**

## Connections

- Shopper → Prefix and session pages: prefixes link
- Prefix and session pages → API client: requests session
- API client → Session endpoints: calls API
- Session endpoints → Scraping coordination: starts scraping
- Scraping coordination → Store fetching: fetches page
- Store fetching → Bright Data: retrieves page
- Scraping coordination → Product extraction: extracts products
- Scraping coordination → Category tree: categorizes products
- Category tree → Jev classification: classifies
- Rules and ranking → Jev classification: ranks preferences
- Session endpoints → Session service: manages sessions
- Session service → Supabase: stores sessions
- Rules management → Supabase: stores rules
- API client → Rules management: manages rules
- API client → Account access: requests account
- Account access → Supabase: reads account data
- Session view → API client: loads session
- Session history → API client: loads history
- Connected agent → MCP access: requests session data
- MCP access → Session service: accesses sessions
- MCP access → Rules and ranking: requests filtered items
- Grok / Grok Bot → MCP access: connects over MCP
- Connected agent → Purchase endpoints: requests purchase
- Purchase endpoints → Purchase handling: creates intent
- Purchase handling → Supabase: stores purchase
- Shopper → Purchase confirmation: approves purchase
- Purchase confirmation → API client: submits approval
- API client → Purchase endpoints: confirms intent