Rentals¶

The Rentals module turns your CautaReside into a property-management platform: leases, tenants, listings, agent commissions, lease renewal workflows. Useful for facilities that operate as rental estates rather than owner-occupied condos.

What tenants see¶

Tenants get a focused My Rental view:

Lease summary — start/end dates, monthly rent, deposit amount, notice period.
Lease document (PDF) — your standard agreement, viewable and downloadable.
Renewal countdown — days until lease ends + renewal status.
Pay rent — one-click rent payment via MoMo / card. Also available in the Billing module.
Move-out request — initiate the move-out workflow with notice date.

What landlords / owners see¶

If your facility allows owners to manage their own units:

My Properties — every unit they own, with current tenant / vacant status.
Income summary — rent collected per unit per month.
Listings — units they want to advertise as available.
Tenant applications — for vacant units, applications they've received via the listing.

What facility admins do¶

Register a lease¶

Rentals → New Lease:

Unit (linked to your unit registry).
Tenant (existing resident or new — system creates the user account if new).
Owner (the unit's owner — typically pre-filled from the unit record).
Start date + duration (typical: 12 months).
Monthly rent + deposit + other charges (service, utilities, parking).
Notice period (typical: 30 or 60 days).
Lease document — generate from your facility's template, or upload a signed PDF.

The system creates the tenant's portal access, schedules the recurring monthly rent invoices, and sets up the renewal countdown.

Manage listings¶

For vacant units:

Rentals → Listings → New Listing.
Pick the unit, set asking rent, write a description, attach photos.
Mark active.
The listing appears on your facility's resident-facing portal (if public listings are enabled) and in your agent network.

When applications come in: - Review applicant details (income, references, prior tenancy history). - Approve → triggers lease creation workflow. - Decline → applicant is notified.

Lease renewal workflow¶

90 days before lease end: - Tenant gets a renewal prompt (via email + push). - They can accept renewal, propose changes, or initiate move-out. - Negotiate the new terms inside the messaging module. - Sign the new lease (digital signature or upload).

Move-out workflow¶

When a tenant initiates move-out: 1. Notice received — system records the date. 2. Inspection scheduled — pick a date, assign a staff member. 3. Inspection report — checklist + photos of unit condition. 4. Deposit reconciliation — calculate any deductions for damage, unpaid bills, cleaning fees. 5. Final settlement — refund the deposit (minus deductions) or bill the tenant for any shortfall.

Each step is logged with timestamps and signatures, so disputes about "who took my deposit" are resolved by the audit trail.

Real-estate agents¶

CautaReside has a full real-estate agent sub-module with its own self-service portal, license tracking, SOP acceptance flow, training quiz, peer-to-peer access delegation, and 5-metric ratings. Two distinct agent types exist; pick the right one when registering.

Agent types: internal vs external¶

Internal agent — facility staff or in-house agent hired by the management company / developer. Commission-eligible. Sees the full rentals slice for the facility (treated as mgmt-aligned). Gets all agent-portal features.
External agent — third-party contractor agent hired by an individual unit owner (not by the facility). Referral-only: commission tracking is disabled by default. Scoped data view — sees only the units and owners they're assigned to. Subset of agent-portal features (no commissions tab, no long-let rental notifications, no dashboard stats).

You pick the type when registering the agent. It's reversible from the admin agent table (the "Convert to Internal / External" action) but flipping it triggers a permission-scope recompute; the agent should re-login for the new scope to take effect cleanly.

License capture¶

Every agent has a license number + license expiry captured at registration:

License number — auto-generated as <FACILITY>-<RAND6> (e.g. DEMO-A3K9X7). Opaque, facility-prefixed, drawn from a 32-char alphabet that excludes visually-confusing characters (no 0/O/1/I). Mgmt can override with an externally-issued GREDA REA license number on creation if the agent already holds one. The auto-generated number is NOT a credential — it's a display ID for mgmt to reference at renewal time.
License issue date — derived from the agent record's creation timestamp. Shown as issued YYYY-MM-DD next to the license number in both the admin table and the agent's own profile, so mgmt can spot overdue-for-renewal licenses at a glance without baking the date into the ID itself.
License expiry — required. Drives the auto-suspension job (see below).

License auto-suspension + renewal¶

A daily background job scans for agents whose license_expiry has passed and flips them to suspended state. The same status flips on the agent at the instant the expiry timestamp is reached — there's no "my license expired 6 hours ago and I'm still working" race window.

A suspended agent: - Can still log in and view their existing assignments, delegations, ratings, notifications, and any signed SOP receipt. - CANNOT take any new actions — no visitor pre-registration, no short-stay creation, no rental notification, no delegation grants. - Sees a red banner across all panels of their portal with the renewal instructions.

To renew: 1. Agent obtains a new license offline (GREDA registration, etc.). 2. Mgmt updates the license expiry date in the admin form. 3. If the facility has Phase 2 enabled, the renewal gate runs and blocks the save unless the agent has ALSO accepted the latest SOPs AND passed the standards training quiz since their previous expiry. The save returns RENEWAL_REQUIRES_SOP_ACCEPTANCE or RENEWAL_REQUIRES_TRAINING if either is missing. 4. Once the renewal goes through, the suspension auto-clears in the same save and the agent is back in normal status.

Standard Operating Procedures (SOPs)¶

Each facility can author and publish an Agent SOP that agents must read and accept at first login and at every license renewal. There are two separate SOP tracks:

Internal Agent SOPs — for staff agents. Authored in Settings → Agent SOPs & Training Questions. Edit Markdown directly, click Save Draft as many times as you like, click Publish to Internal Agents when ready to push.
External (Contractor) Agent SOPs — for third-party contractor agents. Same editor pattern, separate card immediately below the Internal SOPs editor. If left blank or unpublished, external agents fall back to the internal SOP at sign time — you're not forced to author a second SOP on day one. When you do publish a contractor SOP, externals sign THAT version instead of the internal one.

Both tracks share the same operator-controlled master switch (the Agent SOP gate). Flipping the gate off kills both at once — there's no split-personality state where internal SOPs enforce but external don't.

When SOPs are published: - New agents see a blocking modal at first login until they accept. - Existing agents see a banner with a sign affordance. - At license renewal, mgmt's save is blocked until the agent has accepted the LATEST version (the SHA-256 of the markdown they signed is stored on the agent row, so a re-publish counts as a new version and triggers the gate). - Once accepted, the agent gets a 📥 Download signed copy (PDF) affordance — a streamed receipt with the SOP body, typed/drawn signature, signing date + time, acceptance IP, content hash, and the Act 772 attestation paragraph (Ghana's Electronic Transactions Act, 2008).

Signature options¶

The agent picks between two signature modes at acceptance time:

Type your full legal name (default) — the typed characters are the signature artefact, rendered in a script-ish typeface on the receipt above a horizontal rule.
Draw signature — a freehand canvas (mouse, finger, or stylus via Pointer Events). Stored as a PNG and embedded directly in the PDF receipt. The two modes are mutually exclusive: switching modes picks one or the other.

The receipt PDF carries both visual signature + the audit fingerprint (SHA-256 of the markdown body) so anyone can recompute the hash and verify byte-equality with the content the agent saw at acceptance.

Training quiz¶

Each facility can author multiple-choice questions (prompt + options + correctIndex) under Settings → Agent SOPs & Training Questions. The agent takes the quiz in their portal under the 📜 Training tab. Server scores in real time:

✓ PASSED — score ≥ facility threshold (default 80%). The last- pass timestamp is stamped on the agent record; the agent is cleared for license renewal until their next expiry cycle.
✗ Did not pass — try again. Re-takes are unlimited; only the most recent pass counts.

If the agent's last quiz pass is BEFORE their current license expiry, the next renewal save is blocked with RENEWAL_REQUIRES_TRAINING until they re-take.

The training quiz currently runs as a single track per audience — internal and external agents take the same quiz. A contractor- specific quiz track is a separate scope decision; ask if you want it.

Peer-to-peer access delegation¶

An agent who holds a primary assignment on a unit can grant another agent temporary delegated access to that unit via the 🤝 Delegations tab in their portal. A delegate can pre-register visitors and book short-stays against the delegated unit for the window the grant covers.

Auth rules: 1. Caller must hold an active PRIMARY assignment for the unit. No chaining — a delegate cannot re-delegate. 2. Target agent must be active in the same facility. 3. Cannot grant to self. 4. Optional expiry date — if set, must be in the future. After expiry, the delegation row auto-deactivates.

Bidirectional internal ↔ external delegation is allowed. A staff agent can delegate down to a contractor (a unit owner's contractor helping cover a viewing) and a contractor can delegate up to a staff agent. Subject to the rules above.

The delegation target picker is scoped: - Internal agents see the full facility agent directory in the picker (other internals + externals). - External agents see the smaller set of (all internal agents) ∪ (other external agents sharing at least one assigned owner). This prevents a contractor from enumerating every other contractor at the facility — they only see legitimate working-relationship collaborators plus the chain-of-command internal agents.

Agent visitor pre-registration¶

Agents (internal and external) pre-register visitors against units they're assigned to (primary or via delegation). The visitor appears in the facility-wide visitor log with preRegisteredBy = <agent userId>. Same shape as staff-side pre-registration — the only difference is the unit picker is scoped to the agent's accessible units.

Agent ratings (5-metric)¶

Tenants, owners, and mgmt can rate an agent across five metrics: communication, professionalism, market knowledge, responsiveness, transparency. The agent sees:

Their own aggregate (avg + count).
Free-text comment list from each rating — never the rater identity (retaliation protection: an agent who could see "Owner X rated me 1 star" might refuse to work with them).
No per-metric breakdown (mgmt-only).

Mgmt sees the full breakdown with rater identity (used for picking agents for assignments + dealing with abuse cases).

Listings¶

Agents can post listings for the units they're assigned to. The listing form pulls the unit registry for the agent's accessible units. Mgmt approves listings before they go public on the resident-facing portal.

For external agents, the listings tab shows only listings for units their assigned owners control. For internal agents it's the full facility set (same view as mgmt-tier).

Short-stays¶

Both agent types can create short-stay bookings against units they're assigned to. Same flow as the staff-side short-stay process — guest + ID + dates + party size → rate calculation → payment link → temp unit-resident + temp access credential.

Commission ledger (internal agents only)¶

Internal agents see their commission ledger under the 💰 Commissions tab. Tracks pending and paid-out commission entries with unit + source context (rent, short-stay, etc.). External agents do not have a commission ledger — by design, their commission terms default to zero on registration (referral-only model).

Reports¶

Occupancy rate (occupied units / total)
Rent collection rate (% of rent invoiced collected on time)
Vacancy duration (average days a unit sits empty between leases)
Renewal rate (% of leases that renew vs end)
Per-agent performance (placements + collected commission)

Tips¶

Upload signed leases as PDFs — even with a digital workflow, having the signed document attached to the lease record matters for legal disputes.
Schedule inspections at lease start AND end — having a baseline prevents arguments about pre-existing damage.
Use Rentals + Billing together — rent is one of many charges on a tenant's monthly invoice. Configure the rent line item in your fee schedule so it appears alongside service charge, parking, etc.
Renewal lead time — 90 days is the typical notice but it's configurable. For high-demand units, 120 days gives you more time to find a new tenant if the current one moves out.
Encourage agents to set their portal username — system-assigned IDs are enumerable; a self-chosen username is a small hardening step against credential-stuffing attacks. Surfaced via a nudge card in Settings → Account.

Process flows¶

End-to-end procedures the rentals / mgmt team runs day-to-day. Steps are anchored to the actual UI labels.

List a unit for rent¶

Rentals → + List a unit.
Pick the unit from the registry (auto-fills bedrooms, area, location).
Pick listing type (Long-term lease / Short-stay / Both).
Capture rent (per month for long-term, per night for short-stay), security deposit, available-from date, optional photos (up to 12).
Publish — listing goes live on the public rental surface (and / or the Agent Portal if a real-estate-agent integration is configured).

Process a long-term rental application¶

Application lands in Rentals → Applications with status New.
Open the application → review applicant details, references, payslip / employment proof attachments, requested move-in date.
Action:
Schedule a viewing (sends a calendar invite).
Decline with a reason (Income criteria / References / Already accepted another / Other).
Approve → tenancy contract draft auto-generated from the facility's lease template; both parties sign electronically.
On signed contract: deposit + first month's rent posted to billing; resident user account auto-created with their lease end-date driving access-control auto-revoke.

Onboard a short-stay guest¶

Rentals → Short-stays → + New booking (or accept a request from the public listing).
Capture guest name + ID + arrival / departure dates + party size.
The system computes the rate (per-night × nights + cleaning fee + caution deposit) and pushes a payment link to the guest.
On payment, the system: creates a temporary unit-resident record for the stay window; issues a temporary access credential (PIN or RFID, scoped to that window); pre-registers a vehicle pass if the guest provided plate details.
At checkout: caution deposit auto-refunds after the housekeeping inspection passes (24 h SLA); damage deductions are itemised + emailed to the guest before refund.

Handle a security-deposit dispute¶

Rentals → tenancy → End of tenancy → check-out inspection.
Capture damage items with photos + replacement-cost estimate. The deposit-return statement auto-deducts the listed items.
Email the deposit-return statement to the tenant.
If the tenant disputes:
Open dispute on the tenancy → tenant uploads counter- evidence + their own assessment.
Mgmt reviews → Adjust deductions (revise the statement) or Hold pending arbitration.
Once resolved, Confirm refund — the agreed amount transfers via the original payment method; the dispute trail is preserved permanently for audit.

Register a new agent¶

Rentals → Agents → + Register Agent.
Pick agent type: Internal (commission-eligible, staff / on-contract) or External (referral-only, 3^rd-party contractor).
Capture name, company (optional), phone, email, ID type + number.
Optionally enter a license number if the agent already holds an externally-issued one; otherwise leave blank to let the system auto-generate <FACILITY>-<RAND6>.
License expiry — required. Default: 1 year from today.
Save → agent created, invite link sent to their email (with SMS fallback if the email bounces). Account is pending_first_ login_sop = true if the SOP gate is enabled.

Author + publish Agent SOPs¶

Settings → scroll to 📜 Agent SOPs & Training Questions (requires the Agent SOP gate to be ON for your facility).
Author the internal SOPs in Markdown.
Optionally author the external (contractor) SOPs in the second card. Leave blank to use the internal SOPs for contractors too.
Add training questions in the JSON editor ([{ id, prompt, options: [], correctIndex }, …]).
Click Save Draft to persist without exposing to agents.
Click 👁 Preview as agent to render exactly what an agent will see (no acceptance recorded).
Click Publish to Internal Agents / Publish to Contractors when ready. Existing agents see a banner the next time they open their portal; new agents see a blocking first-login modal.

Suspend an agent's license¶

Automatic. The daily background job (runAgentLicenseSuspensionJob) scans for expired licenses and flips licenseSuspendedAt to the current timestamp. The agent's action endpoints start returning LICENSE_EXPIRED immediately; the agent sees the red banner on their next portal load. To override (e.g. agent with proven renewal in progress), mgmt can update the expiry date in the admin form — see License auto-suspension + renewal above.

Re-sign SOPs (out-of-date)¶

If a facility re-publishes their SOPs (edits → click Publish again), all previously-accepted agents flip to out-of-date state. They see a gold banner on their next portal load with a Re-sign affordance. The Re-sign button only appears when the agent's acceptance is genuinely out of date — once they're up to date, the button hides (avoids cluttering the UI with a redundant action).