# st4rk-7/riven architecture

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

- Interactive diagram: https://gitdiagram.com/st4rk-7/riven
- Repository: https://github.com/st4rk-7/riven

## Overview

Riven is a competitor-price and stock monitoring product for small retailers. A retailer signs in, adds a product, and the app discovers competitor offers; collection can also be triggered from Amazon pages via the Chrome extension or by the server crawler. Observations are extracted, matched to products, and recorded so the app can show match status and price history. The graph preserves the documented review and scheduling capabilities; unsampled subsystems are represented only where the tree or README supports them, so some links are documented rather than source-verified.

Main entry points: [`server/observations.ts`](https://github.com/st4rk-7/riven/blob/main/server/observations.ts) (Observation routes), [`web/riven-main.tsx`](https://github.com/st4rk-7/riven/blob/main/web/riven-main.tsx) (Retailer app), [`server/products.ts`](https://github.com/st4rk-7/riven/blob/main/server/products.ts) (Product routes), [`server/app.ts`](https://github.com/st4rk-7/riven/blob/main/server/app.ts) (Fastify API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Retailer apps"]
  node_app["Retailer app<br/>[riven-main.tsx]"]
  node_product_views["Product screens"]
  node_catalog["Catalog and history view<br/>[data.ts]"]
  node_extension["Chrome extension<br/>[background.ts]"]
end

subgraph group_server["API and identity"]
  node_api["Fastify API<br/>[app.ts]"]
  node_auth["Sign-in and identity<br/>[auth.ts]"]
  node_product_routes["Product routes<br/>[products.ts]"]
  node_observation_routes["Observation routes<br/>[observations.ts]"]
  node_discovery["Offer discovery<br/>[discovery.ts]"]
  node_matching["Product matching<br/>[matching.ts]"]
end

subgraph group_collection["Offer collection"]
  node_crawler["Scheduled crawler<br/>[crawler.ts]"]
  node_amazon_collector["Amazon collector"]
  node_page_capture["Page capture and send<br/>[capture.ts]"]
  node_site_rules["Site rules<br/>[sites.ts]"]
  node_extractor["Offer extraction<br/>[extract.ts]"]
end

subgraph group_data["Product and observation data"]
  node_observation_save["Observation persistence"]
  node_postgres[("PostgreSQL")]
end

node_retailer(("Retailer"))
node_amazon["Amazon pages"]
node_external_auth["Better Auth"]

node_retailer -->|"uses"| node_app
node_app -->|"renders"| node_product_views
node_app -->|"builds catalog"| node_catalog
node_product_views -->|"reads offers"| node_catalog
node_app -.->|"requests data"| node_api
node_app -->|"requests page fetch"| node_extension
node_retailer -->|"shares viewed pages"| node_extension
node_extension -->|"captures pages"| node_amazon
node_extension -.->|"sends observations"| node_api
node_api -->|"registers routes"| node_auth
node_auth -->|"delegates sign-in"| node_external_auth
node_api -->|"registers routes"| node_product_routes
node_api -->|"registers routes"| node_observation_routes
node_product_routes -->|"uses matching"| node_matching
node_product_routes -->|"starts collection"| node_amazon_collector
node_product_routes -.->|"discovers offers"| node_discovery
node_observation_routes -->|"uses extraction"| node_extractor
node_observation_routes -->|"coordinates checks"| node_crawler
node_observation_routes -->|"requests discovery"| node_discovery
node_observation_routes -->|"saves observations"| node_observation_save
node_crawler -.->|"rechecks offers"| node_amazon_collector
node_amazon_collector -->|"extracts pages"| node_extractor
node_amazon_collector -->|"selects rules"| node_site_rules
node_extractor -->|"applies rules"| node_site_rules
node_amazon_collector -.->|"fetches pages"| node_amazon
node_observation_save -.->|"writes records"| node_postgres
node_product_routes -.->|"reads and writes"| node_postgres
node_observation_routes -.->|"reads records"| node_postgres
node_auth -->|"uses database"| node_postgres

click node_app "https://github.com/st4rk-7/riven/blob/main/web/riven-main.tsx"
click node_product_views "https://github.com/st4rk-7/riven/tree/main/web/screens"
click node_catalog "https://github.com/st4rk-7/riven/blob/main/web/data.ts"
click node_extension "https://github.com/st4rk-7/riven/blob/main/extension/src/background.ts"
click node_api "https://github.com/st4rk-7/riven/blob/main/server/app.ts"
click node_auth "https://github.com/st4rk-7/riven/blob/main/server/auth.ts"
click node_product_routes "https://github.com/st4rk-7/riven/blob/main/server/products.ts"
click node_observation_routes "https://github.com/st4rk-7/riven/blob/main/server/observations.ts"
click node_discovery "https://github.com/st4rk-7/riven/blob/main/server/discovery.ts"
click node_matching "https://github.com/st4rk-7/riven/blob/main/server/matching.ts"
click node_crawler "https://github.com/st4rk-7/riven/blob/main/server/crawler.ts"
click node_amazon_collector "https://github.com/st4rk-7/riven/blob/main/server/sources/amazon-collector.ts"
click node_page_capture "https://github.com/st4rk-7/riven/blob/main/extension/src/capture.ts"
click node_site_rules "https://github.com/st4rk-7/riven/blob/main/server/sources/sites.ts"
click node_extractor "https://github.com/st4rk-7/riven/blob/main/server/sources/extract.ts"
click node_observation_save "https://github.com/st4rk-7/riven/blob/main/server/save-observation.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_app,node_product_views,node_catalog,node_extension toneBlue
class node_api,node_auth,node_product_routes,node_observation_routes,node_discovery,node_matching toneAmber
class node_crawler,node_amazon_collector,node_page_capture,node_site_rules,node_extractor toneMint
class node_observation_save,node_postgres toneRose
class node_retailer,node_amazon,node_external_auth toneIndigo
```

## Components

### Retailer apps

- [Retailer app](https://github.com/st4rk-7/riven/blob/main/web/riven-main.tsx): `web/riven-main.tsx`
- [Product screens](https://github.com/st4rk-7/riven/tree/main/web/screens): `web/screens`
- [Catalog and history view](https://github.com/st4rk-7/riven/blob/main/web/data.ts): `web/data.ts`
- [Chrome extension](https://github.com/st4rk-7/riven/blob/main/extension/src/background.ts): `extension/src/background.ts`

### API and identity

- [Fastify API](https://github.com/st4rk-7/riven/blob/main/server/app.ts): `server/app.ts`
- [Sign-in and identity](https://github.com/st4rk-7/riven/blob/main/server/auth.ts): `server/auth.ts`
- [Product routes](https://github.com/st4rk-7/riven/blob/main/server/products.ts): `server/products.ts`
- [Observation routes](https://github.com/st4rk-7/riven/blob/main/server/observations.ts): `server/observations.ts`
- [Offer discovery](https://github.com/st4rk-7/riven/blob/main/server/discovery.ts): `server/discovery.ts`
- [Product matching](https://github.com/st4rk-7/riven/blob/main/server/matching.ts): `server/matching.ts`

### Offer collection

- [Scheduled crawler](https://github.com/st4rk-7/riven/blob/main/server/crawler.ts): `server/crawler.ts`
- [Amazon collector](https://github.com/st4rk-7/riven/blob/main/server/sources/amazon-collector.ts): `server/sources/amazon-collector.ts`
- [Page capture and send](https://github.com/st4rk-7/riven/blob/main/extension/src/capture.ts): `extension/src/capture.ts`
- [Site rules](https://github.com/st4rk-7/riven/blob/main/server/sources/sites.ts): `server/sources/sites.ts`
- [Offer extraction](https://github.com/st4rk-7/riven/blob/main/server/sources/extract.ts): `server/sources/extract.ts`

### Product and observation data

- [Observation persistence](https://github.com/st4rk-7/riven/blob/main/server/save-observation.ts): `server/save-observation.ts`
- **PostgreSQL**

### Other components

- **Retailer**
- **Amazon pages**
- **Better Auth**

## Connections

- Retailer → Retailer app: uses (evidence: `README.md`)
- Retailer app → Product screens: renders (evidence: `web/riven-main.tsx`)
- Retailer app → Catalog and history view: builds catalog (evidence: `web/riven-main.tsx`)
- Product screens → Catalog and history view: reads offers (evidence: `web/screens/Competitors.tsx`)
- Retailer app → Fastify API: requests data (evidence: `README.md`)
- Retailer app → Chrome extension: requests page fetch (evidence: `web/riven-main.tsx`)
- Retailer → Chrome extension: shares viewed pages (evidence: `README.md`)
- Chrome extension → Amazon pages: captures pages (evidence: `README.md`)
- Chrome extension → Fastify API: sends observations (evidence: `README.md`)
- Fastify API → Sign-in and identity: registers routes (evidence: `server/app.ts`)
- Sign-in and identity → Better Auth: delegates sign-in (evidence: `server/auth.ts`)
- Fastify API → Product routes: registers routes (evidence: `server/app.ts`)
- Fastify API → Observation routes: registers routes (evidence: `server/app.ts`)
- Product routes → Product matching: uses matching (evidence: `server/products.ts`)
- Product routes → Amazon collector: starts collection (evidence: `server/products.ts`)
- Product routes → Offer discovery: discovers offers
- Observation routes → Offer extraction: uses extraction (evidence: `server/observations.ts`)
- Observation routes → Scheduled crawler: coordinates checks (evidence: `server/observations.ts`)
- Observation routes → Offer discovery: requests discovery (evidence: `server/observations.ts`)
- Observation routes → Observation persistence: saves observations (evidence: `server/observations.ts`)
- Scheduled crawler → Amazon collector: rechecks offers
- Amazon collector → Offer extraction: extracts pages (evidence: `server/sources/amazon-collector.ts`)
- Amazon collector → Site rules: selects rules (evidence: `server/sources/amazon-collector.ts`)
- Offer extraction → Site rules: applies rules (evidence: `server/sources/extract.ts`)
- Amazon collector → Amazon pages: fetches pages
- Observation persistence → PostgreSQL: writes records
- Product routes → PostgreSQL: reads and writes
- Observation routes → PostgreSQL: reads records
- Sign-in and identity → PostgreSQL: uses database (evidence: `server/auth.ts`)
