# 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.