# dwell-official/dwell architecture

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

- Interactive diagram: https://gitdiagram.com/dwell-official/dwell
- Repository: https://github.com/dwell-official/dwell

## Overview

Dwell helps renters compare housing against a full-cost, infrastructure-aware plan, then verify listings through visit-gated reviews; agents publish listings and build a reputation. The graph includes the documented AI advice and summaries, market statistics, civic exports, plan sharing, and rewards. Backend route mounting and sampled review/reward calls support the shown wiring; unsampled feature internals and database relationships are not inferred.

Main entry points: [`backend/src/index.ts`](https://github.com/dwell-official/dwell/blob/main/backend/src/index.ts) (REST API), [`frontend/src/App.tsx`](https://github.com/dwell-official/dwell/blob/main/frontend/src/App.tsx) (Web application), [`backend/src/services/rewardService.ts`](https://github.com/dwell-official/dwell/blob/main/backend/src/services/rewardService.ts) (Rewards wallet), [`backend/src/routes/reviews.ts`](https://github.com/dwell-official/dwell/blob/main/backend/src/routes/reviews.ts) (Review handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Rental discovery"]
  node_plan["Plan builder<br/>[PlanBuilder.tsx]"]
  node_listings["Listing discovery<br/>[Listings.tsx]"]
  node_listing_detail["Listing details<br/>[ListingDetail.tsx]"]
  node_match["Match scoring<br/>[matchScore.ts]"]
  node_market_stats["Market statistics<br/>[marketStats.ts]"]
  node_visits["Visit scheduling<br/>[Visits.tsx]"]
  node_ai_advisor["AI budget advice<br/>[aiBudgetAdvisor.ts]"]
  node_sharing["Plan sharing<br/>[share.ts]"]
end

subgraph group_trust["Trust and accountability"]
  node_review_form["Visit review<br/>[ReviewForm.tsx]"]
  node_tenancy_review["Tenancy review"]
  node_reviews_api["Review handling<br/>[reviews.ts]"]
  node_health["Infrastructure scores<br/>[healthScore.ts]"]
  node_civic["Civic reporting<br/>[civicExport.ts]"]
  node_ai_summary["Review summaries<br/>[aiSummary.ts]"]
end

subgraph group_market["Marketplace operations"]
  node_agent_tools["Agent listings<br/>[AgentDashboard.tsx]"]
  node_rewards["Rewards wallet<br/>[rewardService.ts]"]
end

subgraph group_platform["Application platform"]
  node_app["Web application<br/>[App.tsx]"]
  node_api["REST API<br/>[index.ts]"]
  node_database[("Application database")]
  node_notification["Notifications<br/>[notifications.ts]"]
  node_vtu["VTU provider<br/>[vtu-factory.ts]"]
end

node_renter(("Renter"))
node_agent(("Agent"))

node_renter -->|"uses"| node_app
node_agent -->|"uses"| node_app
node_app -->|"routes to"| node_plan
node_app -->|"routes to"| node_listings
node_app -->|"routes to"| node_listing_detail
node_app -->|"routes to"| node_visits
node_app -->|"routes to"| node_review_form
node_app -->|"routes to"| node_tenancy_review
node_app -->|"routes to"| node_agent_tools
node_plan -->|"requests"| node_api
node_listings -->|"requests"| node_api
node_listing_detail -->|"requests"| node_api
node_visits -->|"requests"| node_api
node_review_form -->|"submits review"| node_api
node_tenancy_review -->|"submits review"| node_api
node_api -->|"dispatches"| node_reviews_api
node_api -->|"serves data"| node_database
node_reviews_api -->|"reads and writes"| node_database
node_reviews_api -->|"triggers reward"| node_rewards
node_rewards -->|"reads and writes"| node_database
node_rewards -->|"creates notification"| node_notification
node_rewards -->|"fulfills claim"| node_vtu
node_api -->|"dispatches"| node_civic
node_api -->|"dispatches"| node_sharing
node_agent_tools -->|"requests"| node_api

click node_app "https://github.com/dwell-official/dwell/blob/main/frontend/src/App.tsx"
click node_plan "https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/PlanBuilder.tsx"
click node_listings "https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/Listings.tsx"
click node_listing_detail "https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/ListingDetail.tsx"
click node_match "https://github.com/dwell-official/dwell/blob/main/backend/src/services/matchScore.ts"
click node_market_stats "https://github.com/dwell-official/dwell/blob/main/backend/src/services/marketStats.ts"
click node_visits "https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/Visits.tsx"
click node_review_form "https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/ReviewForm.tsx"
click node_tenancy_review "https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/TenancyReviewForm.tsx"
click node_reviews_api "https://github.com/dwell-official/dwell/blob/main/backend/src/routes/reviews.ts"
click node_health "https://github.com/dwell-official/dwell/blob/main/backend/src/services/healthScore.ts"
click node_civic "https://github.com/dwell-official/dwell/blob/main/backend/src/routes/civicExport.ts"
click node_ai_advisor "https://github.com/dwell-official/dwell/blob/main/backend/src/services/aiBudgetAdvisor.ts"
click node_ai_summary "https://github.com/dwell-official/dwell/blob/main/backend/src/services/aiSummary.ts"
click node_sharing "https://github.com/dwell-official/dwell/blob/main/backend/src/routes/share.ts"
click node_agent_tools "https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/AgentDashboard.tsx"
click node_rewards "https://github.com/dwell-official/dwell/blob/main/backend/src/services/rewardService.ts"
click node_api "https://github.com/dwell-official/dwell/blob/main/backend/src/index.ts"
click node_notification "https://github.com/dwell-official/dwell/blob/main/backend/src/routes/notifications.ts"
click node_vtu "https://github.com/dwell-official/dwell/blob/main/backend/src/providers/vtu-factory.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_plan,node_listings,node_listing_detail,node_match,node_market_stats,node_visits,node_ai_advisor,node_sharing toneBlue
class node_review_form,node_tenancy_review,node_reviews_api,node_health,node_civic,node_ai_summary toneAmber
class node_agent_tools,node_rewards toneMint
class node_app,node_api,node_database,node_notification,node_vtu toneRose
class node_renter,node_agent toneIndigo
```

## Components

### Rental discovery

- [Plan builder](https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/PlanBuilder.tsx): `frontend/src/pages/PlanBuilder.tsx`
- [Listing discovery](https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/Listings.tsx): `frontend/src/pages/Listings.tsx`
- [Listing details](https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/ListingDetail.tsx): `frontend/src/pages/ListingDetail.tsx`
- [Match scoring](https://github.com/dwell-official/dwell/blob/main/backend/src/services/matchScore.ts): `backend/src/services/matchScore.ts`
- [Market statistics](https://github.com/dwell-official/dwell/blob/main/backend/src/services/marketStats.ts): `backend/src/services/marketStats.ts`
- [Visit scheduling](https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/Visits.tsx): `frontend/src/pages/Visits.tsx`
- [AI budget advice](https://github.com/dwell-official/dwell/blob/main/backend/src/services/aiBudgetAdvisor.ts): `backend/src/services/aiBudgetAdvisor.ts`
- [Plan sharing](https://github.com/dwell-official/dwell/blob/main/backend/src/routes/share.ts): `backend/src/routes/share.ts`

### Trust and accountability

- [Visit review](https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/ReviewForm.tsx): `frontend/src/pages/ReviewForm.tsx`
- [Tenancy review](https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/TenancyReviewForm.tsx): `frontend/src/pages/TenancyReviewForm.tsx`
- [Review handling](https://github.com/dwell-official/dwell/blob/main/backend/src/routes/reviews.ts): `backend/src/routes/reviews.ts`
- [Infrastructure scores](https://github.com/dwell-official/dwell/blob/main/backend/src/services/healthScore.ts): `backend/src/services/healthScore.ts`
- [Civic reporting](https://github.com/dwell-official/dwell/blob/main/backend/src/routes/civicExport.ts): `backend/src/routes/civicExport.ts`
- [Review summaries](https://github.com/dwell-official/dwell/blob/main/backend/src/services/aiSummary.ts): `backend/src/services/aiSummary.ts`

### Marketplace operations

- [Agent listings](https://github.com/dwell-official/dwell/blob/main/frontend/src/pages/AgentDashboard.tsx): `frontend/src/pages/AgentDashboard.tsx`
- [Rewards wallet](https://github.com/dwell-official/dwell/blob/main/backend/src/services/rewardService.ts): `backend/src/services/rewardService.ts`

### Application platform

- [Web application](https://github.com/dwell-official/dwell/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [REST API](https://github.com/dwell-official/dwell/blob/main/backend/src/index.ts): `backend/src/index.ts`
- **Application database**
- [Notifications](https://github.com/dwell-official/dwell/blob/main/backend/src/routes/notifications.ts): `backend/src/routes/notifications.ts`
- [VTU provider](https://github.com/dwell-official/dwell/blob/main/backend/src/providers/vtu-factory.ts): `backend/src/providers/vtu-factory.ts`

### Other components

- **Renter**
- **Agent**

## Connections

- Renter → Web application: uses
- Agent → Web application: uses
- Web application → Plan builder: routes to
- Web application → Listing discovery: routes to
- Web application → Listing details: routes to
- Web application → Visit scheduling: routes to
- Web application → Visit review: routes to
- Web application → Tenancy review: routes to
- Web application → Agent listings: routes to
- Plan builder → REST API: requests
- Listing discovery → REST API: requests
- Listing details → REST API: requests
- Visit scheduling → REST API: requests
- Visit review → REST API: submits review
- Tenancy review → REST API: submits review
- REST API → Review handling: dispatches
- REST API → Application database: serves data
- Review handling → Application database: reads and writes
- Review handling → Rewards wallet: triggers reward
- Rewards wallet → Application database: reads and writes
- Rewards wallet → Notifications: creates notification
- Rewards wallet → VTU provider: fulfills claim
- REST API → Civic reporting: dispatches
- REST API → Plan sharing: dispatches
- Agent listings → REST API: requests