alla-allaos-fullstack/docs/implementation/task-a-template-audit.md

# Task A Template Audit

## 1. Executive Summary

This repository is already partway through the migration described in the project instructions. The current production-facing baseline is `Auth.js` plus app-owned `users`, `organizations`, and `memberships`, with `products` and `users` already using Route Handlers plus Drizzle. The dashboard still contains a mix of real app patterns and template/demo seams, so Task B should extend only the migrated patterns and avoid inheriting placeholder implementations.

The convention freeze for ALLA OS CRM vNext should be:

- Primary tenant boundary is `organizationId`.
- Membership, role, and permission checks live inside the active organization context.
- `branchId` is a business sub-scope inside an organization, not the tenant key.
- New CRM production work should follow the `products` and `users` module architecture, while using `Layout.md` as the structural UI source of truth for CRM pages.

No required audit path was missing. `Layout.md`, `AGENTS.md`, `README.md`, `package.json`, `src/db/schema.ts`, `src/lib/auth`, `src/app/dashboard`, `src/features`, and `src/components` are all present.

## 2. Project Structure

Observed top-level implementation anchors:

- App Router lives under `src/app`.
- Shared UI primitives live under `src/components/ui`.
- Layout primitives live under `src/components/layout`.
- Feature modules live under `src/features`.
- Drizzle schema is centralized in `src/db/schema.ts`.
- Shared auth helpers live under `src/lib/auth`.
- API boundaries live under `src/app/api/**`.

Observed feature directories:

- `auth`
- `chat`
- `crm`
- `elements`
- `example-dashboard`
- `forms`
- `kanban`
- `notifications`
- `overview`
- `products`
- `profile`
- `react-query-demo`
- `setup`
- `users`

Freeze recommendation:

- Treat `products` and `users` as the authoritative app-owned CRUD reference.
- Treat `crm`, `example-dashboard`, `forms`, `react-query-demo`, and several dashboard demo routes as template/demo seams unless and until they are migrated behind route handlers and auth-aware persistence.

## 3. Layout.md Findings

`Layout.md` is a structural skeleton, not a token source. It explicitly says no design tokens, colors, text, or icons are embedded directly and everything is represented by semantic placeholders.

Important frozen rules from `Layout.md`:

- CRM detail pages should use Template A.
- CRM list pages should use Template B.
- Page composition should remain slot-based: header, action row, preview, progress, main column, side column, dialogs.
- Layout spacing should map to semantic spacing slots rather than inventing page-local spacing rules.
- Cards, tabs, summary grids, timelines, and action rows are part of the intended page grammar.
- Detail pages are expected to support status-driven actions, preview panels, and side-column quick info where the business flow needs them.

Implication for Task B:

- Build CRM UI by mapping repository components and tokens onto the `Layout.md` skeleton.
- Do not invent a new page grammar if the existing template already covers the CRM use case.

## 4. kiranism-shadcn-dashboard Skill Findings

The skill is directionally correct but partially stale relative to the current repo state.

Still valid:

- Use Auth.js, Drizzle, route handlers, and app-owned org/membership semantics.
- Keep feature code under `src/features/<name>/`.
- Use `types.ts -> service.ts -> queries.ts -> mutations.ts`.
- Use local `apiClient` from feature services.
- Prefer server prefetch plus `HydrationBoundary`.

Stale compared with current code:

- The skill says there is no committed `auth.ts`, Drizzle schema, or shared RBAC model. Those now exist in `src/auth.ts`, `src/db/schema.ts`, and `src/lib/auth/*`.
- The skill says `src/features/products/api/service.ts` and `src/features/users/api/service.ts` still call mock data. They now call local route handlers through `apiClient`.

Convention freeze:

- Use the skill for architecture direction.
- Use the repository code as the final source of truth when the skill and code disagree.

## 5. Routing Convention

Observed routing pattern:

- Global dashboard shell: `src/app/dashboard/layout.tsx`
- Feature pages: `src/app/dashboard/**/page.tsx`
- API boundaries: `src/app/api/**/route.ts`
- Auth entrypoint: `src/app/api/auth/[...nextauth]/route.ts`

Dashboard routes currently mix three categories:

- Migrated app-owned routes: `product`, `users`, `workspaces`
- Template utility/demo routes: `forms`, `react-query`, `elements`, `overview`, `kanban`, `notifications`, `billing`, `profile`
- CRM demo routes: `crm/**`

Freeze recommendation:

- New CRM production pages should live under `src/app/dashboard/crm/**`.
- Production data for CRM must move through `src/app/api/crm/**` or feature-specific route handler namespaces, not direct mock service access.

## 6. Dashboard Layout Convention

`src/app/dashboard/layout.tsx` establishes the dashboard shell:

- `KBar`
- `SidebarProvider`
- `AppSidebar`
- `SidebarInset`
- `Header`
- `InfobarProvider`
- `InfoSidebar`

`src/components/layout/page-container.tsx` is the standard page wrapper and should remain the default page-level container:

- Handles title and description through `Heading`
- Supports page header actions
- Supports access fallback state
- Supports loading skeleton state

Freeze recommendation:

- Use `PageContainer` for dashboard pages instead of composing page headers ad hoc.
- Preserve the existing shell and only replace inner feature content.

## 7. Feature Folder Convention

Strong existing reference pattern:

- `src/features/products/api/{types,service,queries,mutations}.ts`
- `src/features/users/api/{types,service,queries,mutations}.ts`
- `src/features/<feature>/components/**`
- `src/features/<feature>/schemas/**` when forms exist

Freeze recommendation:

- CRM production work should follow the same split:
  - `api/types.ts`
  - `api/service.ts`
  - `api/queries.ts`
  - `api/mutations.ts`
  - `components/**`
  - `schemas/**` for form validation

## 8. Component Convention

Observed shared conventions:

- Shared UI primitives live under `src/components/ui/**`.
- Icons should be imported from `@/components/icons`.
- Page headers should go through `PageContainer`.
- Contextual documentation uses `InfoSidebar` plus `infoContent`.

Server/client split:

- Server components are the default for route entry pages.
- Client components are used for interactive tables, forms, switchers, and session-driven sidebar behavior.
- `AppSidebar`, `OrgSwitcher`, forms, and table shells are client components.

Freeze recommendation:

- Keep route pages server-first.
- Push interaction into feature components and shared UI primitives.

## 9. Form Convention

Observed form system:

- Primary form hook is `useAppForm` from `src/components/ui/tanstack-form.tsx`.
- Typed field helpers come from `useFormFields<T>()`.
- Validation is Zod-based.
- Form dialogs/sheets submit through React Query mutations.

Observed sheet/dialog pattern:

- `src/features/users/components/user-form-sheet.tsx` is the best current reference.
- Forms use `Sheet`, `SheetContent`, `SheetHeader`, `SheetFooter`.
- Submit button uses `<Button isLoading={isPending}>`.

Freeze recommendation:

- CRM forms should use `useAppForm`, typed fields, Zod schemas, and mutation-backed submission.
- Prefer `Sheet` for create/edit overlays when the current dashboard pattern already uses it.

## 10. Table Convention

Observed table pattern:

- Shared table shell is `src/components/ui/table/data-table.tsx`.
- State management helper is `src/hooks/use-data-table.ts`.
- URL state is driven by `nuqs`.
- Feature table pages prefetch on the server and render table components on the client.

Key conventions:

- Manual pagination, sorting, and filtering are expected.
- Query string keys are standardized via `src/lib/searchparams.ts`.
- Data tables rely on TanStack Table and TanStack Query.

Freeze recommendation:

- CRM list pages should keep the same table state model when the UI is tabular.
- If a CRM list is card-based per `Layout.md` Template B, the server data contract can still reuse the same filter, sort, and pagination conventions.

## 11. API / Server Action Convention

Observed production boundary:

- Feature services call `apiClient`.
- Route handlers perform auth, access control, and database work.
- Current repo prefers route handlers over direct client-to-DB access.

Observed examples:

- `src/app/api/products/route.ts`
- `src/app/api/products/[id]/route.ts`
- `src/app/api/users/route.ts`
- `src/app/api/users/[id]/route.ts`
- `src/app/api/organizations/route.ts`
- `src/app/api/organizations/active/route.ts`

Freeze recommendation:

- CRM production code should follow route handlers plus Drizzle, not in-memory feature services.
- Server actions are acceptable only when they fit naturally, but route handlers are the stronger established repo pattern.

## 12. Drizzle / Database Convention

Observed schema in `src/db/schema.ts`:

- `users`
- `organizations`
- `memberships`
- `products`

Current conventions:

- IDs for app-owned auth entities are `text` primary keys.
- Organization-scoped business entities include `organizationId`.
- Timestamps are timezone-aware and default to `now`.
- `users.activeOrganizationId` stores active workspace context.
- `memberships.permissions` is an array column.

Freeze recommendation for CRM vNext:

- Every CRM entity that belongs to a tenant must carry `organizationId`.
- `branchId` should be an additional column where needed for business scoping, not a replacement for `organizationId`.
- Audit and workflow entities should reference organization first, then branch if applicable.

## 13. Auth Convention

Current auth baseline is real and already committed:

- Auth.js config lives in `src/auth.ts`.
- Credentials provider checks `users.password_hash`.
- Session is enriched with organizations, active organization, membership role, business role, and active permissions.
- `src/proxy.ts` protects dashboard and protected API routes.

Preferred server helpers:

- `requireSession()`
- `requireSystemRole()`
- `requireOrganizationAccess()`

Freeze recommendation:

- All new CRM protected routes should use shared helpers from `src/lib/auth/session.ts`.
- Do not introduce Clerk or alternate auth paths.

## 14. Organization / Membership / Permission Convention

Current app-owned model:

- `users.systemRole`: global role such as `super_admin | user`
- `memberships.role`: organization role such as `admin | user`
- `memberships.businessRole`: business/department role such as `it_admin`, `helpdesk`, `auditor`
- `memberships.permissions`: fine-grained permissions array

Relevant code:

- `src/lib/auth/rbac.ts`
- `src/lib/auth/session.ts`
- `src/config/nav-config.ts`
- `src/hooks/use-nav.ts`

Freeze recommendation:

- CRM authorization must be organization-aware first.
- Membership role and explicit permissions should gate organization-scoped actions.
- Business role can layer domain-specific behavior but should not replace organization membership checks.

## 15. Branch Scope Convention

Task A explicitly requires organization-first scoping. The current repo supports that direction.

Evidence:

- Existing real entities use `organizationId` as the tenant boundary.
- Active context switching works at the organization level via `users.activeOrganizationId` and `/api/organizations/active`.
- CRM mock services use `branchId` inside domain records such as customers, enquiries, quotations, and approvals, which implies branch is a nested business scope.

Frozen convention:

- `organizationId` = tenant / workspace / company group scope
- `membership` = user access inside organization
- `branchId` = business branch / operational document scope inside organization

Do not design CRM around branch-first tenancy.

## 16. UI / Design Token Convention

Observed visual/token system:

- Theme system lives under `src/components/themes/**`.
- Theme CSS entrypoint is `src/styles/theme.css`.
- Default theme is `mongodb` from `src/components/themes/theme.config.ts`.
- Multiple named themes already exist; this repo already has a tokenized visual system.

Observed dashboard tone:

- Sidebar-based admin shell
- Sticky translucent header
- Theme switching and documentation sidebar
- shadcn cards, sheets, dialogs, tables, and Radix-based interactions

Freeze recommendation:

- Reuse the existing theme/token system.
- Use `Layout.md` for CRM structure, but map it onto current shadcn/tailwind/theme primitives.
- Do not create a parallel design system for Task B.

## 17. CRM vNext Recommended Convention

Recommended convention freeze for Task B:

- Routing:
  - Use `src/app/dashboard/crm/**` for pages.
  - Add route handlers under `src/app/api/crm/**` or sub-feature namespaces.
- Data model:
  - Every CRM entity stores `organizationId`.
  - Add `branchId` only as sub-scope where operationally required.
- Feature shape:
  - Follow `types.ts -> service.ts -> queries.ts -> mutations.ts -> components`.
- Auth:
  - Gate all real CRM reads and writes through `requireOrganizationAccess()`.
- UI:
  - Use `PageContainer`.
  - Use `Layout.md` Template A for detail pages and Template B for list pages.
  - Reuse shared shadcn primitives, theme system, icons registry, and infobar pattern.
- Data fetching:
  - Server prefetch with `getQueryClient()`
  - `HydrationBoundary`
  - client consumption through React Query
- Forms:
  - `useAppForm`
  - Zod schema
  - React Query mutations
- Tables/lists:
  - Keep `nuqs` filter/sort/page conventions
  - Reuse `useDataTable` when the UX is tabular

## 18. Files That Should Not Be Touched

For Task B, these should be treated as source-of-truth or stable infrastructure unless there is a deliberate migration step:

- `Layout.md`
- `AGENTS.md`
- `src/auth.ts`
- `src/lib/auth/session.ts`
- `src/lib/auth/rbac.ts`
- `src/db/schema.ts`
- `src/components/ui/**`
- `src/components/layout/page-container.tsx`
- `src/components/themes/**`
- `src/styles/theme.css`

Files to avoid using as production references:

- `src/constants/mock-api.ts`
- `src/constants/mock-api-users.ts`
- `src/features/crm/api/service.ts`
- `src/features/crm/api/queries.ts`
- other demo/template routes that still depend on mock or placeholder data

These legacy/demo files do not need immediate deletion, but Task B should not extend them as the long-term production path.

## 19. Risks / Concerns

Key risks before Task B:

- The repo currently mixes migrated app-owned code and demo/template code, so copying patterns from the wrong feature can reintroduce mock architecture.
- `src/features/crm/api/service.ts` is still in-memory mock state and currently uses `branchId` across CRM records without a real persisted organization boundary.
- Some nav and page access behavior is client-visible UX filtering only; all CRM protection must still be enforced server-side.
- `src/proxy.ts` protects broad route classes, but fine-grained CRM permission rules will still need route handler or page-level checks.
- Existing skill text is partially stale, so implementation decisions should always be verified against repository code.

## 20. Task B Implementation Plan

Recommended path for Task B:

1. Define CRM Drizzle tables with `organizationId` as the tenant boundary and `branchId` as optional business sub-scope.
2. Add shared CRM API contracts under `src/features/crm/api/types.ts` that reflect real route handler payloads.
3. Introduce CRM route handlers under `src/app/api/crm/**` and gate them with `requireOrganizationAccess()`.
4. Replace `src/features/crm/api/service.ts` mock-backed functions with `apiClient` calls to local route handlers.
5. Keep existing CRM route/page structure where possible, but refit the data path to the real app boundary.
6. For list pages, preserve current query, pagination, sort, and hydration conventions.
7. For detail pages, implement UI against `Layout.md` Template A using existing shared primitives and theme tokens.
8. Only after the boundary is real should branch-specific business logic be layered into CRM workflows.

Final convention freeze:

- Organization-first
- Membership-aware
- Branch as sub-scope
- Route-handler plus Drizzle
- Server-enforced RBAC
- `Layout.md` as CRM layout source of truth
- `products` and `users` as production architecture reference