# project-butler/butler architecture

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

- Interactive diagram: https://gitdiagram.com/project-butler/butler
- Repository: https://github.com/project-butler/butler

## Overview

Butler is a rental-management service for landlords, tenants, and operators, delivered through one role- and surface-aware frontend and an Express/Prisma API. The principal workflow is a landlord managing properties, units, contracts, and related records; tenants can access their contracts, while operators administer users and operations. Distinct supporting capabilities include invitations, document storage, community features, and dispute guidance. The README establishes the frontend/API relationship and major product capabilities; sampled controllers show selected API-to-service calls. Other feature-level wiring is not asserted where source was unsampled.

Main entry points: [`apps/butler/src/App.jsx`](https://github.com/project-butler/butler/blob/dev/apps/butler/src/App.jsx) (Role-aware frontend), [`apps/api/src/app.js`](https://github.com/project-butler/butler/blob/dev/apps/api/src/app.js) (Express API), [`apps/api/src/domains/disputes/controller.js`](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/disputes/controller.js) (Dispute guidance), [`apps/api/src/domains/community/controller.js`](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/community/controller.js) (Resident community)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Role-based client"]
  node_client_app["Role-aware frontend<br/>[App.jsx]"]
  node_landlord_views["Landlord screens"]
  node_tenant_views["Tenant screens<br/>[TenantRoutes.jsx]"]
  node_admin_views["Admin screens<br/>[AdminRoutes.jsx]"]
  node_invite_views["Invitation flow<br/>[InviteRoutes.jsx]"]
end

subgraph group_rental["Rental operations"]
  node_properties["Property management<br/>[service.js]"]
  node_contracts["Lease contracts<br/>[service.js]"]
  node_buildings["Building lookup<br/>[service.js]"]
  node_ownership["Ownership verification<br/>[service.js]"]
  node_documents["Document handling<br/>[service.js]"]
  node_invitations["Tenant invitations<br/>[service.js]"]
end

subgraph group_support["Resident support"]
  node_community["Resident community<br/>[controller.js]"]
  node_disputes["Dispute guidance<br/>[controller.js]"]
  node_dispute_search["Reference retrieval<br/>[retriever.js]"]
  node_dispute_chat["Counselor chatbot<br/>[chatbot.js]"]
end

subgraph group_operations["Platform operations"]
  node_admin["Operator services<br/>[service.js]"]
  node_activities["Activity history<br/>[service.js]"]
end

subgraph group_shared["API foundation"]
  node_api["Express API<br/>[app.js]"]
  node_database[("PostgreSQL<br/>[prismaClient.js]")]
  node_response["Response envelope<br/>[respond.js]"]
end

node_landlords(("Landlords"))
node_tenants(("Tenants"))
node_operators(("Operators"))

node_landlords -->|"use"| node_client_app
node_tenants -->|"use"| node_client_app
node_operators -->|"use"| node_client_app
node_client_app -->|"routes by role"| node_landlord_views
node_client_app -->|"routes by role"| node_tenant_views
node_client_app -->|"routes by role"| node_admin_views
node_client_app -->|"routes invitations"| node_invite_views
node_client_app -->|"calls API"| node_api
node_landlord_views -.->|"requests"| node_properties
node_tenant_views -.->|"requests"| node_contracts
node_admin_views -.->|"requests"| node_admin
node_invite_views -.->|"requests"| node_invitations
node_api -.->|"routes to"| node_properties
node_api -.->|"routes to"| node_contracts
node_api -.->|"routes to"| node_documents
node_api -.->|"routes to"| node_community
node_api -.->|"routes to"| node_disputes
node_api -.->|"routes to"| node_admin
node_community -->|"loads news"| node_dispute_search
node_disputes -->|"retrieves references"| node_dispute_search
node_disputes -->|"asks counselor"| node_dispute_chat
node_disputes -->|"sends results"| node_response
node_community -->|"sends results"| node_response
node_admin -.->|"reads and writes"| node_database
node_properties -.->|"reads and writes"| node_database
node_contracts -.->|"reads and writes"| node_database

click node_client_app "https://github.com/project-butler/butler/blob/dev/apps/butler/src/App.jsx"
click node_landlord_views "https://github.com/project-butler/butler/blob/dev/apps/butler/src/landlord/web/LandlordWebRoutes.jsx"
click node_tenant_views "https://github.com/project-butler/butler/blob/dev/apps/butler/src/tenant/TenantRoutes.jsx"
click node_admin_views "https://github.com/project-butler/butler/blob/dev/apps/butler/src/admin/AdminRoutes.jsx"
click node_invite_views "https://github.com/project-butler/butler/blob/dev/apps/butler/src/invite/InviteRoutes.jsx"
click node_api "https://github.com/project-butler/butler/blob/dev/apps/api/src/app.js"
click node_properties "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/properties/service.js"
click node_contracts "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/contracts/service.js"
click node_buildings "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/complexes/service.js"
click node_ownership "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/ownershipVerifications/service.js"
click node_documents "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/documents/service.js"
click node_invitations "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/tenantInvitations/service.js"
click node_community "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/community/controller.js"
click node_disputes "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/disputes/controller.js"
click node_dispute_search "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/disputes/retriever.js"
click node_dispute_chat "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/disputes/chatbot.js"
click node_admin "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/admin/service.js"
click node_activities "https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/activities/service.js"
click node_database "https://github.com/project-butler/butler/blob/dev/apps/api/src/platform/prismaClient.js"
click node_response "https://github.com/project-butler/butler/blob/dev/apps/api/src/platform/respond.js"

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_client_app,node_landlord_views,node_tenant_views,node_admin_views,node_invite_views toneBlue
class node_properties,node_contracts,node_buildings,node_ownership,node_documents,node_invitations toneAmber
class node_community,node_disputes,node_dispute_search,node_dispute_chat toneMint
class node_admin,node_activities toneRose
class node_api,node_database,node_response,node_landlords,node_tenants,node_operators toneIndigo
```

## Components

### Role-based client

- [Role-aware frontend](https://github.com/project-butler/butler/blob/dev/apps/butler/src/App.jsx): `apps/butler/src/App.jsx`
- [Landlord screens](https://github.com/project-butler/butler/blob/dev/apps/butler/src/landlord/web/LandlordWebRoutes.jsx): `apps/butler/src/landlord/web/LandlordWebRoutes.jsx`
- [Tenant screens](https://github.com/project-butler/butler/blob/dev/apps/butler/src/tenant/TenantRoutes.jsx): `apps/butler/src/tenant/TenantRoutes.jsx`
- [Admin screens](https://github.com/project-butler/butler/blob/dev/apps/butler/src/admin/AdminRoutes.jsx): `apps/butler/src/admin/AdminRoutes.jsx`
- [Invitation flow](https://github.com/project-butler/butler/blob/dev/apps/butler/src/invite/InviteRoutes.jsx): `apps/butler/src/invite/InviteRoutes.jsx`

### Rental operations

- [Property management](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/properties/service.js): `apps/api/src/domains/properties/service.js`
- [Lease contracts](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/contracts/service.js): `apps/api/src/domains/contracts/service.js`
- [Building lookup](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/complexes/service.js): `apps/api/src/domains/complexes/service.js`
- [Ownership verification](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/ownershipVerifications/service.js): `apps/api/src/domains/ownershipVerifications/service.js`
- [Document handling](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/documents/service.js): `apps/api/src/domains/documents/service.js`
- [Tenant invitations](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/tenantInvitations/service.js): `apps/api/src/domains/tenantInvitations/service.js`

### Resident support

- [Resident community](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/community/controller.js): `apps/api/src/domains/community/controller.js`
- [Dispute guidance](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/disputes/controller.js): `apps/api/src/domains/disputes/controller.js`
- [Reference retrieval](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/disputes/retriever.js): `apps/api/src/domains/disputes/retriever.js`
- [Counselor chatbot](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/disputes/chatbot.js): `apps/api/src/domains/disputes/chatbot.js`

### Platform operations

- [Operator services](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/admin/service.js): `apps/api/src/domains/admin/service.js`
- [Activity history](https://github.com/project-butler/butler/blob/dev/apps/api/src/domains/activities/service.js): `apps/api/src/domains/activities/service.js`

### API foundation

- [Express API](https://github.com/project-butler/butler/blob/dev/apps/api/src/app.js): `apps/api/src/app.js`
- [PostgreSQL](https://github.com/project-butler/butler/blob/dev/apps/api/src/platform/prismaClient.js): `apps/api/src/platform/prismaClient.js`
- [Response envelope](https://github.com/project-butler/butler/blob/dev/apps/api/src/platform/respond.js): `apps/api/src/platform/respond.js`

### Other components

- **Landlords**
- **Tenants**
- **Operators**

## Connections

- Landlords → Role-aware frontend: use (evidence: `README.md`)
- Tenants → Role-aware frontend: use (evidence: `README.md`)
- Operators → Role-aware frontend: use (evidence: `README.md`)
- Role-aware frontend → Landlord screens: routes by role (evidence: `apps/butler/src/App.jsx`)
- Role-aware frontend → Tenant screens: routes by role (evidence: `apps/butler/src/App.jsx`)
- Role-aware frontend → Admin screens: routes by role (evidence: `apps/butler/src/App.jsx`)
- Role-aware frontend → Invitation flow: routes invitations (evidence: `apps/butler/src/App.jsx`)
- Role-aware frontend → Express API: calls API (evidence: `README.md`)
- Landlord screens → Property management: requests
- Tenant screens → Lease contracts: requests
- Admin screens → Operator services: requests
- Invitation flow → Tenant invitations: requests
- Express API → Property management: routes to
- Express API → Lease contracts: routes to
- Express API → Document handling: routes to
- Express API → Resident community: routes to
- Express API → Dispute guidance: routes to
- Express API → Operator services: routes to
- Resident community → Reference retrieval: loads news (evidence: `apps/api/src/domains/community/controller.js`)
- Dispute guidance → Reference retrieval: retrieves references (evidence: `apps/api/src/domains/disputes/controller.js`)
- Dispute guidance → Counselor chatbot: asks counselor (evidence: `apps/api/src/domains/disputes/controller.js`)
- Dispute guidance → Response envelope: sends results (evidence: `apps/api/src/domains/disputes/controller.js`)
- Resident community → Response envelope: sends results (evidence: `apps/api/src/domains/community/controller.js`)
- Operator services → PostgreSQL: reads and writes
- Property management → PostgreSQL: reads and writes
- Lease contracts → PostgreSQL: reads and writes