# carlossg/arco architecture

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

- Interactive diagram: https://gitdiagram.com/carlossg/arco
- Repository: https://github.com/carlossg/arco

## Overview

Arco is an AEM Edge Delivery Services espresso-brand site with a personalized, AI-generated-page workflow. Browsing builds a session interest profile; a For You action or natural-language query sends context to the recommender, which generates and streams a page. The default deployment runs the shared Worker handler on Google Cloud with Vertex Gemini and Firestore; optional branches include DA persistence, admin/evaluation tools, and the retained Cloudflare Worker. The graph reflects documented flows and shown imports/calls; unsampled subsystems are included at directory level where the README identifies their capabilities.

Main entry points: [`workers/recommender/src/index.js`](https://github.com/carlossg/arco/blob/main/workers/recommender/src/index.js) (Shared request handler), [`blocks/header/header.js`](https://github.com/carlossg/arco/blob/main/blocks/header/header.js) (Navigation and search), [`services/recommender/src/server.js`](https://github.com/carlossg/arco/blob/main/services/recommender/src/server.js) (Cloud Run service), [`workers/recommender/src/pipeline/executor.js`](https://github.com/carlossg/arco/blob/main/workers/recommender/src/pipeline/executor.js) (Generation pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_site["Site experience"]
  node_site["AEM site<br/>[scripts.js]"]
  node_navigation["Navigation and search<br/>[header.js]"]
  node_session["Browsing profile<br/>[session-context.js]"]
  node_prefetch["For You prefetch"]
  node_speculation["Speculative fetch"]
  node_stream["Page streaming"]
  node_experience["Generated page UI<br/>[keep-exploring.js]"]
  node_personalization["Quiz assembly<br/>[assembly-engine.js]"]
end

subgraph group_generation["Generation runtime"]
  node_worker["Shared request handler<br/>[index.js]"]
  node_pipeline["Generation pipeline<br/>[executor.js]"]
  node_llm["LLM generation<br/>[llm-generate.js]"]
  node_providers["Model providers<br/>[index.js]"]
  node_rag["Hybrid content retrieval<br/>[rag-content.js]"]
  node_cloudflare["Cloudflare alternative<br/>[index.js]"]
end

subgraph group_google["Google backend"]
  node_google_service["Cloud Run service<br/>[server.js]"]
  node_google_ai["Vertex Gemini<br/>[vertex.js]"]
  node_firestore[("Firestore storage<br/>[storage.js]")]
  node_vector[("Vector search<br/>[vector-index.js]")]
  node_tasks["Evaluation queue<br/>[tasks.js]"]
end

subgraph group_operations["Operations"]
  node_admin["Admin SPA<br/>[admin.js]"]
  node_evaluation["Evaluation tools<br/>[evaluations.js]"]
  node_analytics["Analytics and feedback<br/>[analytics.js]"]
  node_persistence["DA persistence<br/>[da-persist.js]"]
end

node_visitor(("Visitor"))

node_visitor -->|"browses and queries"| node_navigation
node_navigation -->|"records signals"| node_session
node_navigation -->|"requests For You"| node_prefetch
node_prefetch -->|"reads context"| node_session
node_navigation -->|"attaches prefetch"| node_speculation
node_speculation -->|"posts generation request"| node_worker
node_navigation -->|"submits query"| node_google_service
node_google_service -->|"dispatches request"| node_worker
node_worker -->|"streams generated page"| node_experience
node_experience -->|"renders streamed response"| node_stream
node_worker -.->|"runs generation flow"| node_pipeline
node_pipeline -.->|"runs generation step"| node_llm
node_llm -->|"selects provider"| node_providers
node_llm -->|"uses Vertex Gemini"| node_google_ai
node_pipeline -->|"retrieves content"| node_rag
node_rag -->|"uses vector search"| node_vector
node_worker -->|"persists generations"| node_firestore
node_google_service -->|"routes evaluation requests"| node_evaluation
node_evaluation -.->|"queues evaluation work"| node_tasks
node_worker -.->|"records events"| node_analytics
node_worker -->|"saves pages optionally"| node_persistence
node_visitor -->|"manages recommender"| node_admin
node_admin -.->|"configures and inspects"| node_google_service
node_site -.->|"composes persona content"| node_personalization
node_worker -.->|"supports alternative deployment"| node_cloudflare

click node_site "https://github.com/carlossg/arco/blob/main/scripts/scripts.js"
click node_navigation "https://github.com/carlossg/arco/blob/main/blocks/header/header.js"
click node_session "https://github.com/carlossg/arco/blob/main/scripts/session-context.js"
click node_prefetch "https://github.com/carlossg/arco/blob/main/scripts/for-you-prefetch.js"
click node_speculation "https://github.com/carlossg/arco/blob/main/scripts/speculative-engine.js"
click node_stream "https://github.com/carlossg/arco/blob/main/scripts/recommender-stream.js"
click node_experience "https://github.com/carlossg/arco/blob/main/blocks/keep-exploring/keep-exploring.js"
click node_admin "https://github.com/carlossg/arco/blob/main/blocks/admin/admin.js"
click node_personalization "https://github.com/carlossg/arco/blob/main/personalization/assembly-engine.js"
click node_google_service "https://github.com/carlossg/arco/blob/main/services/recommender/src/server.js"
click node_worker "https://github.com/carlossg/arco/blob/main/workers/recommender/src/index.js"
click node_pipeline "https://github.com/carlossg/arco/blob/main/workers/recommender/src/pipeline/executor.js"
click node_llm "https://github.com/carlossg/arco/blob/main/workers/recommender/src/pipeline/steps/llm-generate.js"
click node_providers "https://github.com/carlossg/arco/blob/main/workers/recommender/src/providers/index.js"
click node_rag "https://github.com/carlossg/arco/blob/main/workers/recommender/src/pipeline/steps/rag-content.js"
click node_google_ai "https://github.com/carlossg/arco/blob/main/services/recommender/src/vertex.js"
click node_firestore "https://github.com/carlossg/arco/blob/main/services/recommender/src/storage.js"
click node_vector "https://github.com/carlossg/arco/blob/main/services/recommender/src/vector-index.js"
click node_tasks "https://github.com/carlossg/arco/blob/main/services/recommender/src/tasks.js"
click node_evaluation "https://github.com/carlossg/arco/blob/main/services/recommender/src/evaluations.js"
click node_analytics "https://github.com/carlossg/arco/blob/main/workers/recommender/src/analytics.js"
click node_persistence "https://github.com/carlossg/arco/blob/main/workers/recommender/src/da-persist.js"
click node_cloudflare "https://github.com/carlossg/arco/blob/main/workers/recommender/src/providers/index.js"

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_site,node_navigation,node_session,node_prefetch,node_speculation,node_stream,node_experience,node_personalization toneBlue
class node_worker,node_pipeline,node_llm,node_providers,node_rag,node_cloudflare toneAmber
class node_google_service,node_google_ai,node_firestore,node_vector,node_tasks toneMint
class node_admin,node_evaluation,node_analytics,node_persistence toneRose
class node_visitor toneIndigo
```

## Components

### Site experience

- [AEM site](https://github.com/carlossg/arco/blob/main/scripts/scripts.js): `scripts/scripts.js`
- [Navigation and search](https://github.com/carlossg/arco/blob/main/blocks/header/header.js): `blocks/header/header.js`
- [Browsing profile](https://github.com/carlossg/arco/blob/main/scripts/session-context.js): `scripts/session-context.js`
- [For You prefetch](https://github.com/carlossg/arco/blob/main/scripts/for-you-prefetch.js): `scripts/for-you-prefetch.js`
- [Speculative fetch](https://github.com/carlossg/arco/blob/main/scripts/speculative-engine.js): `scripts/speculative-engine.js`
- [Page streaming](https://github.com/carlossg/arco/blob/main/scripts/recommender-stream.js): `scripts/recommender-stream.js`
- [Generated page UI](https://github.com/carlossg/arco/blob/main/blocks/keep-exploring/keep-exploring.js): `blocks/keep-exploring/keep-exploring.js`
- [Quiz assembly](https://github.com/carlossg/arco/blob/main/personalization/assembly-engine.js): `personalization/assembly-engine.js`

### Generation runtime

- [Shared request handler](https://github.com/carlossg/arco/blob/main/workers/recommender/src/index.js): `workers/recommender/src/index.js`
- [Generation pipeline](https://github.com/carlossg/arco/blob/main/workers/recommender/src/pipeline/executor.js): `workers/recommender/src/pipeline/executor.js`
- [LLM generation](https://github.com/carlossg/arco/blob/main/workers/recommender/src/pipeline/steps/llm-generate.js): `workers/recommender/src/pipeline/steps/llm-generate.js`
- [Model providers](https://github.com/carlossg/arco/blob/main/workers/recommender/src/providers/index.js): `workers/recommender/src/providers/index.js`
- [Hybrid content retrieval](https://github.com/carlossg/arco/blob/main/workers/recommender/src/pipeline/steps/rag-content.js): `workers/recommender/src/pipeline/steps/rag-content.js`
- [Cloudflare alternative](https://github.com/carlossg/arco/blob/main/workers/recommender/src/providers/index.js): `workers/recommender/src/providers/index.js`

### Google backend

- [Cloud Run service](https://github.com/carlossg/arco/blob/main/services/recommender/src/server.js): `services/recommender/src/server.js`
- [Vertex Gemini](https://github.com/carlossg/arco/blob/main/services/recommender/src/vertex.js): `services/recommender/src/vertex.js`
- [Firestore storage](https://github.com/carlossg/arco/blob/main/services/recommender/src/storage.js): `services/recommender/src/storage.js`
- [Vector search](https://github.com/carlossg/arco/blob/main/services/recommender/src/vector-index.js): `services/recommender/src/vector-index.js`
- [Evaluation queue](https://github.com/carlossg/arco/blob/main/services/recommender/src/tasks.js): `services/recommender/src/tasks.js`

### Operations

- [Admin SPA](https://github.com/carlossg/arco/blob/main/blocks/admin/admin.js): `blocks/admin/admin.js`
- [Evaluation tools](https://github.com/carlossg/arco/blob/main/services/recommender/src/evaluations.js): `services/recommender/src/evaluations.js`
- [Analytics and feedback](https://github.com/carlossg/arco/blob/main/workers/recommender/src/analytics.js): `workers/recommender/src/analytics.js`
- [DA persistence](https://github.com/carlossg/arco/blob/main/workers/recommender/src/da-persist.js): `workers/recommender/src/da-persist.js`

### Other components

- **Visitor**

## Connections

- Visitor → Navigation and search: browses and queries
- Navigation and search → Browsing profile: records signals (evidence: `blocks/header/header.js`)
- Navigation and search → For You prefetch: requests For You (evidence: `blocks/header/header.js`)
- For You prefetch → Browsing profile: reads context (evidence: `blocks/header/header.js`)
- Navigation and search → Speculative fetch: attaches prefetch (evidence: `blocks/header/header.js`)
- Speculative fetch → Shared request handler: posts generation request (evidence: `scripts/speculative-engine.js`)
- Navigation and search → Cloud Run service: submits query
- Cloud Run service → Shared request handler: dispatches request (evidence: `services/recommender/src/server.js`)
- Shared request handler → Generated page UI: streams generated page
- Generated page UI → Page streaming: renders streamed response (evidence: `blocks/keep-exploring/keep-exploring.js`)
- Shared request handler → Generation pipeline: runs generation flow
- Generation pipeline → LLM generation: runs generation step
- LLM generation → Model providers: selects provider (evidence: `workers/recommender/src/pipeline/steps/llm-generate.js`)
- LLM generation → Vertex Gemini: uses Vertex Gemini
- Generation pipeline → Hybrid content retrieval: retrieves content
- Hybrid content retrieval → Vector search: uses vector search
- Shared request handler → Firestore storage: persists generations (evidence: `services/recommender/src/server.js`)
- Cloud Run service → Evaluation tools: routes evaluation requests (evidence: `services/recommender/src/server.js`)
- Evaluation tools → Evaluation queue: queues evaluation work
- Shared request handler → Analytics and feedback: records events
- Shared request handler → DA persistence: saves pages optionally
- Visitor → Admin SPA: manages recommender
- Admin SPA → Cloud Run service: configures and inspects
- AEM site → Quiz assembly: composes persona content
- Shared request handler → Cloudflare alternative: supports alternative deployment
