Sales & GTM

Fundraising & Ecosystem

Listings

Unified pattern for data tables, grids, and CRUD operations — optimistic updates, URL-persisted views, infinite scroll, type-safe queries.

Listings are the backbone of data-driven features. 11 entities follow the same shape — students, teachers, classrooms, assignments, etc. — with consistent UX and optimistic updates.

Features

Feature	Behaviour
Optimistic updates	Add / update / remove instantly with automatic rollback on errors
URL-persisted views	Table / grid view toggle via URL query params (`nuqs`)
Infinite scroll	Load-more pagination, no page reloads
Centralised queries	Type-safe query builders with role-based authorisation per module

File patterns

Every listing follows the mirror pattern — the URL produces two directories: one in app/ for routing, one in components/<feature>/ for everything else.

File	Purpose
`content.tsx`	Server component — data fetching, tenant context
`table.tsx`	Client component — interactive table with state
`columns.tsx`	Column definitions (client, uses hooks)
`form.tsx`	Create / edit form with validation
`actions.ts`	Server actions — validate, scope tenant, mutate
`queries.ts`	Query builders with Prisma
`authorization.ts`	RBAC permission checks
`validation.ts`	Zod schemas + refinements
`types.ts`	TypeScript interfaces
`config.ts`	Constants, options, labels
`list-params.ts`	URL params (`nuqs`)
`README.md`	Feature documentation
`ISSUE.md`	Known issues tracker

Page composition

PageTitle              src/components/atom/page-title.tsx
  Abc Management — "Manage all abc records in your school"

PageNav                src/components/atom/page-nav.tsx
  All | Active | Archive | Settings

Toolbar                src/components/atom/toolbar.tsx
  [search] [filters]  [view ≡/⊞] [export ↓] [create +]

DataTable              src/components/table/data-table.tsx
OR GridContainer       src/components/atom/grid-container.tsx

Modal (when open)      src/components/atom/modal/modal
  ModalFormLayout
    Form (listings/abc/form.tsx)
  ModalFooter
    Step 1 of 2: Basic Info     [Cancel] [Next]

Component flow

Route (page.tsx)
  → Content (content.tsx) ── Server
      • getTenantContext()
      • Parse URL params
      • Fetch via queries.ts
  → Table (table.tsx) ── Client
      • useModal()
      • usePlatformView()
      • useDataTable()
      ├─ Toolbar (Search, ViewToggle, Export, Create)
      ├─ DataTable / GridContainer (Columns, row actions, pagination)
      └─ Modal (Form, ModalFormLayout, ModalFooter)

Reference implementation

Grades is the canonical reference. All paths under src/components/school-dashboard/listings/grades/:

Pattern	File
Server actions	`actions.ts`
Queries	`queries.ts`
Authorization	`authorization.ts`
Validation	`validation.ts`
Table	`table.tsx`
Columns	`columns.tsx`
Form	`form.tsx`
Content	`content.tsx`

Core hooks

Hook	Path	Purpose
`usePlatformData`	`src/hooks/use-platform-data.ts`	Data fetching with optimistic updates and infinite scroll
`usePlatformView`	`src/hooks/use-platform-view.ts`	View mode (table / grid) with URL persistence
`useDataTable`	`src/components/table/use-data-table.ts`	TanStack Table state management
`useModal`	`src/components/atom/modal/context.tsx`	Modal open / close state

Modules

All 11 listings ship table, grid, search, and export:

Announcements, Assignments, Classes, Classrooms, Events, Grades, Parents, Staff, Students, Subjects, Teachers.

Subjects additionally carries a school-side customization layer over the platform catalog: on the subject detail page admins get a Customize panel (SchoolCatalogCustomization) to hide chapters / lessons / a specific instructor's video, hide a lesson's quiz, set the preferred instructor source, and contribute the school's own videos. It writes per-school ContentOverride / InstructorPreference rows enforced by the lumos (LMS) read paths — see the catalog docs (“School-side controls”).

Best practices

Multi-tenant safety

Always include schoolId in every database query.
Get from session: const { schoolId } = session.user.
Missing schoolId breaks tenant isolation.

Column definitions

Define handlers before the columns useMemo.
Columns with hooks (useModal) must be generated in client components.
Pass callbacks via getColumns(dictionary, lang, { onDelete, onEdit, onView }).

Optimistic updates

Call optimisticRemove(id) before server request.
Call refresh() on error to rollback.
Use optimisticUpdate(id, updater) for in-place updates.

Server actions

Start with "use server".
Validate with Zod on both client (UX) and server (security).
Call revalidatePath() or redirect() after mutations.
Return typed ActionResponse<T>.

Use ModalFormLayout for two-column header / form layout.
Use ModalFooter for progress bar and navigation.
Call onSuccess() after successful mutations.

Maturity levels

Level	Feature	Status
1	Basic CRUD	Complete
2	Relationship context (counts, quick links)	In progress
3	Rich detail pages with related data tabs	In progress
4	Cross-listing actions (bulk operations)	In progress
5	Automated workflows (triggers, notifications)	Planned

Listings

Unified pattern for data tables, grids, and CRUD operations — optimistic updates, URL-persisted views, infinite scroll, type-safe queries.

Listings are the backbone of data-driven features. 11 entities follow the same shape — students, teachers, classrooms, assignments, etc. — with consistent UX and optimistic updates.

Features

Feature	Behaviour
Optimistic updates	Add / update / remove instantly with automatic rollback on errors
URL-persisted views	Table / grid view toggle via URL query params (`nuqs`)
Infinite scroll	Load-more pagination, no page reloads
Centralised queries	Type-safe query builders with role-based authorisation per module

File patterns

Every listing follows the mirror pattern — the URL produces two directories: one in app/ for routing, one in components/<feature>/ for everything else.

File	Purpose
`content.tsx`	Server component — data fetching, tenant context
`table.tsx`	Client component — interactive table with state
`columns.tsx`	Column definitions (client, uses hooks)
`form.tsx`	Create / edit form with validation
`actions.ts`	Server actions — validate, scope tenant, mutate
`queries.ts`	Query builders with Prisma
`authorization.ts`	RBAC permission checks
`validation.ts`	Zod schemas + refinements
`types.ts`	TypeScript interfaces
`config.ts`	Constants, options, labels
`list-params.ts`	URL params (`nuqs`)
`README.md`	Feature documentation
`ISSUE.md`	Known issues tracker

Page composition

PageTitle              src/components/atom/page-title.tsx
  Abc Management — "Manage all abc records in your school"

PageNav                src/components/atom/page-nav.tsx
  All | Active | Archive | Settings

Toolbar                src/components/atom/toolbar.tsx
  [search] [filters]  [view ≡/⊞] [export ↓] [create +]

DataTable              src/components/table/data-table.tsx
OR GridContainer       src/components/atom/grid-container.tsx

Modal (when open)      src/components/atom/modal/modal
  ModalFormLayout
    Form (listings/abc/form.tsx)
  ModalFooter
    Step 1 of 2: Basic Info     [Cancel] [Next]

Component flow

Route (page.tsx)
  → Content (content.tsx) ── Server
      • getTenantContext()
      • Parse URL params
      • Fetch via queries.ts
  → Table (table.tsx) ── Client
      • useModal()
      • usePlatformView()
      • useDataTable()
      ├─ Toolbar (Search, ViewToggle, Export, Create)
      ├─ DataTable / GridContainer (Columns, row actions, pagination)
      └─ Modal (Form, ModalFormLayout, ModalFooter)

Reference implementation

Grades is the canonical reference. All paths under src/components/school-dashboard/listings/grades/:

Pattern	File
Server actions	`actions.ts`
Queries	`queries.ts`
Authorization	`authorization.ts`
Validation	`validation.ts`
Table	`table.tsx`
Columns	`columns.tsx`
Form	`form.tsx`
Content	`content.tsx`

Core hooks

Hook	Path	Purpose
`usePlatformData`	`src/hooks/use-platform-data.ts`	Data fetching with optimistic updates and infinite scroll
`usePlatformView`	`src/hooks/use-platform-view.ts`	View mode (table / grid) with URL persistence
`useDataTable`	`src/components/table/use-data-table.ts`	TanStack Table state management
`useModal`	`src/components/atom/modal/context.tsx`	Modal open / close state

Modules

All 11 listings ship table, grid, search, and export:

Announcements, Assignments, Classes, Classrooms, Events, Grades, Parents, Staff, Students, Subjects, Teachers.

Subjects additionally carries a school-side customization layer over the platform catalog: on the subject detail page admins get a Customize panel (SchoolCatalogCustomization) to hide chapters / lessons / a specific instructor's video, hide a lesson's quiz, set the preferred instructor source, and contribute the school's own videos. It writes per-school ContentOverride / InstructorPreference rows enforced by the lumos (LMS) read paths — see the catalog docs (“School-side controls”).

Best practices

Multi-tenant safety

Always include schoolId in every database query.
Get from session: const { schoolId } = session.user.
Missing schoolId breaks tenant isolation.

Column definitions

Define handlers before the columns useMemo.
Columns with hooks (useModal) must be generated in client components.
Pass callbacks via getColumns(dictionary, lang, { onDelete, onEdit, onView }).

Optimistic updates

Call optimisticRemove(id) before server request.
Call refresh() on error to rollback.
Use optimisticUpdate(id, updater) for in-place updates.

Server actions

Start with "use server".
Validate with Zod on both client (UX) and server (security).
Call revalidatePath() or redirect() after mutations.
Return typed ActionResponse<T>.

Use ModalFormLayout for two-column header / form layout.
Use ModalFooter for progress bar and navigation.
Call onSuccess() after successful mutations.

Maturity levels

Level	Feature	Status
1	Basic CRUD	Complete
2	Relationship context (counts, quick links)	In progress
3	Rich detail pages with related data tabs	In progress
4	Cross-listing actions (bulk operations)	In progress
5	Automated workflows (triggers, notifications)	Planned

balqalam

Listings

Features

File patterns

Page composition

Component flow

Reference implementation

Core hooks

Modules

Best practices

Multi-tenant safety

Column definitions

Optimistic updates

Server actions

Maturity levels

See also

balqalam

Listings

Features

File patterns

Page composition

Component flow

Reference implementation

Core hooks

Modules

Best practices

Multi-tenant safety

Column definitions

Optimistic updates

Server actions

Maturity levels

See also

Listings

Features

File patterns

Page composition

Component flow

Reference implementation

Core hooks

Modules

Best practices

Multi-tenant safety

Column definitions

Optimistic updates

Server actions

Modal forms

Maturity levels

See also

Listings

Features

File patterns

Page composition

Component flow

Reference implementation

Core hooks

Modules

Best practices

Multi-tenant safety

Column definitions

Optimistic updates

Server actions

Modal forms

Maturity levels

See also