How bluenot3/roam works
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 Backend server · App.tsx App UI · screens Screens · api.ts API client
Components 19
Frontend
React/Vite operator UI
- App UI · Operator dashboard for scans, browsing, export, and account actions
shot-app/src/App.tsx - Screens · Screen-level app flows for home, scan, gallery, history, analytics, export, templates, settings, login
shot-app/src/screens - Shared UI · Reusable interface pieces like sidebar, cards, toast, and upgrade modal
shot-app/src/components - Auth state · Application-wide authentication and session state
shot-app/src/contexts/AuthContext.tsx - API client · Frontend boundary for backend requests and job status calls
shot-app/src/lib/api.ts - Toast system · Centralized transient user notifications
shot-app/src/lib/toast.ts - Mock data · Local/demo dataset for rendering without live backend data
shot-app/src/data/mockData.ts
Backend
Node orchestration and capture pipeline
- Backend server · API gateway and orchestration entrypoint for capture, progress, and packaging
backend.mjs - Capture pipeline · Loads targets, traverses pages, captures screenshots and walkthrough video
backend.mjs - AI analysis · Generates page understanding and narration from captured content
backend.mjs - Artifact packager · Aggregates screenshots, video, sitemap data, narration, and ZIP output
backend.mjs
External services
Third-party APIs and browser runtime
- Playwright · Headless browser control used for capture and traversal
- Gemini · External model service for page analysis and narration
- Supabase · Cloud auth and storage boundary
- Stripe · Subscription and plan entitlement service
Dev tools
Build and local-run scripts
- Bundle build · Builds the frontend into distributable assets
build-frontend.mjs - Serve bundle · Serves the built app and integrated runtime locally
serve-bundle.mjs - Browser setup · Installs and provisions browser binaries for automation
setup-browser.mjs - Playwright install · Installs Playwright dependencies for the capture runtime
playwright-install.mjs
Connections 20
- 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