=== Softtara Resident Management Portal ===
Contributors: softtara
Tags: resident portal, property management, work orders, maintenance, tenant portal
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 8.0
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect Residents, Technicians & Property Teams

== Description ==

**Resident Portal — Connect Residents, Technicians & Property Teams**

Resident Portal gives property teams a self-contained system for running the day-to-day work of a residential property, from a resident's first login to a technician closing out a maintenance ticket.

Residents register for their own account, land on a personal dashboard, and submit maintenance requests or general inquiries with photos or documents attached. Every request gets an automatic, human-readable ticket number and a visible status timeline, so residents always know where things stand without calling the office.

Technicians sign in to their own dashboard to see what's assigned to them, update status, and leave notes as work progresses — residents are notified automatically at each step.

Property staff manage everything from the WordPress admin: residents, technicians, and work orders each have a dedicated screen with search, filtering, sorting, and bulk actions, plus a dashboard with an at-a-glance summary and self-hosted SVG charts (no external charting service or CDN). Work order data can be exported to CSV or Excel, or opened in a clean print view, always reflecting whatever filters are currently applied.

Every automated email — registration, verification, new request confirmations, status updates, assignments, replies, and more — renders through one consistent HTML template and can be customized from Settings, including the subject line and body text of each message. Outgoing mail can optionally be routed through a custom SMTP server, with the SMTP password encrypted at rest, or queued in the background for sites with slow mail delivery.

An in-app notification bell keeps residents, technicians, and administrators up to date without relying on email alone — residents see it in their dashboard, and administrators and technicians see it in the WordPress admin bar.

A dedicated Settings screen covers company branding, per-notification on/off toggles, upload restrictions, status badge colors, and appearance — so the portal can be tailored to a property's branding and workflow without touching any code.

= Key Features =

**Resident Portal**

* Self-service resident registration with email verification
* Login, logout, and forgot/reset password flows
* A personal dashboard with request summary, quick actions, and recent activity
* Submitting a Maintenance Request or General Inquiry, with priority, category, apartment number, property area, common area, location description, and up to 5 attachments
* Paginated request history and a detail view with ticket number, current status, a visual status tracker, structured status history, an activity timeline, and attachments
* Replying directly to staff from a request's detail view
* Profile viewing and editing

**Work Order Management**

* Automatic, human-readable ticket numbers (e.g. MR-000123, GI-000045)
* A configurable status lifecycle (open, assigned, in progress, completed, closed, cancelled)
* Technician assignment, with resident and technician notifications on assignment and status changes
* Internal Notes (visible to all staff), Private Notes (visible only to the author), and resident-visible Replies
* Soft delete with a Trash view (restore or permanently delete)
* An "aging" indicator that flags unresolved requests open longer than 10 days

**Technician Dashboard**

* Overview, My Requests, request detail, and Profile views
* Updating the status of assigned requests and adding notes
* The same resident-facing notifications used for admin-initiated status changes

**Administration**

* Dedicated screens for Residents, Technicians, Work Orders, and Activity, built on WordPress's native list table with search, filters, sorting, and pagination
* A dashboard with summary statistics and self-hosted SVG charts
* Bulk actions on Residents and Work Orders
* A read-only, filterable Activity log for auditing
* Work order search across ticket number, title, description, apartment number, and resident name/email, plus Status, Priority, Type, Technician, and Date Range filters
* Export to CSV, export to a genuine .xlsx Excel file, and a print-ready view — all reflecting the current filtered/sorted results, not just the current page

**Email & Notifications**

* A shared, table-based HTML email template used across every automated message
* Editable Subject/Body for every automated email, using placeholder tokens (e.g. {resident_name}, {ticket_number}, {reply_text}), with a Reset to Default option and a live preview
* Optional custom SMTP delivery (host, port, encryption, username/password, with the password encrypted at rest), applied through WordPress's standard phpmailer_init integration, plus a Send Test Email tool
* An optional background email queue (WP-Cron based, with retry) for sites with slow mail servers, off by default
* An in-app notification bell for residents (dashboard topbar) and administrators/technicians (WordPress admin bar), with live updates, mark-as-read, and mark-all-read

**Settings**

* Company information: name, logo, and contact email/phone
* Per-notification on/off toggles for discretionary email and in-app alerts (core account emails always send)
* Upload restrictions: allowed file types and maximum upload size
* Status badge colors, customizable across both the resident and admin interfaces
* Appearance: accent color and logo placement

== Installation ==

1. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
2. Choose the Resident Portal ZIP file and click Install Now.
3. Activate the plugin. This automatically creates the required database tables, the Resident and Technician roles, default settings, and the front-end pages (Login, Register, Forgot Password, Reset Password, Resident Dashboard, Technician Dashboard).
4. Go to Resident Portal → Settings to configure your company information and other options.
5. If you want to send email through a custom mail server, configure it under Resident Portal → Email Settings and send a test email.
6. Share the Login/Register page links with your residents, and add technicians from Resident Portal → Technicians.
7. Residents can now register and submit maintenance requests; staff and technicians manage them from their respective dashboards.

No manual database setup is required, and no paid add-ons are needed.

== Frequently Asked Questions ==

= What is Resident Portal? =

Resident Portal is a WordPress plugin that gives property teams a resident self-service portal, a full work order/maintenance-request system, a Technician Dashboard, and an admin back office for managing residents, technicians, and requests.

= Who can use Resident Portal? =

Residents self-register for accounts. Technicians are added by an administrator. Site administrators manage the whole system from the WordPress admin.

= How do residents submit maintenance requests? =

From their dashboard, residents choose Maintenance Request or General Inquiry and provide details such as priority, category, apartment number, property area, common area, and a location description, with up to 5 attachments.

= Can residents track their requests? =

Yes. Each request has a unique ticket number and a detail view showing current status, a visual status tracker, a structured status history, an activity timeline, and any attachments.

= Can work orders include attachments? =

Yes, residents can attach up to 5 files when submitting a request, and staff can view them from the admin Work Orders screen.

= How do technicians access their assignments? =

Technicians log in to their own Technician Dashboard to see assigned requests, update status, and add notes.

= How are email notifications handled? =

Every automated email (registration, verification, new request confirmations, status changes, assignments, replies, and more) uses a shared HTML template. Individual discretionary notifications can be turned on or off, and the subject/body of any template can be customized from Settings.

= Does Resident Portal support SMTP? =

Yes. Resident Portal → Email Settings lets you configure a custom SMTP server, with the password encrypted at rest, and includes a Send Test Email tool. If left unconfigured, mail is sent through your site's normal mail delivery.

= Where can I configure the portal? =

Resident Portal → Settings covers company information, notification toggles, upload restrictions, status colors, and appearance. SMTP is configured on its own dedicated Resident Portal → Email Settings screen.

= How do I manage residents? =

From Resident Portal → Residents, with search, filters, sorting, pagination, and bulk actions.

= How do I manage technicians? =

From Resident Portal → Technicians, where you can add a technician (which creates their WordPress account and emails them a link to set a password) and edit their details.

= How do I manage work orders? =

From Resident Portal → Work Orders, where you can view, filter, search, assign, update status, add notes, reply to the resident, and delete (to Trash, with restore or permanent delete available).

= How do I export work order information? =

From the Work Orders screen, use Export CSV, Export Excel, or Print View. All three reflect the currently applied search, filters, and sort, across the full result set rather than only the current page.

= What happens if the plugin is deactivated? =

Deactivating leaves all data, roles, and settings intact. The plugin simply stops running until reactivated.

= What happens if the plugin is uninstalled? =

Deleting the plugin from the Plugins screen removes its database tables, custom roles and capabilities, and its stored options. The front-end pages it created (Login, Register, dashboards, etc.) are left in place, since WordPress content is never silently deleted.

= Does this plugin need any paid add-ons or manual database setup? =

No. Everything required — database tables, roles, capabilities, pages, and default settings — is created automatically on activation.

= What PHP/WordPress versions are required? =

PHP 8.0+ and WordPress 6.0+.

== Screenshots ==

1. Resident dashboard with request summary and recent activity.
2. Submitting a maintenance request with attachments.
3. Work order detail view with status tracker and history.
4. Technician dashboard showing assigned requests.
5. Admin Work Orders screen with search, filters, and bulk actions.
6. Admin Residents management screen.
7. Admin Technicians management screen.
8. Admin Activity log.
9. Email Settings screen with SMTP configuration.
10. General Settings screen.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.

== Privacy ==

Resident Portal stores the data needed to operate a resident/work-order portal on your own WordPress database:

* **User information** — for residents and technicians: name, email, phone, apartment number (residents), profile photo, and the linked WordPress user account.
* **Work order information** — request type, priority, category, location details, description, status, and assignment history.
* **Attachments** — files uploaded by residents when submitting a request, validated by their actual file content rather than the browser-supplied file type.
* **Activity data** — a log of actions taken on residents, technicians, and work orders, used for the admin Activity screen.
* **Email-related information** — the content of outgoing notification emails, and, if the optional background email queue is enabled, a temporary record of queued messages. If a custom SMTP server is configured, its password is encrypted before being stored.

Resident Portal does not send data to any third-party analytics or tracking service. If a site administrator configures a custom SMTP server under Email Settings, outgoing email is transmitted through that administrator-selected SMTP provider rather than the server's default mail transport; no other external service is contacted by the plugin.

== External Services ==

Resident Portal does not connect to any external API or third-party service by default.

If a site administrator chooses to configure a custom SMTP server under Resident Portal → Email Settings, outgoing plugin emails (such as verification, work order, and status-update notifications) are transmitted through that administrator-specified SMTP provider instead of the server's default mail transport. This is entirely optional, off unless configured, and uses whichever SMTP provider the administrator selects — Resident Portal itself does not send data to any specific third party. Sending email through SMTP is subject to that provider's own terms of service and privacy policy.

The admin dashboard's charts are rendered as self-hosted SVG markup generated by PHP; no external charting library or CDN is used.
