alla-tms/docs/REFRACTOR_REPORT.md

Refactor Report

Generated from plans/rule-ai.md.

Canonical Reference

Primary canonical feature: training-records

Why:

• Uses Route Handlers plus Drizzle.
• Has feature API contracts, services, queries, and mutations.
• Uses server prefetch and TanStack Query hydration.
• Uses DataTable, DataTableToolbar, DataTablePagination, and row action menus.
• Uses TanStack Form plus Zod.
• Includes upload and review flows.
• Enforces role-aware behavior.

Secondary references:

• employee-directory for responsive table tuning and custom toolbar behavior.
• announcements for content publishing and lightweight state transitions.
• audit-logs for read-only table pattern.

Findings

Announcements

Status: partially off-pattern.

Findings:

• Uses manual Pagination rather than DataTablePagination.
• Uses card list layout, which may be acceptable for content feeds but should not be copied for data tables.

Recommended refactor:

• Keep card layout if announcements are intentionally content-first.
• If a management table is needed, add a DataTable-based management view instead of extending manual pagination.

Notifications

Status: partially off-pattern.

Findings:

• Uses manual pagination in notifications-page.tsx.
• Should be reviewed if notifications become a true data-management table.

Recommended refactor:

• Convert to DataTable if filtering, sorting, view options, or admin review workflows grow.

Online Lessons

Status: actively migrating.

Findings:

• Has a full feature module with API, service, queries, mutations, schema, server helper, form, list/detail pages.
• Recent table work should stay aligned to DataTable and useDataTable.
• Manage/list routes should avoid duplicated table implementations.

Recommended refactor:

• Keep only one canonical list table implementation.
• Remove or redirect legacy manage listing code after confirming no route depends on it.

Employee Directory

Status: mostly aligned.

Findings:

• Uses DataTable and custom toolbar.
• Good reference for responsive table widths and hidden columns.
• No schema folder because it is currently backed by users and server data helpers rather than a new entity schema.

Recommended refactor:

• Keep as secondary canonical table reference.

Products, Employees, Forms, Kanban, Chat, React Query Demo

Status: legacy/template/demo areas.

Findings:

• Some files still reflect starter-template patterns.
• Products and employees include older table/form conventions.
• Demo pages should not be copied for runtime features.

Recommended refactor:

• Do not use these as references for new features.
• Migrate only when a user-facing requirement touches the feature.

Reports

Status: feature-specific dashboard view.

Findings:

• Uses custom report page and chart/table cards.
• Lint currently reports unused imports and nested component warnings in reports.

Recommended refactor:

• Clean unused report imports.
• Extract nested render components if reports are touched again.

Shared Table Stack

Status: canonical.

Findings:

• components/ui/table/data-table.tsx is the canonical shell.
• data-table-pagination.tsx owns pagination UI.
• data-table-toolbar.tsx owns generic filter and view controls.

Recommended refactor:

• New tables should not create manual pagination.
• Feature-specific toolbars may wrap shared DataTable controls, but should not replace them wholesale.

Forms

Status: canonical stack is clear.

Findings:

• Project uses TanStack Form, not React Hook Form.
• components/ui/tanstack-form.tsx is the shared entry point.

Recommended refactor:

• Do not introduce React Hook Form.
• Keep validation schemas in feature schemas/.

Persistence And Server Actions

Status: canonical stack is clear.

Findings:

• Project uses Drizzle, not Prisma.
• Project uses Route Handlers, not next-safe-action, for runtime feature mutations.

Recommended refactor:

• Do not introduce Prisma.
• Do not introduce next-safe-action without an explicit architecture decision.

Refactor Queue

1. Verify online-lessons has a single DataTable implementation and remove duplicated manage table code if no longer used.
2. Convert admin-heavy manual pagination screens to DataTable when they become data-management views.
3. Clean report warnings the next time report code is touched.
4. Keep legacy template features isolated and do not copy their patterns.

Stop Rule

Before refactoring broad areas, ask for approval with a scoped plan. Documentation changes and narrow consistency fixes may proceed directly when requested.