How carlossg/arco works
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: index.js Shared request handler · header.js Navigation and search · server.js Cloud Run service · executor.js Generation pipeline
Components 24
Site experience
- AEM site
scripts/scripts.js - Navigation and search
blocks/header/header.js - Browsing profile
scripts/session-context.js - For You prefetch
scripts/for-you-prefetch.js - Speculative fetch
scripts/speculative-engine.js - Page streaming
scripts/recommender-stream.js - Generated page UI
blocks/keep-exploring/keep-exploring.js - Quiz assembly
personalization/assembly-engine.js
Generation runtime
- Shared request handler
workers/recommender/src/index.js - Generation pipeline
workers/recommender/src/pipeline/executor.js - LLM generation
workers/recommender/src/pipeline/steps/llm-generate.js - Model providers
workers/recommender/src/providers/index.js - Hybrid content retrieval
workers/recommender/src/pipeline/steps/rag-content.js - Cloudflare alternative
workers/recommender/src/providers/index.js
Google backend
- Cloud Run service
services/recommender/src/server.js - Vertex Gemini
services/recommender/src/vertex.js - Firestore storage
services/recommender/src/storage.js - Vector search
services/recommender/src/vector-index.js - Evaluation queue
services/recommender/src/tasks.js
Operations
- Admin SPA
blocks/admin/admin.js - Evaluation tools
services/recommender/src/evaluations.js - Analytics and feedback
workers/recommender/src/analytics.js - DA persistence
workers/recommender/src/da-persist.js
Other components
- Visitor
Connections 25
- Visitor → Navigation and search: browses and queries
- Navigation and search → Browsing profile: records signals
blocks/header/header.js - Navigation and search → For You prefetch: requests For You
blocks/header/header.js - For You prefetch → Browsing profile: reads context
blocks/header/header.js - Navigation and search → Speculative fetch: attaches prefetch
blocks/header/header.js - Speculative fetch → Shared request handler: posts generation request
scripts/speculative-engine.js - Navigation and search → Cloud Run service: submits query
- Cloud Run service → Shared request handler: dispatches request
services/recommender/src/server.js - Shared request handler → Generated page UI: streams generated page
- Generated page UI → Page streaming: renders streamed response
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
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
services/recommender/src/server.js - Cloud Run service → Evaluation tools: routes evaluation requests
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