> ## Documentation Index
> Fetch the complete documentation index at: https://helloluciallc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

<Note>
  Lucia converts external signals into structured decisions.
</Note>

## Flow

<div className="hl-flow"><span>External</span><span>Ingestion</span><span>Normalization</span><span>Intelligence</span><span>Workspace Context</span><span>Execution</span><span>Saved Work</span><span>UI</span></div>

Guest-facing flow:

<div className="hl-flow-v"><span>guest conversation</span><span>identity orientation / claim collection</span><span>signed operational\_signal v0</span><span>Engine guest signal normalization</span><span>Admin Signal Stream review/link surface</span><span>Focus Ops context when safe</span></div>

## Temporal Spine

Calendar is Lucia's temporal spine.

Lucia is situationally aware because the system is grounded in:

```text theme={"dark"}
arrivals
departures
stay windows
booking identity
```

## Current Live-Dev Product Flow

```text theme={"dark"}
Calendar / booking spine
→ Booking Pulse
→ Signal Stream
→ Lucia Workspace / Focus with Lucia
→ Resolver Matrix
→ Dynamic Action Workspace for action/save work

Calendar booking click
→ Full Booking Page for record/review

Eval Labs
→ behavioral proof and regression protection

Guest-Facing Lucia
→ public concierge, identity/linkage discipline, and guest-to-operator signal bridge

Payment Truth Foundation
→ policy shape, booking timing, Stripe movement truth, durable ledger, LIEA attention judgment, and Admin read-only rendering
```

Core doctrine:

```text theme={"dark"}
Calendar = root operational reality.
Lucia Workspace = context-aware reasoning partner beside the operator.
Infinite real-world property tasks.
Finite beautiful action workspaces.
Lucia routes the human to the right one.
Lucia Workspace + DAW = cockpit.
Full Booking Page = record/review surface.
Guest-facing Lucia = front-of-house concierge.
Guest-to-Operator Bridge = structured privacy-safe operational signal path.
Eval Labs = proof/regression system.
Payment truth separates owed policy, Stripe movement, durable storage, attention judgment, and Admin rendering.
```

This is Development/live-dev runtime truth, not production readiness.

See [04 - Lucia Workspace OS Milestone](/lucia/system-architecture/lucia-workspace-os-milestone) for the current Workspace OS milestone.

See [00 - START HERE - Guest-Facing Lucia](/lucia/guest-facing-lucia/start-here-guest-facing-lucia) for the current guest-facing Lucia milestone.

See [Lucia Payment Truth Foundation](/lucia/system-architecture/lucia-payment-truth-foundation) for the current payment truth foundation.

## Stack

Twilio, Postmark, Bunny, Engine, Admin UI, Guest Agent, Resend, Supabase, Stripe sandbox, GPT-5.6 Sol, OpenAI Responses API

## Independent Model Configuration Boundaries

| Runtime surface                         | Current model | Configuration and evidence boundary                                                                                               |
| --------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Lucia Engine Development                | `gpt-5.6-sol` | Engine-owned configuration with same-response runtime/model provenance from `/admin/operator-focus`                               |
| Lucia Guest Agent production deployment | `gpt-5.6-sol` | Guest-owned `VV_AI_MODEL` production override and `gpt-5.6-sol` source fallback, independently live-verified against the provider |

The matching model name does not create inheritance between the two surfaces. Each owns its configuration, deployment, and runtime verification. Both use the OpenAI Responses API; Guest Agent embeddings remain `text-embedding-3-small`.

The Guest Agent model-only upgrade preserved prompts, verification flow, routing, schemas, and the core SSE events `start`, `token`, `cta`, `meta`, and `done`. Guest Agent does not expose or persist the Engine's `/admin/operator-focus` provenance contract.

## Focus Ops Runtime Evidence Flow

<div className="hl-flow-v"><span>Eval Labs production</span><span>Development /admin/operator-focus</span><span>stable ok / data / meta response</span><span>meta.runtime + meta.model\_runtime</span><span>owner verification + per-run provenance</span></div>

The Engine keeps operational output in `data` and exposes evidence in `meta`; provenance does not replace or reshape the stable response contract. Runtime identity reports the Engine environment and commit. Model-runtime evidence reports the configured model, provider-resolved model, model-invoked state, deterministic-path state, fallback state, and task outcomes.

This architecture records model invocation versus no-attempt deterministic execution, proves provider-backed success through task evidence, and records fallback independently. Eval Labs persists captured evidence for new runs and explicitly reports that provenance was not captured for historical runs that lack it.

## Payment Truth Boundary

Current payment truth architecture:

<div className="hl-flow-v"><span>Property policy truth</span><span>calendar/booking temporal truth</span><span>Stripe movement truth</span><span>Lucia Core durable ledger</span><span>LIEA financial judgment</span><span>Admin payment truth rendering</span></div>

Implemented Development truth:

```text theme={"dark"}
Durable Stripe movement truth is implemented.
Lucia Core Supabase durable ledger is configured and tested in Development.
LIEA consumes Stripe financial truth for payment attention suppression.
Admin renders Engine payment truth read-only.
Property Payment Policy v0 is visible in Admin as draft/no-persistence baseline only.
```

Not yet implemented:

```text theme={"dark"}
Durable Engine-owned property payment policy truth.
Signal Stream -> LIEA wiring.
Admin payment writes or payment creation/refund/mark-paid UI.
Full policy-aware due/overdue/partial/pending judgment.
```

## Guest Verification Boundary

Current guest verification architecture:

```text theme={"dark"}
Candidate Booking Lookup Helper v0
Magic Link Verification Token + Session State v0
Magic Link Verification endpoints v0
Resend-backed verification email delivery
```

Verification emails go only to the booking email already on file. Guest-entered email is never trusted as the destination.

Guest verification proves linkage. It does not grant unrestricted mutation access.

## Environments

dev active, stage validation

## Build Identity

Current live-dev build identity:

```text theme={"dark"}
The live-dev topbar displays Admin and Engine build identity.
Admin build identity is injected at Admin build time.
Engine build identity is fetched from the Engine root endpoint.
```

The tag is runtime evidence for the currently deployed Admin/Engine pair. Canon may document the identity mechanism, but must not hardcode volatile commit hashes as system truth.