# Miliki Portal Revamp — Implementation Plan

Status: active implementation. The foundation and first role workspaces described below were implemented on 30 September 2026. Later operational workstreams remain tracked in the delivery table and must not be treated as complete until their acceptance gates pass.

### Implemented foundation (30 September 2026)

- Role-aware dashboards for Property Owner and Customer Support, while retaining the existing SuperAdmin analytics foundation.
- Explicit owner, support-assignment, and SuperAdmin query scoping across projects, orders, customers, global search, leads, and cases.
- Indexed workflow schema for staff assignments, leads/activity, support cases/events, follow-up tasks, approval requests, and status history.
- Server-paginated plot and order lists, scoped search, eager loading, streamed exports, and short-lived aggregate caching for high-volume reads.
- SuperAdmin staff portfolio assignment and project-publication approval queues.
- Lead, follow-up, case/SLA, timeline, and status-transition workflows with audit-friendly history.
- White/green/orange workspace shell and a licensed, self-hosted Google Sans Flex WOFF2 subset.
- CI tests before deployment and lock-file-only production dependency installation.

Still pending from the longer roadmap: bulk plot-import preview/error reporting, finance reconciliation, consolidated customer timeline, transfer-management workspace, statement generation, feature-flagged rollout, and the optional rental track. Those require product/accounting decisions and are intentionally not represented as completed features.

## 1. Outcome and scope

Build one coherent operations portal with three role-specific workspaces: Property Owner, Customer Support, and SuperAdmin. The first release will support the business already represented in Miliki: property-owner onboarding, project and plot inventory, visits, sales, payments, and post-purchase land-transfer progress. It will not label plot sales as rental management. If lease, tenant, rent, and maintenance workflows are required, model and deliver them as a separate, explicitly approved product track after the plot-sales foundation is stable.

The redesign should preserve Miliki's current green and orange accents, use white as the dominant surface, and use Google Sans Flex throughout. It should combine—not discard—the SuperAdmin dashboard work already present.

### Success criteria

- Every user lands in a useful dashboard for their role, with a clear next action.
- An owner can manage projects and plot inventory and understand sales, cash collected, balances, and transfer progress without asking staff for routine updates.
- A support agent can find a customer, see their complete sales context, record contact, and schedule a follow-up from one workspace.
- SuperAdmin can see cross-portfolio health, approvals, service backlog, and payment exceptions, then drill into the underlying records.
- A user cannot access another owner's data through a URL, search, export, AJAX request, or background job.
- Lists remain responsive for projects with 1,000+ plots; metrics have documented definitions and reconcile to source records.

## 2. Baseline and what to reuse

The portal is a Laravel 9, Blade, Bootstrap, jQuery/DataTables application with Spatie permissions. The separate `propertyfin` Laravel API serves customer/mini-app operations. They share business concepts and must use a documented contract for customers, projects, plots, orders, payments, and status changes; verify the production data ownership and integration topology before changing write paths.

Retain and improve these existing features:

| Existing portal capability | Revamp treatment |
| --- | --- |
| SuperAdmin async statistics, ApexCharts, recent orders/activity, global search, notifications, and date range | Keep as the dashboard foundation; correct metric definitions, errors, loading behavior, permissions, and layout. |
| Owner and project create/edit flows, including draft states | Put in guided onboarding and project workspaces rather than rebuilding the forms blindly. |
| Project images, maps, terms, plot import/pricing, visits, orders, and post-purchase status | Bring into one project lifecycle and plot/customer timelines. |
| Verified owner bank accounts | Reuse approval and document handling; expose payout context only when the accounting source is confirmed. |
| Permission roles and audit records | Formalize a role/capability matrix and a consistent audit trail. |

Current issues to resolve in the foundation: support users can log in but have no role-specific dashboard; ticket routes point to missing views; some owner/order and customer-search paths are not safely scoped; some dashboard and list queries happen inside Blade; legacy telco pages and unused menus obscure the product. Older project notes are useful context, but implementation decisions must be checked against current code and production behavior.

### Code starting points

- Portal: `routes/web.php`, `app/Http/Controllers/DashboardController.php`, `app/Http/Controllers/Property/*`, `app/Http/Controllers/CustomerController.php`.
- UI: `resources/views/mainlayout/layout.blade.php`, `left_navbar.blade.php`, `resources/views/superadmin/dashboard.blade.php`, `resources/views/partials/{superadmin,propertyowner}/dashboard.blade.php`, `public/web/assets/js/pages/dashboard.init.js`, `public/web/assets/css/miliki-theme.css`.
- API: `propertyfin/routes/api.php`, `propertyfin/app/Services/MiniAppReadService.php`, and the order/payment services and tests.

## 3. Benchmark translation and visual specification

The supplied references are inspiration, not a specification to copy. The first shows a property detail page, location overview, reviews queue, and analytics; the second shows a calm, white dashboard with compact navigation, search, a prominent trend chart, recent payments, and listing cards. For Miliki, translate these patterns into project/plot operations and sales follow-up. Do **not** copy rent, tenants, or generic review approvals into the initial plot-sales navigation unless those workflows are confirmed.

### Shell and hierarchy

1. Use a primarily white sidebar and card surfaces over a very light neutral content canvas. Use Miliki green for the active navigation state, primary buttons, chart highlights, and key links; use orange sparingly for attention, pending work, and one secondary data series. Do not use color alone to communicate status.
2. Keep the top bar compact: role/workspace context, global search, notifications, help, and profile. Date range and export belong in the relevant dashboard/page header, not on every screen.
3. Use a consistent page hierarchy: title + explanatory subtitle + primary action; filters; essential KPIs; one main trend or work queue; supporting lists/cards. Prefer actionable exceptions over rows of decorative charts.
4. Use real Miliki project imagery and plot metadata. On desktop, show rich project cards where visual scanning helps; use dense, paginated tables for plot inventory, orders, cases, and reconciliation.
5. Keep the shell responsive: collapsible sidebar at tablet widths, filter drawers and stacked cards on phones, readable tables with prioritized columns or horizontal scroll, and no clipped actions.

### Design tokens and components

- Start from `miliki-theme.css`: primary `#0B5E42`, accent `#F2941B`, light surfaces, existing semantic success/warning/danger tokens. Consolidate page-specific CSS into documented tokens rather than stacking overrides.
- Use a spacing scale, consistent radii, borders, focus rings, typography sizes, table density, and chart palette. Build reusable Blade components/partials for page header, metric card, status badge, filter bar, empty state, skeleton, alert, modal/drawer, timeline item, and confirmation prompt.
- Replace the current bundled Google Sans TTF references with a properly licensed, self-hosted Google Sans Flex webfont, preferably optimized WOFF2 with `font-display: swap`; verify weight/character coverage for English and Swahili, and retain a system-font fallback. Avoid fetching a font from a third-party service at runtime if it is not necessary.
- Give every chart a clear title, units, date range, legend, accessible text/table equivalent, empty state, and drill-down. Label money as TZS; do not display sample values or misleading percentage deltas.
- Target WCAG 2.2 AA for keyboard focus, form labels, contrast, error messaging, and non-color status cues. Test the English/Swahili labels and long project names.

### Dashboard compositions

- **Owner:** portfolio health, available/reserved/sold plots, collected vs outstanding TZS, upcoming visits, expiring reservations, overdue payments, transfer milestones, and recent activity. First actions: add project, import plots, review enquiry, view statement.
- **Support:** assigned leads/cases, due and overdue follow-ups, first-response breaches, today's visits, payment exceptions requiring contact, and a recent-customer list. The main module is a prioritized queue, not a revenue chart.
- **SuperAdmin:** cross-owner sales and collections, inventory by status/project, owner/project approvals, support SLA, unmatched/failed payments, stalled transfers, and drill-down tables. Preserve the existing widget-loading pattern, but make time-range behavior and metric definitions consistent.

## 4. Role journeys and navigation

| Role | Primary navigation | Minimum end-to-end journey |
| --- | --- | --- |
| Property Owner | Overview; Projects; Plots; Leads & Visits; Orders & Collections; Transfers; Documents & Statements; Team; Settings | Complete profile and verified bank details → create draft project → upload and validate plots/prices → request publication → handle enquiry/visit → monitor reservation/order/payment → track transfer → download statement. |
| Customer Support | My Work; Leads; Customers; Visits; Cases; Orders & Payments (read/assist); Knowledge Base | Receive or create lead → identify customer and plot → contact customer → record outcome and next task → arrange visit or escalate issue → follow reservation/payment/transfer → resolve case. |
| SuperAdmin | Overview; Approval Queue; Owners; Projects & Inventory; Sales; Finance Exceptions; Support; Transfers; Reports; Users & Access; Settings & Audit | Review owner/project request → monitor live portfolio → investigate exception → assign/escalate → approve permitted changes → audit outcome. |

Support agents need a configurable scope: assigned owner/project/channel, rather than unrestricted access to all customer and financial records. Owners may have team members with narrower permissions (inventory, sales, finance, read-only). SuperAdmin should use least-privilege capabilities for sensitive actions rather than one blanket permission in the long term.

## 5. Functional workstreams

### A. Owner operations

- Guided onboarding with draft/submit/approved/rejected states, missing-document checklist, verification timestamps, and reasoned feedback.
- Project workspace with overview, media/maps, publication readiness, order settings, visit availability, pricing, and activity history.
- Plot inventory: bulk import preview, row validation and duplicate detection, error download, status and price changes with audit trail, server-side search by plot number/land use/price/status, saved filters, and safe bulk actions. Prevent double booking and selling unavailable plots.
- Sales and collections: enquiry/visit pipeline, reservations and expiry, orders, installment schedules, received payments, outstanding balances, and exception visibility. Clearly separate order value from settled collections and payout eligibility.
- Transfer tracker: configurable milestones, owner/customer-visible status, required documents, assigned handler, due dates, and history.
- Statements and reports: project/period filters, reproducible CSV/PDF exports, and reconciliation before showing payout figures.

### B. Customer support and sales follow-up

- A canonical customer workspace joined to the buyer records used by the mini-app, not a second isolated address book.
- Lead record with source, interest (project/plot), stage, assignee, contact consent, next action/due time, duplicate detection, and close reason.
- Timeline of calls, messages, visits, bookings, orders, payments, cases, and transfer updates; distinguish internal notes from customer-visible messages.
- Follow-up queue with reminders, overdue/escalation rules, assignment/reassignment history, visit scheduling, templates, and task completion outcomes.
- Case/ticket model for problems (payment mismatch, booking, documentation, transfer delay, complaint) with priority, owner, status, SLA clock, escalation, and resolution reason.
- Search by phone, name, order reference, project, plot number, and case/lead ID. Search results must honor role scope and mask sensitive fields where appropriate.

### C. SuperAdmin and governance

- Approval queues for owners, bank accounts, project publication, and exceptional inventory/price changes; record decision, actor, reason, and time.
- Cross-portfolio dashboards with defined filters and consistent TZS calculations.
- Payment reconciliation queue with gateway reference, internal transaction, order, amount, status, age, and documented resolution. Never silently edit or delete historical payment evidence.
- Support supervision: workload, response/resolution compliance, aging, conversion, reopen rate, and coaching drill-downs.
- Managed status/configuration catalogs; roles and permission templates; audit/event search; owner/project assignment and safe impersonation only if approved and fully audited.

## 6. Data, architecture, and security

### Domain and ownership decisions first

Map current `users`/customer identity, `property_owners`, `properties`, `property_plots`, pricing, bookings/visits, orders, transactions, notifications, and post-purchase statuses in both repos. Decide which service is authoritative for each write. Prefer adding a versioned portal-to-API contract over directly duplicating order/payment rules in two applications. Reuse existing IDs; provide a migration/backfill plan for legacy records; preserve auditability and avoid destructive cleanup in the same release as new features.

Likely new entities: `leads`, `lead_activities`, `follow_up_tasks`, `support_cases`, `case_events/messages`, `staff_assignments`, `approval_requests`, and explicit state-transition history. Define uniqueness, foreign keys, indexes, retention rules, and PII boundaries before migrations. Rental-only entities (units, tenants, leases, rent schedules, maintenance work orders) are outside the initial schema.

### Application boundaries

- Introduce route-level `auth` and explicit capability middleware, then resource policies for every owner/project/customer/order/case/statement action. Scope list queries before pagination, search, and export. Add tests for cross-owner and cross-channel access. Hiding a sidebar link is not authorization.
- Move query and workflow logic out of Blade into small application services/query objects/Form Requests. Use explicit workflow transitions for project publication, reservation, order, case, approval, and transfer states.
- Keep payment callbacks idempotent and server-authoritative. Use transactions/locking for plot reservation and payment state changes. Use queues with retry and failure visibility for imports, notifications, exports, and external callbacks.
- Use paginated indexed queries for large inventory, orders, and case queues; load dashboard modules independently; avoid N+1 joins and eager-loading entire portfolios. Cache only stable aggregates with explicit invalidation, not sensitive or rapidly changing payment state by default.
- Define one search service that normalizes phone/reference input, supports exact ID/reference match before partial search, groups OR conditions correctly, debounces UI calls, enforces minimum query lengths, limits results, and applies role scope before ranking.
- Use structured error logging, correlation IDs for critical workflows, audit events for sensitive changes, and operational alerts for failed jobs/callbacks. CI must run lint/build/tests before deployment; feature-flag the new shell and modules for progressive rollout.

## 7. Delivery phases and acceptance gates

These are ordered work packages, not calendar promises. Estimate sprint duration after Phase 0 confirms staffing, production data quality, and integration ownership.

| Phase | Implementation | Acceptance gate |
| --- | --- | --- |
| **0 — Discovery and baseline** | Journey workshops; inventory existing routes/screens/data; benchmark review; permissions matrix; KPI dictionary; performance and accessibility baseline; API ownership map; confirm plot-sales vs rental scope. | Signed-off flows, wireframes, technical decisions, backlog, and measurable baseline. |
| **1 — Foundation and safety** | Fix known owner-order and customer-search scoping; route/policy protection; role/capability seeders; state definitions; regression tests; CI gate; design tokens and shared shell behind a flag. | Cross-owner/unauthorized access tests pass; existing workflows still pass; shell works on desktop/mobile. |
| **2 — SuperAdmin dashboard consolidation** | Reuse existing widgets/search/notifications/date range; correct calculations, drill-downs, loading/error states, exports, and visual hierarchy. Add approval/exception summaries. | Cards and charts reconcile to filtered source records; no dead quick actions; accessible loading and errors. |
| **3 — Owner MVP** | Owner home; onboarding/project workspace; fast plot inventory/import; visits/orders/collections/transfer read views; statements. | An owner completes the core project-to-sale monitoring journey with their own data only; 1,000+ plot test remains responsive. |
| **4 — Support MVP** | Support home, canonical customer lookup/timeline, leads, follow-ups, cases, ownership/escalation, SLA indicators, visit and order context. | Every lead/case can be assigned, followed, escalated, and closed with an audit trail; support scope tests pass. |
| **5 — Admin operations and rollout** | Approval queues, finance exceptions, cross-role analytics, transfer oversight, audit/configuration, documentation and training. Pilot by role, then expand. | Operational reports reconcile, pilot feedback is addressed, rollback path tested, legacy routes retired or redirected safely. |
| **6 — Optional rental track** | Only after scope approval: separate rental domain and UX for units, tenants, leases, rent, expenses, maintenance, and owner statements. | Rental accounting and workflow rules are signed off before implementation. |

Implement each phase in vertical slices: data/policy → endpoint/query → UI → automated tests → role UAT → staged release. Avoid a single big-bang redesign.

## 8. Verification and non-functional requirements

- **Functional tests:** owner isolation, support assignment scope, project/plot state changes, duplicate import rows, reservation races, order/payment reconciliation, follow-up SLA, audit history, export permissions, and dashboard metric definitions.
- **UI tests:** all three role homes, search/filters, empty/loading/error states, long names, small screens, keyboard navigation, screen reader labels, and English/Swahili content.
- **Performance:** measure baseline first, then agree targets for dashboard first useful paint, search response, and a filtered 1,000+ plot page; capture query count, p95 latency, and database plans in CI/staging. No full-table client-side DataTables for large datasets.
- **Data checks:** compare historical totals and sampled records before/after each migration; reconcile order, transaction, and payout aggregates; do not infer payout from order status alone.
- **Release safety:** seeded test roles, staging with production-shaped anonymized data, feature flags, backward-compatible migrations, backup/rollback instructions, monitored pilot, and post-release review.

## 9. Decisions needed before implementation

1. Does “property management” in this release include rentals/leases/maintenance, or only land projects and plot sales? The plan assumes the latter first.
2. Which application/database is authoritative for customer identity, plot availability, orders, payment confirmation, and transfer milestones?
3. Which support channels are in scope initially (phone, WhatsApp, email, mini-app), and which are integrated versus manually logged? What response hours and escalation policy apply?
4. What approvals may owners perform themselves, and which require Miliki staff? Who can view detailed customer PII and finance data?
5. Which owner statements/payout figures are legally and operationally reliable today, and what reconciliation process establishes them?

### Reference principles

- Owner visibility and self-service: https://www.appfolio.com/property-management-owner-experience
- Support response and resolution policies: https://support.zendesk.com/hc/en-us/articles/4408829459866-Defining-SLA-policies
- Authorization: https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html
- Accessibility: https://www.w3.org/WAI/WCAG22/quickref/
- Google Sans Flex source and license: https://github.com/googlefonts/googlesans-flex