alla-tms/AGENTS.md

AGENTS.md - Project Constitution For AI Coding Agents

This file provides project-specific guidance for AI coding agents working in this repository.

Highest Priority

AI agents must follow instructions in this order:

1. Existing project implementation
2. docs/AI_DEVELOPMENT_GUIDE.md
3. docs/PROJECT_ARCHITECTURE.md
4. AGENTS.md
5. kiranism-shadcn-dashboard
6. shadcn/ui
7. TanStack Table, TanStack Query, TanStack Form, and nuqs patterns
8. Next.js best practices

If instructions conflict, the higher item wins.

Mandatory Audit Before Code Changes

Before editing code, inspect the existing implementation for:

• Feature structure
• Shared components
• Shared hooks
• Shared route handlers and service patterns
• Shared dialogs and sheets
• Shared forms
• Shared tables
• Shared layout
• Auth and role checks

Do not guess. Reuse what exists before creating anything new.

Project Overview

This project is a Next.js 16 training-system dashboard built on an app-owned stack.

Current core stack:

• Framework: Next.js 16 App Router
• Language: TypeScript 5.7
• UI: shadcn/ui + Tailwind CSS v4
• Authentication: Auth.js
• Persistence: PostgreSQL + Drizzle ORM
• Data Fetching: TanStack React Query
• URL State: nuqs
• Forms: TanStack Form + Zod
• Charts: Recharts
• Monitoring: Sentry

The actual stack is Drizzle ORM and TanStack Form. Do not introduce Prisma, React Hook Form, or next-safe-action unless a future architecture decision explicitly adopts them.

Current architecture status:

• Auth is app-owned through Auth.js
• Multi-tenant access uses users, organizations, and memberships
• users is now the single person entity for auth and training participation
• employees is legacy migration data only and should not be used for new runtime work
• Core training modules are DB-backed:
  • users
  • courses
  • training-records
  • training-matrix
  • reports
• Some template pages still exist as placeholders or legacy seams

Auth And Roles

The current auth model is centered around:

• users
• organizations
• memberships

Important files:

• src/auth.ts
• src/lib/auth/session.ts
• src/lib/auth/roles.ts
• src/proxy.ts
• src/db/schema.ts

Current behavior:

• Authentication uses an Auth.js Credentials provider
• Passwords are verified against users.password_hash
• The user row stores active_organization_id
• Session enrichment loads membership and organizer context
• Self-service sign-up is disabled

Role model:

• super_admin: system-level organizer management
• admin: organizer-level management
• user: standard end user

Preferred server-side helpers:

• requireSession()
• requireOrganizationAccess(options?)

Do not introduce Clerk usage.

Sidebar Expectations

Sidebar visibility is role-based:

• super_admin: sees organizer management plus all organizer-operational menus
• admin: sees Dashboard, Users, Courses, Training Records, Training Matrix, Reports
• user: sees only Dashboard, Training Records, Reports

Nav filtering is UX only. Real protection must stay server-side.

Project Structure

/src
  app/
    auth/
    dashboard/
    api/
  components/
  config/
  db/
    schema.ts
  features/
    auth/
    overview/
    users/
    courses/
    training-records/
    training-matrix/
    reports/
    products/
  hooks/
  lib/
  styles/
  types/

Relevant docs:

• docs/AI_DEVELOPMENT_GUIDE.md
• docs/PROJECT_ARCHITECTURE.md
• docs/REFRACTOR_REPORT.md
• plans/req.md
• plans/implementation-plan.md
• plans/system-test-flow.md
• docs/themes.md
• docs/nav-rbac.md

Canonical Features

Use these references in order:

1. training-records: canonical feature for CRUD, Route Handlers, Drizzle, DataTable, TanStack Form, upload, and review flows.
2. employee-directory: canonical responsive DataTable and custom toolbar reference.
3. announcements: canonical content publishing and state transition reference.
4. audit-logs: canonical read-only table reference.

Feature and UI work must copy the existing pattern from these features before inventing a new approach.

Data Model Guidance

Runtime person data belongs on users.

User profile fields used by training features include:

• employee_code
• department_id
• position_id
• company_name
• hired_at

Training participation should reference training_records.user_id.

Do not build new features on top of the legacy employees module.

Feature Architecture

Each feature should use:

src/features/<name>/api/
  types.ts
  service.ts
  queries.ts
  mutations.ts

Rules:

• components import contracts from types.ts
• services call local route handlers through apiClient
• route handlers talk to Drizzle
• prefer server prefetch + HydrationBoundary + useSuspenseQuery()

Preferred backend path:

• Route Handlers + Drizzle + Auth.js session helpers

Legacy mock files are migration seams only:

• src/constants/mock-api.ts
• src/constants/mock-api-users.ts

DataTable Rules

For data tables, reuse:

• DataTable
• DataTableToolbar
• DataTablePagination
• DataTableViewOptions
• DataTableColumnHeader
• useDataTable
• TanStack ColumnDef
• shared faceted/date/slider filters
• row action menu components

Do not create a new table shell, toolbar, pagination component, sorting pattern, or view-options implementation when the shared stack can serve the feature.

Manual tables are only acceptable for small static layouts or legacy code that is intentionally left unchanged.

Forms

Use:

• useAppForm
• project field wrappers from @/components/ui/tanstack-form
• Zod validation

Master-data fields such as Department and Position should use dropdowns backed by server data, not free text.

Organizer-scoped defaults:

• company should come from the active organizer/workspace context
• normal admins should not choose arbitrary organizers
• super_admin may assign organizer context when creating users

Do not introduce React Hook Form into this project.

Dialog, Sheet, And Action Rules

Reuse:

• Dialog
• Sheet
• AlertDialog
• AlertModal
• DropdownMenu

Use a row action menu when a row has multiple commands such as view, edit, publish, archive, or delete.

Upload Rules

Reuse existing upload components and storage helpers:

• FileUploader
• certificate-storage.ts
• announcement-storage.ts
• online-lesson-storage.ts

Do not create a new upload/storage implementation until the existing helpers are proven insufficient.

Responsive Rules

Pages must not overflow horizontally.

Use:

• PageContainer
• w-full min-w-0 max-w-full
• overflow-x-auto only inside table shells
• wrapping button containers
• shrink-0 whitespace-nowrap for actions that must not clip

Do not create nested cards for page sections. Cards are for forms, filters, empty states, repeated content items, and focused tools.

Forbidden Without Approval

AI agents must not introduce:

• New dashboard layout
• New table framework
• New pagination pattern
• New toolbar framework
• New form framework
• New dialog framework
• New upload framework
• Prisma
• Clerk
• React Hook Form
• next-safe-action
• Mock data imports in runtime UI

Protected Data Rules

Use these rules consistently:

• admin can see organizer-wide data
• user can only see their own training data
• reports for user must be self-scoped on the server even if URL params are manipulated
• training-record participant selection must come from organizer-scoped users

Development Commands

bun install
# or
npm install

bun run dev
# or
npm run dev

bun run build
# or
npm run build

bun run lint
# or
npm run lint

bun run migrate
# or
npm run migrate

Environment Configuration

Required:

AUTH_SECRET=your-long-random-secret
DATABASE_URL=postgres://postgres:postgres@localhost:5432/training_system

Optional Sentry variables may also be configured.

Notes For AI Agents

1. Always use cn() for className merging.
2. Keep new work inside src/features/.
3. Server components are the default.
4. Avoid any; keep contracts explicit.
5. Use PageContainer for page headers.
6. Use TanStack Form + Zod via existing wrappers.
7. Use icons only through @/components/icons.
8. Prefer Route Handlers + Drizzle + React Query for new app-owned features.
9. Never import mock API data directly into UI components.
10. Use @/auth and src/lib/auth/session.ts for auth checks.
11. Do not introduce Clerk usage.
12. Treat employees as legacy migration data, not target runtime architecture.
13. Follow the migrated users, courses, and training-records patterns for new CRUD work.
14. Read docs/AI_DEVELOPMENT_GUIDE.md and docs/PROJECT_ARCHITECTURE.md before substantial code changes.
15. If code being touched is off-pattern, propose a focused refactor before expanding that pattern.
16. Consistency is more important than novelty. New work should look like it has always been part of the project.

Required Completion Checklist

Before final response, verify:

• Existing feature pattern was inspected.
• Shared components were reused.
• Shared hooks were reused.
• Shared dialogs/sheets/action menus were reused.
• Data tables use the shared DataTable stack.
• Forms use TanStack Form plus Zod.
• Route handlers and Drizzle patterns are preserved.
• Server-side auth and role checks are preserved.
• Folder structure and naming match the project.
• Responsive behavior does not clip buttons or overflow the page.