Aurelia docs
Technical architecture
Aurelia's current architecture is intentionally compact: a Next.js app with a client-side concierge shell, server-side chat routes, generated hotel knowledge files, embeddings-backed retrieval, and explicit host analytics hooks.
CTOs and engineers reviewing deployment shape, runtime boundaries, and implementation realism.
8 min
Map the actual runtime layers across the host website, concierge shell, server routes, retrieval, and analytics.
System layers
Keep the host contract thin and the orchestration layers explicit.
Aurelia is best understood as a product layer that spans the website, the concierge runtime, the chat orchestration route, and the hotel knowledge stack. The current prototype keeps those layers narrow enough that a pilot does not require a sprawling distributed system.
| Layer | Runs where | Current responsibility |
|---|---|---|
| Host website | Browser and brand-owned product code | Owns route placement, page context, launcher UI, and analytics hooks |
| Concierge shell | React client components | Owns panel state, launch behavior, prompt lifecycle, and route-aware context updates |
| Chat orchestration | Next.js server route | Receives prompts, classifies the turn, retrieves hotel evidence, and shapes the grounded response |
| Knowledge and retrieval | Generated JSON plus embeddings index | Stores normalized hotel records and supports lexical plus semantic hotel matching |
| Analytics and review | Host analytics plus operational review | Captures launches, prompts, evidence use, answer outcomes, and rollout learnings |
For a first production rollout, this architecture is deliberately compact. The value comes from grounded context and product placement, not from introducing more infrastructure than the pilot can justify.
Browser and server responsibilities
Keep guest context and UI in the browser; keep retrieval and model access on the server.
- The browser owns launch points, panel state, page context, and the visual experience across homepage, destination, hotel, and booking routes.
- The server owns prompt interpretation, hotel retrieval, response orchestration, and model access so secrets stay server-side.
- The host page passes only the context Aurelia needs right now, such as page type, visible hotels, active hotel, and prompt suggestions.
- The returned payload is product-shaped: grounded answer text, widgets, actions, suggestions, and evidence metadata rather than a raw model string alone.
Representative runtime flow in the current prototype.
Host page or product UI
-> PreferredConciergeProvider / ConciergeLauncher
-> /api/chat
-> searchPreferredHotels(...) + hotel knowledge lookup
-> OpenAI response orchestration
-> grounded reply + widgets + actionsCurrent repo surfaces
The architecture is already visible in the codebase rather than hidden behind a future platform story.
| Surface | Current file | Why it matters |
|---|---|---|
| Host integration | src/components/concierge-embed.tsx | Exports the provider, launcher, and hook that website code can mount today |
| Client shell | src/components/concierge-shell.tsx | Maintains panel behavior, host API wiring, and route-aware context on the client |
| Guest answer route | src/app/api/chat/route.ts | Handles prompt classification, retrieval, and grounded answer generation on the server |
| Hotel knowledge layer | src/lib/preferred-hotel-knowledge.ts | Loads normalized hotel records and embeddings-backed search helpers |
| Knowledge build scripts | scripts/ingest-preferred-hotels.mjs and scripts/embed-preferred-hotels.mjs | Generate the hotel snapshot and embedding index used by the retrieval layer |
Deployment posture
Aurelia can launch as one observable Next.js product surface before any deeper platform split is necessary.
- The current prototype runs as a single Next.js App Router application serving both the website and the server routes it needs.
- OPENAI_API_KEY remains on the server; the browser receives only the structured response payload.
- Hotel knowledge and embeddings are generated ahead of time, which keeps retrieval fast and makes the data surface auditable.
- The host analytics layer can subscribe to events through the exposed onEvent hook without owning any model or retrieval logic itself.
- A pilot can stay in this shape until scale, org boundaries, or compliance needs justify splitting services more aggressively.
Aurelia does not need a large platform program to start credibly. It can launch as a contained product layer with clear runtime boundaries, explicit data inputs, and measurable operational hooks.