AttuneLogic Platform Consolidation & UX Improvement Plan

Overview

AttuneLogic has reached the stage where most foundational pieces (security, TypeScript, testing, scheduling, multi-industry support) are in place across:

• @attunelogic-api – Node/Express/Mongoose, multi-tenant, multi-industry backend
• @attunelogic-service – Web dispatch and operations app
• @attunelogic-mobile – Field worker app (drivers/technicians)

The next phase is not “add more features”, but to consolidate, simplify, and align what already exists so the platform feels:

• Robust and predictable for users
• Easier to extend safely for developers
• Consistent across API, web, and mobile

This document describes how to get from “many partially overlapping features” to a coherent, user-focused platform.

Goals

1. User Experience
   • Make 2–3 core workflows per industry feel smooth and reliable end-to-end.
   • Remove or hide confusing, half-finished features from day-to-day usage.
2. Platform Consistency
   • Standardize cross-cutting concerns (auth, tenancy, config, date/time, errors).
   • Ensure API, Service, and Mobile follow the same “laws of physics”.
3. Developer Experience
   • Reduce the surface area of “special cases”.
   • Make new features plug into existing patterns instead of inventing their own.
4. Safety & Stability
   • Harden what exists before adding new complexity (routing, HOS, analytics, etc.).
   • Use configuration and feature flags instead of forks or ad-hoc toggles.

Scope & Assumptions

• Industries: Trucking and Service/Repair (Plumbing, HVAC, Electrical, etc.).
• Tenancy: Multi-tenant, with parentCompany and app type (trucking vs serviceRepair) driving behavior.
• Foundation Layer: Security, TypeScript, testing, and basic documentation are assumed to be in place and working (see API MASTER_ROADMAP).

The recommendations below are ordered. Each phase builds on the previous one.

Phase 1 – Focus on Flagship Workflows

Before touching architecture or adding features, narrow the target.

1.1 Choose core workflows

For each industry, select up to two flagship end-to-end journeys:

• Trucking
  • Quote → Job/Load creation → Dispatch/scheduling → In-transit → Delivered → Invoiced.
• Service/Repair
  • Job booking (internal or customer-facing) → Technician scheduling → On-site work → Completion + approval → Payment.

These must:

• Cross API + Service + Mobile.
• Be achievable with existing primitives (jobs/legs, scheduler, equipment, invoices, PDFs).
• Represent the highest value for real customers.

1.2 Freeze non-essential expansion

For this consolidation phase:

• Do not start new modules (e.g., advanced analytics, full HOS stack, marketplace integrations).
• Treat everything not required for the chosen workflows as:
  • Production – actively supported and visible.
  • Beta – visible but clearly labeled and limited in scope.
  • Experimental/Hidden – behind flags or removed from navigation.

The goal is to reduce the active surface area so we can polish what matters most.

Phase 2 – Standardize Cross-Cutting Platform Behaviors

To make AttuneLogic feel coherent, standardize a few core “laws” across API, Service, and Mobile.

2.1 Configuration & feature flags

Backend (API)

• Use the existing customer-configs system + useCustomerConfig hook as the single source of truth for:
  • Enabled modules (Jobs, Dispatch, Equipment, Inventory, Billing, Customer Portal, etc.).
  • Industry type (trucking vs serviceRepair) and operation type (local, regional, long-haul).
  • Key feature toggles (e.g., “mobileInventoryEnabled”, “customerPortalEnabled”).

Frontend (Service + Mobile)

• Expose a consistent customer config endpoint.
• Create thin hooks:
  • Service: useConfig (already exists) unified with backend semantics.
  • Mobile: useConfig (already exists) reading the same model.
• Derive navigation and conditional UI strictly from config:
  • If a module is disabled, hide its navigation and entry points.
  • If a feature is beta, show a badge and avoid using it in critical flows.

This makes feature rollout predictable and avoids UI/API mismatches.

2.2 Auth, tenancy, and roles

Canonical model

• Define a single conceptual model:
  • user: id, roles, permissions, parentCompany, appType.
  • parentCompany: tenant root, with configuration and branding.
  • roles/permissions: capability-oriented (e.g., dispatch:edit, jobs:view, billing:approve).

API

• Enforce via existing middlewares:
  • verifyToken (authentication + JWT claims),
  • verifyParent (tenant isolation),
  • verifyRole (RBAC).
• Gradually move from simple role lists to a permission matrix, but keep backward compatibility.

Service & Mobile

• Standardize useAuth return shape across projects:
  • Always expose user, roles, parentCompany, appType, and helper functions like hasRole and can(permission).
• Use a shared RBAC helper (web + mobile):
  • e.g., can(user, "dispatch:edit") instead of ad-hoc checks.

Result: every feature integrates with one RBAC pattern, instead of bespoke permission logic.

2.3 Date/time & scheduling

Source of truth

• Treat the web APPOINTMENT_DATETIME_HANDLING.md behavior as the canonical specification:
  • Full Date objects with time are always passed.
  • 12‑hour AM/PM display, correct local → UTC conversion.
  • Business hours and HOS-aware scheduling are respected.

API

• Validate and normalize scheduling inputs server-side:
  • Reject obviously invalid times for a given operation type.
  • Normalize to a single ISO8601 format across endpoints.

Service & Mobile

• Mobile date/time pickers must be aligned with web behavior:
  • Same AM/PM convention and timezone handling.
  • Same mapping between appointment time and schedule views.

This prevents “2:00 PM” meaning one thing on mobile and another on the web/API.

2.4 Errors and response contracts

For the core workflows, define a stable API contract:

• Consistent envelope (e.g., { status, data, error }).
• Clear, user-friendly error codes/messages for common failure modes (auth, validation, conflicts).
• Documented in both developer docs and customer-facing docs.

Service & Mobile should:

• Use shared TypeScript definitions (or generated types) for core entities.
• Display errors consistently with clear guidance (retry? fix data? contact support?).

Phase 3 – Consolidate and Simplify Existing Features

With standards in place, simplify what’s already live.

3.1 Module audit

For each major module (Jobs, Dispatch/Scheduler, Equipment, Inventory, Customer Portal, Payments, HOS, Analytics):

• Classify it as:
  • Production – stable, used by customers.
  • Beta – works for some, but not fully general.
  • Experimental – partially implemented or commented out.
• For each classification:
  • Production: keep visible, fix bugs, avoid breaking changes.
  • Beta: label in UI; avoid using in flagship workflows until hardened.
  • Experimental: hide or protect behind feature flags; do not route users there by default.

3.2 Navigation and entry points

• Clean up navigation on Service and Mobile:
  • Remove or hide links to unfinished flows.
  • Avoid multiple entry points to the same function with slightly different behavior.
• Aim for:
  • One primary list per domain (Jobs, Schedule, Equipment).
  • One detail view per entity used across the app.
  • A consistent pattern: list → filter/search → details → edit → back.

3.3 Refactor into clear domain services

On the API:

• Group logic into a small set of domain services:
  • jobService, scheduleService, equipmentService, billingService, etc.
• Keep controllers thin:
  • Auth + validation + calling the domain service.

On the frontends:

• For each domain, have:
  • A focused RTK Query slice / API module.
  • A small group of hooks/components that encapsulate the complexity (e.g., useJobs, useSchedule).

This makes adding new functionality to an existing domain less risky and more discoverable.

Phase 4 – Deep Polish of Core Workflows

For the selected flagship workflows, do a full experience pass.

4.1 Map the end-to-end journey

For each workflow:

• Map every step and screen across:
  • Service (dispatcher/office),
  • Mobile (driver/technician),
  • API endpoints involved.
• Identify:
  • Redundant forms or steps,
  • Confusing terminology (e.g., load vs job),
  • Places where users are forced to jump between modules.

4.2 Fix UX gaps

Focus on:

• Clear, inline validations instead of cryptic API errors.
• Consistent naming and labels across web + mobile.
• Predictable navigation (no dead-ends or confusing back behavior).
• Reasonable defaults derived from config (industry, operation type, customer preferences).

Every small UX fix compounds into a much more “robust” feel for users.

4.3 Reliability & performance

For the lists and views people live in every day (dispatch board, job tables, today’s jobs, schedule):

• Ensure proper indexes for the underlying queries.
• Avoid heavy N+1 patterns.
• Add pagination/virtualization where needed.
• Consider simple caching for:
  • Customer configuration,
  • Common lookups (service types, locations, equipment types),
  • User profile / permissions.

Phase 5 – Observability Around User Workflows

Beyond logs and metrics, track what users are doing along the core journeys.

5.1 Business event logging

On the API:

• Emit structured events for key state transitions:
  • Job created, scheduled, dispatched, completed, invoiced, cancelled.
  • Equipment created/assigned/retired.
  • Portal actions (invitation sent, job booked).
• Include:
  • parentCompany, appType, userId, and relevant IDs.

These can be stored in Mongo (or a dedicated log sink) and used for:

• Basic reporting.
• Debugging cross-platform issues.
• Understanding real usage patterns.

5.2 Frontend analytics (lightweight)

On Service and Mobile:

• Track:
  • Screen views for core modules.
  • Form submissions for key workflows.
  • Error surfaces (where users encounter validation/server errors).

Use this to decide:

• Which screens need UX work.
• Which modules are safe to invest in next (based on adoption).

Phase 6 – Introduce Advanced Themes One at a Time

Once the core feels solid, re-open advanced roadmap items — but serially, not in parallel.

Candidate “themes”:

1. Advanced routing Phase 1
   • Replace fixed-speed calculations with dynamic travel times and basic traffic-aware ETAs.
   • Keep scope limited to the dispatch board + related mobile views.
2. RBAC & data protection 2.0
   • Permission matrix in Mongo, UI for role/permission management.
   • Field-level encryption for sensitive data.
3. Offline-first mobile
   • Offline job creation and status updates.
   • Background synchronization with conflict resolution.

For each theme:

• Define clear API contracts and frontend expectations.
• Integrate with the configuration/feature flag system.
• Roll out to a small set of tenants first (beta), then expand.

Implementation Checklist (Per Repo)

API (@attunelogic-api)

• Harden customer-configs + useCustomerConfig as the single feature-flag/config system.
• Normalize auth + RBAC middleware and document permission patterns.
• Finalize scheduling/date/time validation contracts for core endpoints.
• Refactor into clear domain services (jobs, schedule, equipment, billing).
• Implement structured business event logging for key state changes.

Service (@attunelogic-service)

• Align useAuth and useConfig with API semantics.
• Clean navigation to center on flagship workflows; hide or label beta modules.
• Ensure scheduler + appointment handling follow the canonical time behavior.
• Simplify and standardize job/leg/equipment flows (list → details → edit).
• Add lightweight analytics around dispatch and job management screens.

Mobile (@attunelogic-mobile)

• Align mobile date/time and scheduling behavior with web + API.
• Use config flags to control visibility of inventory, portal, and experimental modules.
• Complete the job creation and execution flow for chosen industries.
• Stabilize equipment and dashboard experiences around daily workflows.
• Add minimal usage/error tracking on core screens.

---

Last Updated: January 2025
Version: 1.0
Maintainer: Platform Engineering / Architecture