# bluenot3/roam architecture

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

- Interactive diagram: https://gitdiagram.com/bluenot3/roam
- Repository: https://github.com/bluenot3/roam

## Overview

1. **Overall shape**
   - This repo is split into a **Node.js backend** at the root and a **React/Vite frontend** in `shot-app/`.
   - The backend is the orchestration layer for website capture and export; the frontend is the operator UI for starting scans, browsing results, and managing account/plan state.

2. **Primary backend boundary**
   - `backend.mjs` is the central server entrypoint.
   - Its role is to expose API endpoints, coordinate browser automation, stream scan progress, and package outputs for download.
   - The backend is where the non-UI work happens: crawling, screenshot/video generation, AI narration, and archive creation.

3. **Browser automation and capture pipeline**
   - The backend depends on **Playwright** for headless browser control.
   - From the README, the capture flow includes loading a target URL, traversing the page, taking full-page screenshots, recording walkthrough video, and extracting links/site structure.
   - Supporting scripts like `setup-browser.mjs` and `playwright-install.mjs` suggest the repo treats browser provisioning as a first-class runtime concern.

4. **AI and external service integrations**
   - The system is designed to call **Google Gemini** for page analysis and narration generation.
   - The README also calls out **Supabase** for auth/storage and **Stripe** for billing, so the backend likely mediates those service boundaries rather than exposing them directly to the UI.
   - This creates a split between local capture work and cloud-backed account/entitlement handling.

5. **Frontend application boundary**
   - `shot-app/` is a separate SPA built with **React 19 + TypeScript + Vite**.
   - It contains the presentation layer only: user input, scan progress, browsing captured assets, and plan-related UI.
   - The frontend appears to be bundled separately and either served statically or embedded into a bundle flow via root scripts like `build-frontend.mjs` and `serve-bundle.mjs`.

6. **UI composition**
   - The frontend is organized around screen-level views in `src/screens/`, including `HomeScreen`, `ScanScreen`, `GalleryScreen`, `HistoryScreen`, `AnalyticsScreen`, `ExportScreen`, `TemplatesScreen`, `SettingsScreen`, and `LoginScreen`.
   - Shared UI pieces live in `src/components/`, such as `Sidebar`, `ScreenshotCard`, `ToastContainer`, and `UpgradeModal`.
   - This suggests a dashboard-style app with navigation, result browsing, notifications, and upsell flows.

7. **Frontend state and service layers**
   - `src/contexts/AuthContext.tsx` provides app-wide authentication state.
   - `src/lib/api.ts` is the client boundary to the backend API.
   - `src/lib/toast.ts` centralizes user notifications, keeping transient UI feedback out of screen components.

8. **Scan lifecycle and data flow**
   - The core flow is: **user enters a URL in the frontend → frontend calls the backend API → backend performs browser capture and analysis → backend streams progress/status back → frontend presents results and download actions**.
   - The README explicitly mentions an SSE-style progress stream and a packaged ZIP download, which implies long-running jobs are tracked asynchronously rather than blocking the UI.
   - The diagram should show the backend as a job processor with the frontend as a live progress consumer.

9. **Result artifacts**
   - The product outputs multiple artifact types: screenshots, video walkthroughs, sitemap/site-map JSON, narration, and a final ZIP bundle.
   - That means the backend is not just returning JSON; it produces files and aggregates them into a distributable package.
   - The frontend’s gallery/export screens likely consume those artifact references and provide browsing/download UX.

10. **Mocking and local development**
   - `src/data/mockData.ts` suggests the frontend can render without live backend data for development or demo purposes.
   - Root scripts such as `serve-dist.mjs`, `serve-bundle.mjs`, `build-frontend.mjs`, and `debug-links.mjs` indicate a developer workflow that includes building, serving, and validating the bundled UI plus backend behavior.
   - This is useful for diagramming a local-dev path distinct from production runtime.

11. **Deployment/runtime boundaries**
   - The repository targets **Node 20+** and uses a separate frontend build pipeline.
   - The README mentions **Railway** for production and **Docker Compose** for full-stack local runs, so the deployable unit is effectively the backend plus the built frontend assets.
   - The frontend itself can likely be deployed independently for static hosting, but the documented primary mode is the integrated stack.

12. **What to emphasize in an architecture diagram**
   - Show three main zones: **browser UI**, **application/API orchestration**, and **external services**.
   - The important arrows are: frontend to backend API, backend to Playwright/browser, backend to Gemini/Supabase/Stripe, and backend back to frontend via streamed progress and downloadable artifacts.
   - Keep the frontend screens as one subsystem and the capture/analysis/export pipeline as the other; most of the architectural complexity sits in that backend job pipeline.

Main entry points: [`backend.mjs`](https://github.com/bluenot3/roam/blob/main/backend.mjs) (Backend server), [`shot-app/src/App.tsx`](https://github.com/bluenot3/roam/blob/main/shot-app/src/App.tsx) (App UI), [`shot-app/src/screens`](https://github.com/bluenot3/roam/tree/main/shot-app/src/screens) (Screens), [`shot-app/src/lib/api.ts`](https://github.com/bluenot3/roam/blob/main/shot-app/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui["App UI<br/>React SPA<br/>[App.tsx]"]
  node_screens["Screens<br/>views"]
  node_components["Shared UI<br/>components"]
  node_auth["Auth state<br/>context<br/>[AuthContext.tsx]"]
  node_api["API client<br/>[api.ts]"]
  node_toast["Toast system<br/>ui state<br/>[toast.ts]"]
  node_mockdata["Mock data<br/>demo data<br/>[mockData.ts]"]
end

subgraph group_backend["Backend"]
  node_server["Backend server<br/>Node entrypoint<br/>[backend.mjs]"]
  node_capture["Capture pipeline<br/>crawl & record<br/>[backend.mjs]"]
  node_analysis["AI analysis<br/>Gemini workflow<br/>[backend.mjs]"]
  node_archive["Artifact packager<br/>export bundle<br/>[backend.mjs]"]
end

subgraph group_external["External services"]
  node_browser["Playwright<br/>browser automation"]
  node_gemini["Gemini<br/>AI service"]
  node_supabase["Supabase<br/>auth/storage"]
  node_stripe["Stripe<br/>billing"]
end

subgraph group_dev["Dev tools"]
  node_bundle["Bundle build<br/>frontend build<br/>[build-frontend.mjs]"]
  node_servebundle["Serve bundle<br/>local server<br/>[serve-bundle.mjs]"]
  node_playwrightsetup["Browser setup<br/>runtime setup<br/>[setup-browser.mjs]"]
  node_playwrightinstall["Playwright install<br/>installer"]
end

node_ui -->|"renders"| node_screens
node_ui -->|"uses"| node_components
node_ui -->|"reads auth"| node_auth
node_screens -->|"calls"| node_api
node_screens -->|"notifies"| node_toast
node_api -->|"requests"| node_server
node_ui -.->|"fallbacks"| node_mockdata
node_server -->|"orchestrates"| node_capture
node_server -->|"runs"| node_analysis
node_server -->|"packages"| node_archive
node_capture -->|"drives"| node_browser
node_analysis -->|"calls"| node_gemini
node_server -->|"auth/storage"| node_supabase
node_server -->|"billing"| node_stripe
node_archive -->|"returns artifacts"| node_server
node_server -->|"streams progress"| node_api
node_bundle -->|"builds"| node_ui
node_servebundle -->|"serves"| node_bundle
node_playwrightsetup -->|"provisions"| node_browser
node_playwrightinstall -->|"installs"| node_browser

click node_ui "https://github.com/bluenot3/roam/blob/main/shot-app/src/App.tsx"
click node_screens "https://github.com/bluenot3/roam/tree/main/shot-app/src/screens"
click node_components "https://github.com/bluenot3/roam/tree/main/shot-app/src/components"
click node_auth "https://github.com/bluenot3/roam/blob/main/shot-app/src/contexts/AuthContext.tsx"
click node_api "https://github.com/bluenot3/roam/blob/main/shot-app/src/lib/api.ts"
click node_toast "https://github.com/bluenot3/roam/blob/main/shot-app/src/lib/toast.ts"
click node_mockdata "https://github.com/bluenot3/roam/blob/main/shot-app/src/data/mockData.ts"
click node_server "https://github.com/bluenot3/roam/blob/main/backend.mjs"
click node_capture "https://github.com/bluenot3/roam/blob/main/backend.mjs"
click node_analysis "https://github.com/bluenot3/roam/blob/main/backend.mjs"
click node_archive "https://github.com/bluenot3/roam/blob/main/backend.mjs"
click node_bundle "https://github.com/bluenot3/roam/blob/main/build-frontend.mjs"
click node_servebundle "https://github.com/bluenot3/roam/blob/main/serve-bundle.mjs"
click node_playwrightsetup "https://github.com/bluenot3/roam/blob/main/setup-browser.mjs"
click node_playwrightinstall "https://github.com/bluenot3/roam/blob/main/playwright-install.mjs"

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_ui,node_screens,node_components,node_auth,node_api,node_toast,node_mockdata toneBlue
class node_server,node_capture,node_analysis,node_archive toneAmber
class node_browser,node_gemini,node_supabase,node_stripe toneMint
class node_bundle,node_servebundle,node_playwrightsetup,node_playwrightinstall toneRose
```

## Components

### Frontend

React/Vite operator UI

- [App UI](https://github.com/bluenot3/roam/blob/main/shot-app/src/App.tsx): React SPA · Operator dashboard for scans, browsing, export, and account actions · `shot-app/src/App.tsx`
- [Screens](https://github.com/bluenot3/roam/tree/main/shot-app/src/screens): views · Screen-level app flows for home, scan, gallery, history, analytics, export, templates, settings, login · `shot-app/src/screens`
- [Shared UI](https://github.com/bluenot3/roam/tree/main/shot-app/src/components): components · Reusable interface pieces like sidebar, cards, toast, and upgrade modal · `shot-app/src/components`
- [Auth state](https://github.com/bluenot3/roam/blob/main/shot-app/src/contexts/AuthContext.tsx): context · Application-wide authentication and session state · `shot-app/src/contexts/AuthContext.tsx`
- [API client](https://github.com/bluenot3/roam/blob/main/shot-app/src/lib/api.ts): client · Frontend boundary for backend requests and job status calls · `shot-app/src/lib/api.ts`
- [Toast system](https://github.com/bluenot3/roam/blob/main/shot-app/src/lib/toast.ts): ui state · Centralized transient user notifications · `shot-app/src/lib/toast.ts`
- [Mock data](https://github.com/bluenot3/roam/blob/main/shot-app/src/data/mockData.ts): demo data · Local/demo dataset for rendering without live backend data · `shot-app/src/data/mockData.ts`

### Backend

Node orchestration and capture pipeline

- [Backend server](https://github.com/bluenot3/roam/blob/main/backend.mjs): Node entrypoint · API gateway and orchestration entrypoint for capture, progress, and packaging · `backend.mjs`
- [Capture pipeline](https://github.com/bluenot3/roam/blob/main/backend.mjs): crawl & record · Loads targets, traverses pages, captures screenshots and walkthrough video · `backend.mjs`
- [AI analysis](https://github.com/bluenot3/roam/blob/main/backend.mjs): Gemini workflow · Generates page understanding and narration from captured content · `backend.mjs`
- [Artifact packager](https://github.com/bluenot3/roam/blob/main/backend.mjs): export bundle · Aggregates screenshots, video, sitemap data, narration, and ZIP output · `backend.mjs`

### External services

Third-party APIs and browser runtime

- **Playwright**: browser automation · Headless browser control used for capture and traversal
- **Gemini**: AI service · External model service for page analysis and narration
- **Supabase**: auth/storage · Cloud auth and storage boundary
- **Stripe**: billing · Subscription and plan entitlement service

### Dev tools

Build and local-run scripts

- [Bundle build](https://github.com/bluenot3/roam/blob/main/build-frontend.mjs): frontend build · Builds the frontend into distributable assets · `build-frontend.mjs`
- [Serve bundle](https://github.com/bluenot3/roam/blob/main/serve-bundle.mjs): local server · Serves the built app and integrated runtime locally · `serve-bundle.mjs`
- [Browser setup](https://github.com/bluenot3/roam/blob/main/setup-browser.mjs): runtime setup · Installs and provisions browser binaries for automation · `setup-browser.mjs`
- [Playwright install](https://github.com/bluenot3/roam/blob/main/playwright-install.mjs): installer · Installs Playwright dependencies for the capture runtime · `playwright-install.mjs`

## Connections

- App UI → Screens: renders · Main app composes screen-level flows
- App UI → Shared UI: uses · Shared interface pieces support the dashboard shell
- App UI → Auth state: reads auth · App-wide session and login state
- Screens → API client: calls · Screens start scans, fetch results, and trigger exports
- Screens → Toast system: notifies · Screens emit user feedback through the central toast system
- API client → Backend server: requests · Frontend talks to backend endpoints and job streams
- App UI → Mock data: fallbacks · Demo/local rendering can use static data
- Backend server → Capture pipeline: orchestrates · Backend coordinates the capture job lifecycle
- Backend server → AI analysis: runs · Backend invokes AI-based understanding and narration
- Backend server → Artifact packager: packages · Backend assembles downloadable output bundles
- Capture pipeline → Playwright: drives · Headless browsing performs traversal and screenshot/video capture
- AI analysis → Gemini: calls · Model service is used for content analysis and narration
- Backend server → Supabase: auth/storage · Backend mediates account state and persisted assets
- Backend server → Stripe: billing · Backend mediates plan and entitlement checks
- Artifact packager → Backend server: returns artifacts · Generated files and ZIP exports flow back to the API layer
- Backend server → API client: streams progress · Long-running scans report status back to the UI
- Bundle build → App UI: builds · Frontend sources are compiled into deployable assets
- Serve bundle → Bundle build: serves · Local runtime serves the built frontend bundle
- Browser setup → Playwright: provisions · Browser binaries and runtime setup for automation
- Playwright install → Playwright: installs · Playwright dependency installation supports capture runs
