# kacytran1122/keyo architecture

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

- Interactive diagram: https://gitdiagram.com/kacytran1122/keyo
- Repository: https://github.com/kacytran1122/keyo

## Overview

Keyo helps roommate groups evaluate NYC rental listings, coordinate approvals, and make guarded application-fee or deposit payments. Its main path is chat-based listing review, evidence and risk assessment, shared listing/vote state, then a payment proposal checked by an independent guard before XRPL submission. A web dashboard exposes listing evidence, activity, heat layers, and narrated tours. The source excerpts confirm the dashboard reads and guard checks, but do not show the agent’s full orchestration or evidence-ingestion calls; those links are therefore not expanded into a detailed sequence.

Main entry points: [`backend/apps/web/components/Dashboard.tsx`](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/components/Dashboard.tsx) (Map dashboard), [`backend/apps/guard/src/server.ts`](https://github.com/kacytran1122/keyo/blob/main/backend/apps/guard/src/server.ts) (Payment policy guard), [`backend/packages/db/src/index.ts`](https://github.com/kacytran1122/keyo/blob/main/backend/packages/db/src/index.ts) (Application database), [`backend/apps/web/app/api/state/route.ts`](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/state/route.ts) (Thread state API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_chat["Chat assistant"]
  node_agent["Chat agent<br/>[bot.ts]"]
  node_llm["Fact-based replies<br/>[llm.ts]"]
end

subgraph group_evidence["Rental evidence"]
  node_evidence_analysis["Evidence analysis<br/>[analyze.ts]"]
  node_evidence_sources["Public record sources<br/>[sources.ts]"]
  node_evidence_score["Listing risk score<br/>[score.ts]"]
end

subgraph group_web["Dashboard and tours"]
  node_dashboard["Map dashboard<br/>[Dashboard.tsx]"]
  node_state_api["Thread state API<br/>[route.ts]"]
  node_heat_api["Complaint heat API<br/>[route.ts]"]
  node_summer_api["Summer heat API<br/>[route.ts]"]
  node_tour_api["Tour script API<br/>[route.ts]"]
  node_voice_api["Tour voice API<br/>[route.ts]"]
  node_tour_lib["Tour scripts<br/>[tour.ts]"]
  node_voice_lib["Speech synthesis<br/>[elevenlabs.ts]"]
end

subgraph group_payments["Guarded payments"]
  node_guard_client["Guard API client<br/>[guard-client.ts]"]
  node_guard["Payment policy guard<br/>[server.ts]"]
  node_tx_verify["Transaction comparison<br/>[verify-tx.ts]"]
  node_shared_policy["Payment policy rules<br/>[policy.ts]"]
  node_ledger["XRPL transaction tools<br/>[index.ts]"]
end

subgraph group_data["Shared data"]
  node_db[("Application database<br/>[index.ts]")]
  node_heat_db["Complaint heat queries<br/>[heat.ts]"]
  node_pulse_db["Building pulse queries<br/>[pulse.ts]"]
end

node_roommates(("Roommates"))
node_xrpl[("XRPL network")]
node_elevenlabs(("ElevenLabs"))

node_roommates -->|"message listings"| node_agent
node_agent -->|"request payment"| node_guard_client
node_guard_client -->|"cosign or fund"| node_guard
node_guard -->|"load and update"| node_db
node_guard -->|"evaluate rules"| node_shared_policy
node_guard -->|"compare transaction"| node_tx_verify
node_guard -->|"sign and submit"| node_ledger
node_ledger -->|"submit transaction"| node_xrpl
node_dashboard -->|"fetch thread state"| node_state_api
node_state_api -->|"read thread data"| node_db
node_dashboard -->|"request heat layer"| node_heat_api
node_heat_api -->|"query hotspots"| node_heat_db
node_heat_db -->|"read heat data"| node_db
node_dashboard -->|"request summer layer"| node_summer_api
node_summer_api -->|"query temperature cells"| node_db
node_dashboard -->|"request tour script"| node_tour_api
node_tour_api -->|"load listing script"| node_tour_lib
node_dashboard -->|"request narration"| node_voice_api
node_voice_api -->|"load room text"| node_tour_lib
node_voice_api -->|"synthesize speech"| node_voice_lib
node_voice_lib -.->|"generate audio"| node_elevenlabs
node_state_api -->|"load building pulse"| node_pulse_db

click node_agent "https://github.com/kacytran1122/keyo/blob/main/backend/apps/agent/src/bot.ts"
click node_llm "https://github.com/kacytran1122/keyo/blob/main/backend/apps/agent/src/llm.ts"
click node_evidence_analysis "https://github.com/kacytran1122/keyo/blob/main/backend/packages/evidence/src/analyze.ts"
click node_evidence_sources "https://github.com/kacytran1122/keyo/blob/main/backend/packages/evidence/src/sources.ts"
click node_evidence_score "https://github.com/kacytran1122/keyo/blob/main/backend/packages/evidence/src/score.ts"
click node_dashboard "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/components/Dashboard.tsx"
click node_state_api "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/state/route.ts"
click node_heat_api "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/heat/route.ts"
click node_summer_api "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/summer-heat/route.ts"
click node_tour_api "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/tour/route.ts"
click node_voice_api "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/voice/route.ts"
click node_tour_lib "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/lib/tour.ts"
click node_voice_lib "https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/lib/elevenlabs.ts"
click node_db "https://github.com/kacytran1122/keyo/blob/main/backend/packages/db/src/index.ts"
click node_heat_db "https://github.com/kacytran1122/keyo/blob/main/backend/packages/db/src/heat.ts"
click node_pulse_db "https://github.com/kacytran1122/keyo/blob/main/backend/packages/db/src/pulse.ts"
click node_guard_client "https://github.com/kacytran1122/keyo/blob/main/backend/apps/agent/src/guard-client.ts"
click node_guard "https://github.com/kacytran1122/keyo/blob/main/backend/apps/guard/src/server.ts"
click node_tx_verify "https://github.com/kacytran1122/keyo/blob/main/backend/apps/guard/src/verify-tx.ts"
click node_shared_policy "https://github.com/kacytran1122/keyo/blob/main/backend/packages/shared/src/policy.ts"
click node_ledger "https://github.com/kacytran1122/keyo/blob/main/backend/packages/ledger/src/index.ts"

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_agent,node_llm toneBlue
class node_evidence_analysis,node_evidence_sources,node_evidence_score,node_xrpl toneAmber
class node_dashboard,node_state_api,node_heat_api,node_summer_api,node_tour_api,node_voice_api,node_tour_lib,node_voice_lib toneMint
class node_guard_client,node_guard,node_tx_verify,node_shared_policy,node_ledger toneRose
class node_db,node_heat_db,node_pulse_db,node_roommates,node_elevenlabs toneIndigo
```

## Components

### Chat assistant

- [Chat agent](https://github.com/kacytran1122/keyo/blob/main/backend/apps/agent/src/bot.ts): `backend/apps/agent/src/bot.ts`
- [Fact-based replies](https://github.com/kacytran1122/keyo/blob/main/backend/apps/agent/src/llm.ts): `backend/apps/agent/src/llm.ts`

### Rental evidence

- [Evidence analysis](https://github.com/kacytran1122/keyo/blob/main/backend/packages/evidence/src/analyze.ts): `backend/packages/evidence/src/analyze.ts`
- [Public record sources](https://github.com/kacytran1122/keyo/blob/main/backend/packages/evidence/src/sources.ts): `backend/packages/evidence/src/sources.ts`
- [Listing risk score](https://github.com/kacytran1122/keyo/blob/main/backend/packages/evidence/src/score.ts): `backend/packages/evidence/src/score.ts`

### Dashboard and tours

- [Map dashboard](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/components/Dashboard.tsx): `backend/apps/web/components/Dashboard.tsx`
- [Thread state API](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/state/route.ts): `backend/apps/web/app/api/state/route.ts`
- [Complaint heat API](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/heat/route.ts): `backend/apps/web/app/api/heat/route.ts`
- [Summer heat API](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/summer-heat/route.ts): `backend/apps/web/app/api/summer-heat/route.ts`
- [Tour script API](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/tour/route.ts): `backend/apps/web/app/api/tour/route.ts`
- [Tour voice API](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/app/api/voice/route.ts): `backend/apps/web/app/api/voice/route.ts`
- [Tour scripts](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/lib/tour.ts): `backend/apps/web/lib/tour.ts`
- [Speech synthesis](https://github.com/kacytran1122/keyo/blob/main/backend/apps/web/lib/elevenlabs.ts): `backend/apps/web/lib/elevenlabs.ts`

### Guarded payments

- [Guard API client](https://github.com/kacytran1122/keyo/blob/main/backend/apps/agent/src/guard-client.ts): `backend/apps/agent/src/guard-client.ts`
- [Payment policy guard](https://github.com/kacytran1122/keyo/blob/main/backend/apps/guard/src/server.ts): `backend/apps/guard/src/server.ts`
- [Transaction comparison](https://github.com/kacytran1122/keyo/blob/main/backend/apps/guard/src/verify-tx.ts): `backend/apps/guard/src/verify-tx.ts`
- [Payment policy rules](https://github.com/kacytran1122/keyo/blob/main/backend/packages/shared/src/policy.ts): `backend/packages/shared/src/policy.ts`
- [XRPL transaction tools](https://github.com/kacytran1122/keyo/blob/main/backend/packages/ledger/src/index.ts): `backend/packages/ledger/src/index.ts`

### Shared data

- [Application database](https://github.com/kacytran1122/keyo/blob/main/backend/packages/db/src/index.ts): `backend/packages/db/src/index.ts`
- [Complaint heat queries](https://github.com/kacytran1122/keyo/blob/main/backend/packages/db/src/heat.ts): `backend/packages/db/src/heat.ts`
- [Building pulse queries](https://github.com/kacytran1122/keyo/blob/main/backend/packages/db/src/pulse.ts): `backend/packages/db/src/pulse.ts`

### Other components

- **Roommates**
- **XRPL network**
- **ElevenLabs**

## Connections

- Roommates → Chat agent: message listings
- Chat agent → Guard API client: request payment
- Guard API client → Payment policy guard: cosign or fund
- Payment policy guard → Application database: load and update
- Payment policy guard → Payment policy rules: evaluate rules
- Payment policy guard → Transaction comparison: compare transaction
- Payment policy guard → XRPL transaction tools: sign and submit
- XRPL transaction tools → XRPL network: submit transaction
- Map dashboard → Thread state API: fetch thread state
- Thread state API → Application database: read thread data
- Map dashboard → Complaint heat API: request heat layer
- Complaint heat API → Complaint heat queries: query hotspots
- Complaint heat queries → Application database: read heat data
- Map dashboard → Summer heat API: request summer layer
- Summer heat API → Application database: query temperature cells
- Map dashboard → Tour script API: request tour script
- Tour script API → Tour scripts: load listing script
- Map dashboard → Tour voice API: request narration
- Tour voice API → Tour scripts: load room text
- Tour voice API → Speech synthesis: synthesize speech
- Speech synthesis → ElevenLabs: generate audio
- Thread state API → Building pulse queries: load building pulse