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

```text
/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:

```text
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

```bash
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:

```env
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.