alla-allaos-fullstack/plans/mvp-plan.md

IT Asset Governance MVP Plan For This Dashboard Repo

Summary

Implement the IT Center MVP as a new app-owned feature set inside the existing Next.js dashboard, using the current architecture:

• organizations stays the tenant boundary and maps to Company
• business roles (IT Admin, Helpdesk, Infrastructure, Application, Auditor, Viewer) are modeled as workspace-scoped permission bundles, not as replacements for systemRole
• first release is a Core Registry MVP:
  • master data
  • asset register
  • asset lifecycle transactions: assign, transfer, return, repair
  • movement history
  • basic dashboard summaries and risk widgets

This should be built as a new feature family, following the migrated products and users patterns: feature types -> service -> queries/mutations -> route handlers -> Drizzle.

Key Changes

1. Domain model and tenancy alignment

• Treat organization as Company; keep the existing table and session/org-switcher model.
• Add company-scoped master data tables under the selected organization:
  • sites
  • departments
  • locations
  • employees
• Add asset domain tables:
  • assets
  • asset_movements
  • asset_repairs
• Keep Asset UID immutable and system-generated.
• Keep Asset Code mutable and history-tracked through movement events.
• Store current state on assets; store every lifecycle change as an append-only movement row.

2. RBAC model for IT Center

• Keep current auth layers:
  • users.systemRole for global authority
  • workspace membership and active workspace session context for tenant authority
• Add a workspace-scoped business-role profile to membership-derived access:
  • either a new membership field like businessRole
  • or a dedicated per-organization user-access table linked to user + organization
• Recommended canonical permissions:
  • master_data:manage
  • asset:read
  • asset:create
  • asset:update
  • asset:assign
  • asset:transfer
  • asset:return
  • asset:repair
  • asset:audit
  • report:read
• Map business roles to permission bundles:
  • IT Admin: full company-scoped access
  • Helpdesk: assign/transfer/return/read
  • Infrastructure: hardware, warranty, EOS/EOL/EOP, repair
  • Application: software/license/subscription assets
  • Auditor: read, audit, export/report read
  • Viewer: read-only
• Keep server-side enforcement in route handlers and page guards; nav remains UX-only.

3. Feature/module structure in this repo

Create a new feature family under src/features/assets/ and sibling dashboard routes under src/app/dashboard/:

• src/features/assets/
  • api/types.ts
  • api/service.ts
  • api/queries.ts
  • api/mutations.ts
  • components/
  • schemas/
• Add dashboard routes:
  • /dashboard/assets
  • /dashboard/assets/[assetId]
  • /dashboard/assets/assign
  • /dashboard/assets/transfer
  • /dashboard/assets/return
  • /dashboard/assets/repair
  • /dashboard/assets/history
• Add master-data routes/pages, either grouped under /dashboard/master-data/* or /dashboard/assets/settings/*
  • sites
  • departments
  • locations
  • employees
• Reuse existing patterns:
  • PageContainer
  • TanStack Table
  • TanStack Form + Zod
  • React Query prefetch + HydrationBoundary
  • route handlers in src/app/api/**

4. Backend and workflow design

Implement route handlers for:

• master data CRUD
• asset CRUD
• lifecycle actions as explicit endpoints, not generic updates:
  • POST /api/assets/[id]/assign
  • POST /api/assets/[id]/transfer
  • POST /api/assets/[id]/return
  • POST /api/assets/[id]/repair
• movement history listing:
  • GET /api/assets/[id]/movements
• dashboard summary endpoints:
  • totals by status
  • warranty risk counts
  • lifecycle risk counts
  • data-quality counts

Behavior rules to lock in:

• assign updates current owner/location fields and inserts ASSIGN movement
• transfer updates user/department/location/code as needed and inserts one TRANSFER movement with old/new values
• return updates status to one of IN_STOCK | REPAIR | RETIRED and inserts RETURN
• repair inserts repair history and optionally sets status REPAIR
• every lifecycle mutation must write a movement record in the same server transaction

5. UI/navigation and documentation alignment

• Add new sidebar section for Assets, with visibility based on asset permissions.
• Keep Workspaces semantics unchanged; they still represent company switching.
• Add pages in this order for the MVP:
  1. asset register/list
  2. asset create/edit
  3. assign
  4. transfer
  5. return
  6. repair
  7. movement history
  8. dashboard summary widgets
  9. master data CRUD pages
• Update stale docs while implementing:
  • docs/nav-rbac.md is legacy Clerk-oriented and should be rewritten to match Auth.js + current session fields
  • add a new domain glossary doc, preferably CONTEXT.md, to define:
    • Organization = Company
    • Site
    • Department
    • Location
    • Employee
    • Asset UID
    • Asset Code
    • Movement
    • Business Role

Public APIs / Types

• Add new feature contracts in src/features/assets/api/types.ts:
  • Asset
  • AssetFilters
  • AssetsResponse
  • AssetMutationPayload
  • AssetAssignmentPayload
  • AssetTransferPayload
  • AssetReturnPayload
  • AssetRepairPayload
  • AssetMovement
  • AssetDashboardSummary
• Add master data contracts:
  • Site, Department, Location, Employee
• Extend workspace-scoped access modeling so session-backed access checks can resolve:
  • current workspace business role
  • current workspace asset permissions
• Do not overload systemRole with business roles.

Test Plan

• Auth and tenancy:
  • active organization scopes all master data and assets to one company
  • switching organization changes visible assets and master data
• RBAC:
  • IT Admin can do all asset operations in the active workspace
  • Helpdesk can assign/transfer/return but cannot manage system settings
  • Infrastructure can repair and manage lifecycle data
  • Auditor can read and audit but cannot mutate assets
  • Viewer cannot access transactional pages
• Asset lifecycle:
  • create asset generates immutable Asset UID
  • transfer can change owner, department, location, and asset code
  • return updates status and writes movement
  • repair writes repair history and status changes correctly
• History and risk:
  • every lifecycle action creates a movement row
  • warranty/EOS/EOL/EOP widgets count the right assets
  • data-quality widgets flag missing user/location/serial/warranty
• UI:
  • new nav items appear only for permitted roles
  • asset list, detail, and transaction flows follow the repo’s React Query hydration pattern

Assumptions and Defaults

• organizations remains the canonical tenant table and means Company.
• MVP phase 1 is the Core Registry only; Audit, advanced Reports, mobile scanning, approvals, and external integrations stay phase 2+.
• Business roles are workspace-scoped permission bundles layered on top of the current Auth.js + membership model.
• Hardware and software assets can share one assets table in MVP, using assetType and assetCategory fields, unless later scale forces separation.
• Movement history is the audit trail of lifecycle changes; it is not full event sourcing.