Customer Portal

The Rental Billing customer portal is a React single page application served at
/rental-portal and built from the rental-portal folder of this app.

Feature map

Authentication

The portal never stores or transmits passwords itself; credential handling is
delegated to Frappe. Sign-up is available only when
Website Settings → Disable Signup is unchecked.

utility_billing/www/rental-portal.py embeds the standard Frappe session boot
so the SPA receives frappe.boot and the session user without an extra call.

Portal roles and capabilities

utility_billing.api.portal.context.get_portal_context resolves the portal role
and the capabilities used by navigation and guards:

• Guest – anonymous visitor; may browse properties.
• Tenant – a user with the Customer or Tenant role linked through
  Customer.portal_users.
• Property Owner / Landlord, Property Manager, Utility Customer – role
  based, reserved for their dashboards.

Guests receive browse_properties only. Authenticated portal roles currently
receive the full capability map (browse_properties, view_dashboard,
view_my_units, manage_profile, manage_notifications).

Tenant linkage and access control

A tenant's records resolve through standard ERPNext documents:

User (Customer.portal_users) → Customer → Contract (party_type = Customer)
  → Contract Utility Property Item → Utility Property

get_my_properties classifies allocations as:

Property details, invoices, orders, payments, meter readings and support
tickets are always scoped to the caller's own Customers and the requested
property/document. Client-supplied ownership, amounts and statuses are never
trusted.

Bookings

A portal booking is a draft Utility Service Request created for the caller's
Customer. It carries the property row, lease dates and tenant notes.

• The unit stays publicly available until staff submit the request.
• A second pending booking for the same unit is rejected; the tenant is sent to
  the existing request.
• Tenants can modify dates, extend or cancel a pending/current booking according
  to the same ownership rules.
• Submitting the request creates the Contract; signing it moves the unit from
  Reserved to Active.

The portal booking form reads defaults from
get_booking_options: property, monthly rent, deposit, lease dates and any
pending booking.

Invoices, orders and payments

/invoices lists every submitted, payable Sales Invoice and Sales Order of the
signed-in Customer.

• An invoice is paid for its outstanding amount.
• A Sales Order is paid as an advance for its unbilled balance.
• The portal asks the selected gateway controller for a checkout URL and
  redirects the customer. It does not create Payment Entries or Payment
  Requests itself; the gateway records the payment on the reference document.
• A Payment Gateway Account must exist for the document's company. The demo
  data does not create one.

Support tickets

Customers raise standard ERPNext Issue documents from:

• a booking (create_support_issue), or
• an active/reserved property (create_property_support_issue).

Each ticket stores utility_property, utility_service_request (when known),
the Customer, the company and via_customer_portal. Replies are Comments on the
Issue and are rendered with the document timeline. Status counts (open, replied,
resolved) come from the Issue status.

Property details and related documents

Related documents are resolved through:

API surface

Generic doctype browsing (/app routes)

The portal reuses metadata-driven DocTypeList / DocTypeForm components for
/app/:doctype(/:id) pages. They use standard Frappe endpoints:

• frappe.desk.form.load.getdoctype
• frappe.desk.reportview.get and get_count
• frappe.desk.form.load.getdoc
• frappe.client.save / frappe.desk.form.save.savedocs
• frappe.desk.search.search_link
• frappe.model.workflow.*

Slug mapping lives in src/lib/doctype-map.ts. Users without permission are
redirected by PermissionGuard to the forbidden page.

Notifications and appearance

• Notification feed and unread badge use the standard notification log.
• Preferences are handled by /app/notification-settings/<user>.
• The theme customiser supports light/dark mode, 16 estate presets, per-mode
  token overrides, opt-in gradients, radius, sidebar variant and layout.
• Theme selections persist in localStorage under rental-portal:theme.

Frontend structure

rental-portal/src
├── app/                          # auth, dashboard, properties, bookings, invoices, support pages
├── components/
│   ├── properties/               # card, row, media, status and layout components
│   ├── payments/                 # pay button and gateway dialog
│   ├── support/                  # support list/create/detail/reply/timeline
│   ├── doctype/ + fields/        # generic Frappe metadata renderers
│   ├── theme-customizer/         # presets, colours, gradients, layout
│   └── ui/                       # shared primitives
├── config/routes.tsx             # route tree and command-search metadata
├── contexts/                     # user, portal role, notifications
├── lib/                          # Frappe helpers, doctype slugs, formatting
└── types/                        # shared payloads

Demo accounts

The demo generator creates 12 Website Users linked to Customers. See
Demo Data for every email. All demo accounts use the password
Demo@12345; use them for staging and training only.

Tests

utility_billing/utility_billing/tests/test_portal_roles.py covers role,
capability and allocation classification rules:

bench --site <site> run-tests --module utility_billing.utility_billing.tests.test_portal_roles