Quick reference for organizing features using vertical slice architecture.
- Internal utilities used across multiple features
- Framework-specific adapters (Next.js, React)
- Cross-cutting concerns that aren't ready for packages
- Endatix-specific business logic
- App configuration (features/config/)
- Complete vertical slices with use-cases, UI, and infrastructure
- Future npm packages with their own package.json
- Reusable libraries that can be published independently
- Workspace packages that other projects can consume
- Standalone browser bundles (not Next). Today:
src/embed→public/embed/v1/embed.js. See AGENTS.md "Embed SDK".
- Cross-feature UI with no single owning domain
- Design-system vocabulary governed by
DESIGN.md - Vendor primitives (
components/ui/, shadcn)
A reusable concept that grows a UI (file kinds, list tables, statuses) does
not automatically grow a ui/ folder next to its logic. Two shapes already
exist in this repo and they are not interchangeable:
| Shape | When | Example |
|---|---|---|
lib/<domain>/<slice>/ui/ |
The domain is itself a vertical slice — client-only, owns its use-cases, and its UI has exactly one consumer: that domain | lib/survey-features/form-diagnostics/ui/, lib/survey-extensions/ui/ |
lib/<domain>/ + components/… |
The logic is a catalog or helper many unrelated features read, and the UI is presentation vocabulary over it | lib/list-page/table-return-to + components/table/back-to-table-button.tsx; lib/file-kinds/ + components/common/file-kind-icon.tsx |
Decision rule — apply in order; the first test that answers, wins:
- Does server code import the domain? If a route handler, server action or
server page imports it, UI must not live inside it. One
"use client"file with alucide-reactimport turns the domain's barrel into a client dependency, and the nextimport { FILE_KINDS } from "@/lib/file-kinds"in a route handler drags React into a request path. This test is mechanical, not taste, and it is whylib/file-kinds/has noui/. - Who consumes the UI? One domain, and only through that domain → keep it
domain-local in
lib/<domain>/<slice>/ui/. Unrelated features import it directly →components/. - Does
DESIGN.mdgovern how it looks? A status pill, a file mark, table chrome — anything with a rule in the design system — lives incomponents/, where the §5 component index points. A component the design system describes but that is filed inside one domain will be re-invented by the next feature that cannot find it.
Placement inside components/:
components/ui/— shadcn/vendor primitives. Do not add hand-written Hub components here; a local component in this folder reads as vendor code and gets clobbered by the next generator run.components/common/— a single design-vocabulary component per file, no barrel, imported by full path (@/components/common/status-badge).components/<domain>/— a set of related parts with anindex.tsbarrel.components/table/is the reference. Graduate acommon/component here once it is roughly three files, or once the parts share internal conventions (naming, class-name helpers, meta types) that outsiders should not reach past the barrel for. Moving one file is cheap; splitting a folder nobody can navigate is not.
Worked example — file kinds (H933):
lib/file-kinds/file-kinds.ts # catalog: extension, MIME, label, group — server-safe
lib/file-kinds/file-kind-icons.ts # kind → Lucide icon; kept out of index.ts so the
lib/file-kinds/index.ts # barrel stays free of lucide-react (test 1)
components/common/file-kind-icon.tsx # FileKindIcon / FileKindLabel — the rendered mark (tests 2, 3)
features/export/utils.ts # export wire keys + delivery enum → FileKindKey
The catalog is data and stays in lib/. The mark is design-system vocabulary
and stays in components/. Feature code maps its own vocabulary onto a
FileKindKey and never returns a LucideIcon — see DESIGN.md §5 "File Type
Marks". When file UI grows past this one component (previews, upload chips, size
labels), it graduates to components/files/ with a barrel; that is a move, not
a redesign.
Anti-patterns:
- Creating
lib/<domain>/ui/for a single component two features import. That is acomponents/common/component with extra path. - Creating
components/<domain>/for one file. Start incommon/, graduate. - Duplicating a design-system component inside a domain because the shared one
was hard to find. Fix the index in
DESIGN.md§5 instead.
Vertical Slice Architecture: organize by business feature, then by use-case slice.
features/
├── {feature-name}/
│ ├── server.ts # Optional: curated server-safe exports
│ ├── index.ts # Optional: curated shared/client-safe exports
│ ├── types.ts # Feature-shared types across slices
│ ├── utils.ts # Feature-shared pure helpers
│ ├── ui/ # Cross-slice reusable UI only
│ ├── {verb-noun}/ # Use-case slice (preferred)
│ │ ├── {verb-noun}.action.ts # Server action for this slice
│ │ ├── {verb-noun}.server.ts # Optional server-only loader/helper
│ │ ├── use-{noun}.hook.ts # Optional slice-local hook
│ │ ├── ui/ # Slice-local UI
│ │ ├── __tests__/ # Slice-local tests
│ │ └── index.ts # Slice barrel exports
│ └── __tests__/ # Optional cross-slice integration tests
Use features/folders as the canonical implementation of this pattern:
- slices like
create-folder,update-folder,delete-folder,move-form-to-folder,view-forms-header - shared root artifacts in
types.ts,utils.ts, and rootui/for cross-slice components - server-safe curated exports via
features/folders/server.ts - slice-local tests in
features/folders/create-folder/__tests__/ - create, update, and delete revalidate
revalidatePath("/", "layout")so the sidebar nav slot reloads. Page paths alone leave the layout cache stale. Reference:create-folder.action.ts.
A page that reports on a domain (admin Environment, health views) imports that domain's
type instead of writing a matching one. Re-spelling a union or a field list in a
view-*/types.ts creates two definitions that drift silently, and the page ends up
describing settings it does not own.
features/platform-admin/view-environment-settings/types.ts is the worked example:
featureFlags is FlagSettings from lib/feature-flags/flag-settings.ts,
analytics is a Pick<ClientEndatixConfig, …>, and the server loader calls the domain's
own readFlagSettings() rather than assembling fields. Keep the shared vocabulary in a
dependency-free module so client components can type-import it.
Unauthenticated tenant sign-in / self-registration lives here, not under platform-admin: platform-admin is client-imported and must stay free of NextAuth. The slice owns the public-tenant action, the provider allow-list filter, and the (auth) failure states. Hub types use shortUrl; POST /auth/register still sends tenantSlug. See Hub AGENTS.md “Endatix IDs” and “Auth pages”.
list-signup-requests/owns the queue: URL parsing, the loader, the toolbar and the grid.review-signup-request/owns the decision: the approve, reject and retry actions, the review panel, the reviewer-name loader (listSignupReviewers), andsignup-request-state.ts, the one mapping from decision and provisioning to tones, row badge and next step. The grid imports the state mapping and mounts the panel. It never decides itself.SignupRequestView(review-signup-request/types.ts) is what both render.toSignupRequestView(signup-request-view.server.ts) builds it for the list loader and every decision action: it drops the opaquemetadataand keeps only the PostHog visitor reference.load-signup-visitor.server.tsturns that reference into the panel's Visitor section on demand, throughfeatures/analytics/posthog/server/posthog-read-api.server.ts. The panel callsgetSignupVisitorActionafter paint; a server action during render updates the router while the section is rendering. Keep Hub-only fields offlib/endatix-apitypes.- UX pattern:
DESIGN.md§6 "Recipe: list page" (review queue) and "Recipe: review and decide", and "Evidence from third-party tools" for the Visitor section.
The Shared Form's corner on a test page. testCornerFor (features/public-form/test-submission-mode.ts) is the one gate: inspector, notice, or none. The server checks forms.test only on a test page, so a real respondent's load never reaches auth(), and builds a TestInspectorView with toTestInspectorView, the only reader of the wire Submission for it. The slice exports the lazy TestInspector (its own chunk, requested only when a view arrives), toTestInspectorView, and StartOver; the trigger, menu and panels stay internal. SurveyComponent takes renderCorner(model), so the inspector gets the model it sits beside. Embeds keep the plain notice plus Start over.
Reporting export is a dedicated feature (not nested under forms/ or submissions/). Slices map to API capabilities and UI surfaces:
| Slice | Scope | Responsibility |
|---|---|---|
prepare-reporting-export |
Action-only | Server action: compile FormSchema + backfill flattened submissions (fullRecompile → replace + force). Called by the Export dialog and by the submissions grid readiness banner. |
export-submissions |
Submissions list | Tenant-configured export download via exportFormatId (+ legacy CustomExports when flag off). Owns the Export dialog: readiness check, auto prepare when schema missing, optional Rebuild reporting data… (manual prepare + full recompile), format + capability-aware filters. |
manage-export-formats |
Tenant settings (E10b) | CRUD UI for tenant export formats + tenant default mapping picker (alias, key separator, include-test) |
Shared feature root: types.ts, utils.ts (wire key / delivery enum → FileKindKey), export-url.ts, export-error-message.ts. backfill-reporting-submissions.server.ts is the one backfill paging loop: prepare-reporting-export fails when it stops at the batch cap, while export-submissions/refresh-incomplete-submissions.action.ts (the backfill-only refresh before an Incomplete/All export) reports a partial run and lets the export continue. Export permissions follow the API and are loaded once per submissions page: loadSubmissionExportAccess() (export-submissions/export-access.server.ts, from @/features/export/server) makes one evaluatePermissions call and returns SubmissionExportAccess — canExport (submissions.export: Export Submissions shows), canPrepare (submissions.export or forms.edit, the API's rule for compile and a backfill without force: the banner's Prepare and Include in-progress submissions show), canRebuild (forms.edit: Rebuild reporting data… shows in the dialog, since a full recompile clears flattened data). A failed check allows nothing. The server actions still check: list formats (submissions.export or tenant.settings.manage), prepare (forms.edit for fullRecompile only), and the refresh (submissions.export or forms.edit; skipped, not failed, without either). Reporting wireKey catalog: lib/endatix-api/reporting/reporting-export-wire.ts. File kinds and the rendered mark: lib/file-kinds/ + components/common/file-kind-icon.tsx (see “Where UI for a shared concept lives”). Export route stays thin and delegates parsing to export-submissions/parse-export-query.ts. Create-format delivery options come from the API capabilities catalog (wireKey e.g. xlsx); tenant format rows drive the submissions export dialog.
Import from @/features/export (client UI) or @/features/export/server (server actions). Slice barrels: @/features/export/export-submissions, @/features/export/prepare-reporting-export, @/features/export/manage-export-formats.
Note: Codebook/Shoji downloads use the same tenant formats + submissions export dropdown (no separate
export-codebook/manage-export-mappingsslices). Locale stays request-time on the export API and is not edited on format definitions. Prepare is entered from the export dialog (auto when not ready, or via Rebuild reporting data…) and from the submissions grid readiness banner (Prepare, and Include in-progress submissions viarefreshIncompleteSubmissionsAction, both withcanPrepare). Both banner actionsrouter.refresh()the grid when they finish. Import them from@/features/export/server.
Organization identity surfaces follow the same vertical-slice rule:
features/organization/user-management/use-cases/create-tenant-userowns tenant invites. Invite actions must not collect a password from the inviter.features/organization/user-management/use-cases/delete-userowns tenant access removal. It keeps typed confirmation in UI and must not delete the global user identity.features/organization/user-management/use-cases/resend-verificationowns pending-user activation email resend.features/organization/user-management/use-cases/cancel-inviteowns pending invite cancellation and token invalidation.features/organization/user-management/use-cases/manage-user-rolesowns assigning and removing user roles.features/organization/role-managementowns role CRUD and permission catalog UI.
New organization server actions should return ServerActionState and convert Zod failures through ServerActionState.fromZodError.
To prevent server-side dependencies (like database clients or SDKs) from leaking into the client bundle, use explicit entry points:
- Slice
index.ts: Primary import point for each vertical slice. server.ts: Optional feature-level curated exports for Server Components and Server Actions.index.ts: Optional feature-level curated shared/client-safe exports.
Cohesion: Related code lives together - business logic, actions, UI, and tests are co-located.
Discoverability: Find everything related to a feature without navigating multiple folders.
Collaboration: Teams work on different features simultaneously with minimal conflicts.
Flexibility: Features vary in complexity without artificial constraints.
Use __tests__/ folders for test organization:
- Slice level (default):
features/{name}/{verb-noun}/__tests__/- Test slice behavior close to implementation - Feature level (optional):
features/{name}/__tests__/- Cross-slice integration and shared feature helpers - Component level:
.test.tsxfiles go in a__tests__/folder next to the component - Routes and repo-wide checks: the root
__tests__/(__tests__/app/,__tests__/pages/, …) - Mocks and assertions:
hub/AGENTS.mdTests (mocks reset automatically; mock at the boundary) - Focus on slices: Test actions, loaders, hooks, and UI inside the slice where they live
- Environment:
.test.tsruns in node,.test.tsxin jsdom; a.tstest opts into the DOM with// @vitest-environment jsdom. Full rule:hub/AGENTS.mdTests. - AAA regions:
// Arrange/// Act/// Assert(or// Act & Assertwhen there is no setup). Skip only when theitis a one-liner with no distinct phases. Full rule:hub/AGENTS.mdTests and.cursor/rules/endatix-hub-rules.mdc.
// Pure business logic, no Next.js dependencies (only when needed)
export const createFormUseCase = async (
request: CreateFormRequest,
): Promise<Result<string>> => {
// Business logic here
};"use server";
import { revalidatePath } from "next/cache";
import { EndatixApi } from "@/lib/endatix-api";
import { Result } from "@/lib/result";
import { toResult } from "@/lib/result/map-api-result-to-result";
export type DeleteItemResult = Result<string>;
export async function deleteItemAction(
itemId: string,
): Promise<DeleteItemResult> {
const session = await requireAccess(); // auth + authorization at the boundary
const api = new EndatixApi(session.accessToken);
const apiResult = await api.items.delete(itemId);
const result = toResult(apiResult, {
fallbackMessage: "Failed to delete item.",
logMessage: "Failed to delete item.",
loggerName: "feature.items",
mapData: (data) => data.message,
});
if (Result.isSuccess(result)) {
revalidatePath("/(main)/items");
}
return result;
}Action rules:
- Return
Result<T>by default — never swallow failures silently. UseServerActionStateonly for FormData /useActionStateflows that need Zod field-level errors (not for arbitrary Zod multi-field forms) - Authenticate and authorize inside the action, or accept a session already validated by the caller
- Always map Endatix
ApiResultwithtoResult(...)— do not hand-writeResult.error(apiResult.error.message). PassfallbackMessage,logMessage, andloggerNameso expected 403/404/validation stay user-facing and unexpected failures log throughTelemetryLogger - When the UI result type differs from the API body (e.g.
Result<void>), usemapData(e.g.mapData: () => undefined) - Revalidate paths only after
Result.isSuccess(result) - Surface success and failure in the UI with toast or inline feedback; pair actions with a client handler using
useTransitionwhen not usinguseActionState
- Drive search, filters, and pagination from URL
searchParams(parse in a server page or shared util, e.g.parsePlatformAdminListParams,parseFormsListParams). Coerce Next's repeated keys withfirstSearchParam(lib/utils/next-utils); type optionalsearchParamsmembers asSearchParamValue, notSearchParam—?plus| undefinedis redundant. - Use one paged API endpoint with scope/tenant filters rather than two parallel lists sharing the same
pageparam. - Client tables update the URL via
useListUrlState(single debounced field) oruseTableFiltersUrlState(2+ debounced fields, one coalesced commit — see below), plusSelectfilters callingupdateUrldirectly,PagedTableFooter/PagedListFooter, and receive unresolved promises from the server page. - Paged list wiring (one pattern, issue #1011). The server page parses the request, starts the promise, and passes
listKey={listQueryKey(listRequest)}(lib/list-page/list-query-key). Never hand-write a per-list key:listQueryKeycovers every field the parser emits, so new filters and sort fields can't be missed.- A client shell owns
useListUrlStateonce and renders the toolbar outsidePagedListFrame(components/table) and the grid inside it. The grid callsuse(promise)and getsupdateUrl/isPendingas props — it never calls a URL hook itself. Reference:features/platform-admin/list-tenants/ui/tenants-list.tsx. Card-style lists (UsersList,RolesList,PlatformAdminsList) usePagedCardList, which puts the toolbar in the card header and the frame around the rows. - When the toolbar and grid are server-composed (other server content between them, e.g. folder cards on
/forms), wrap them inPagedListUrlProviderand readusePagedListUrl()in both. Same rule: toolbar outside the frame. - Why the key: without it,
use(promise)keeps the first page afterrouter.replaceuntil a full reload. Why the toolbar stays outside: a key change remounts everything inside the frame and shows the fallback, so a search input inside it loses focus and typed characters on every debounced commit. A page change shows the skeleton; that is intended. - Row identity. Every TanStack grid sets
getRowIdto the entity id. Index-keyed rows let stateful cells (the submissions status dropdown, answers) keep the previous page's values — that was the submissions half of #1011. - Submissions key a server section:
PagedListFramewraps the asyncSubmissionListSection(it keeps the post-fetchredirect()on the server), andSubmissionsWithFiltershandsisPendingto itsDataTablefor skeleton rows while the next page is in flight. - Data-list items keep
Suspenseinside the client details section. - Height while loading. Whoever renders the pending skeleton holds the list at its last rendered height with
useHeldHeight(isPending):PagedListFramefor card lists and forms,DataTableGridand the submissionsDataTablefor their row area (the footer sits below it). The skeleton can't shrink the page or move the pager while the next page loads. When rows render the list takes its natural height, so a filter with one result shows one row, every time, and a shorter last page is shorter. One loading look: while a page, filter, or sort change is in flight (isPendingfrom the shell'suseListUrlState), the rows become skeleton rows and everything else stays mounted — no toolbar "Updating…" text, no dimming. Table lists passisPendingtoDataTableGrid(or the submissionsDataTable), which keeps the column header (and its filters) and rendersDataTableSkeletonRows. Card lists pass it toPagedCardList, andPagedListFrameswaps in its fallback; underPagedListUrlProvider(forms) the frame picks it up on its own. An empty list that is reloading shows skeleton rows too (pendingRowCount), not its empty state. Every frame fallback is a*Skeletoncomponent. Spinners are for action buttons (grant, save, delete), never for list rows. The conformance test enforces the fallback names,isPendingon everyDataTableGrid, and no "Updating…" text. - Tests, in three layers. (1)
__tests__/app/paged-list-conformance.test.tsfails the build when a TanStack grid lacksgetRowId, a paged page skipslistQueryKeywithout an allow-listed reason, or a key is hand-rolled. (2)__tests__/pages/paged-list-shells.test.tsxrenders each shell, changeslistKey, and checks new rows appear while the search input keeps its value and focus — add a new shell to its table. (3)e2e/tests/lists/list-paging.spec.tspages every list in a real browser and compares the rows with a fresh render of the same URL — add a new list to itslistsarray.
- A client shell owns
- Files in and out. CSV text is read and written by
lib/utils/csv.ts(readCsvRecords,readCsvRowswith a stray-quote mark per row,writeCsv), server-safe and with no React. Saving a file islib/utils/files-download.ts:downloadFromUrlfor a file a route builds,downloadTextfor one the browser builds. The rendered control iscomponents/common/download-menu.tsx. A slice keeps only its own columns and copy (reference:features/audience/generate-links/personal-links.ts,features/audience/import-csv/csv-preview.ts). Rules:DESIGN.md§6 "Hand over a file". - Shared helpers live in
lib/list-page/(parse-paged-search-params,list-query-key,table-return-to). URL writers and the frame (useListUrlState,useTableFiltersUrlState,PagedListUrlProvider,PagedListFrame,PagedCardList) live incomponents/table/. - List-table chrome (surface, empty state, header/row/cell class helpers, search input, toolbar, paged footer,
BackToTableButton,useListUrlState,useTableFiltersUrlState) lives incomponents/table/.DataTableToolbaris one row: filters scroll, actions stay pinned. Keep the ShadCN primitive (Table,TableRow, …) incomponents/ui/table.tsx. - Do not hand-roll the parts every list table shares — reach for
components/tablefirst:DataTableGridrenders the TanStack header/body;DataTableSkeletonis its loading twin (passcolumns, override a column'scellonly where the placeholder shape differs).useListTableState(urlState, updateUrl)derivessorting,created,modified, andonSortingChangefrom the URL.auditDateColumns({ created, modified, updateUrl })is theCreated/Modifiedpair; spread it into the column list rather than redefining the headers and date filters.ColumnMeta.cellClassName/headerClassNameare declared once incomponents/table/data-table-column-meta.ts. Import that module for the class-name fields; a featuretypes.tsaugmentsColumnMetaonly with its own fields.
- Two or more debounced filter fields on the same table must share one
useTableFiltersUrlState(keys)call (components/table), not oneuseListUrlState/useUrlSearchParamsUpdaterper field — independent debounced writers race (each rebuilds the URL from its own stalesearchParamssnapshot) and can silently drop each other's change.keysmust be a module-level constant array. - Detail → list back navigation restores the list's paging/filters via session-scoped storage, not a URL param — see AGENTS.md "Detail → list back navigation" and
lib/list-page/table-return-to. - Hub list URL key is
search; map it to the API query field (query,filter, etc.) inside the slice parser. Do not introduce a parallelqparam. - The API-client side of a paged list (request type, exported
buildList<Entity>Endpoint,list()returning a normalized page, a separate boundedlistAll()for pickers, which don't support lazy loading. Prefer list with paging where possible) has exactly one documented shape — see AGENTS.md "Paged list sort and calendar From/To → The one list-client shape" and its reference implementationlib/endatix-api/themes/. - Wired this way:
admin/tenants,admin/platform-admins,admin/signup-requests,settings/organization/users,settings/organization/roles,forms,forms/folders/[folderSlug],data-lists(DataListsBrowser), andforms/[formId]/submissions(server section). - Submissions list (
/forms/[formId]/submissions): loader + page-load outcome live infeatures/submissions/list-submissions/(not inapp/). URL parse helpers stay inlist-submission-query/. See AGENTS.md "Page-load outcomes". - Submissions grid on reporting data (
features/submissions/browse-submissions/): the grid that will replacelist-submissions, forked rather than layered: no shared internals withlist-submissionsorui/table, onlycomponents/tablechrome. It callsrememberSubmissionListReturnTofromlist-submission-querybecause the submission page's Back reads that store (it keeps filters and paging, notcolumns). The page picks it whenreportingExportFlag()is on, andSubmissionGridSectionrenders the legacy grid it is given whenGET forms/{formId}/reporting/columnsanswers 404. It owns its API client (lib/endatix-api/reporting/submission-grid.ts), URL state (submission-grid-url.ts: same keys as the legacy list pluscolumns, the visible answer keys), columns (submission-grid-columns.ts; answer column ids areanswer:<key>, metadata ids match the API's saved-viewMetadataKeys) and the readiness banner (grid-readiness.ts).SubmissionGridShellowns oneuseTableFiltersUrlStatewriter throughSubmissionGridUrlProvider; the toolbar and banner sit outside the keyedPagedListFrame, and the rows are a server section inside it so the out-of-range redirect stays on the server. Rows come fromSubmissionGrid.listRows(GET forms/{formId}/reporting/submissionswithcolumns=, at most 500 keys); an API without that endpoint (404) gets rows built fromGET forms/{formId}/submissionsinstead. Answer filters (submission-grid-answer-filters.ts) are URL keysanswer.{contains|from|to}.{key}(the key is the whole rest, so.and:in schema keys survive) and go to the API as repeatedanswer={operator}:{encodeURIComponent(key)}:{value}. Only columns with afilterTypeget a header filter (text: contains, date/datetime: From/To;searchable: falseand submitter columns get none); filters the catalog cannot apply are dropped by the canonical redirect. Thecontainskeys join the metadata text keys in the one debounced writer. Rows with answer filters never fall back to the submissions list; the rows section showsanswerFilterCoverageas a banner with Prepare / Include in-progress, and a 409reporting_not_preparedreads the page again without answer filters and says so. The form's shared view (GET/PUT forms/{formId}/reporting/submission-view,submission-grid-view.ts) fills in columns, page size and sort wherever the URL says nothing, so URL params still win; metadata visibility and order and column widths (resizable throughcomponents/table/column-resize-handle.tsx) live inSubmissionGridViewProvideruntil a form editor saves withsaveSubmissionGridViewAction(a 409 shows inline and reloads the view). While no view is saved, the first load moves the legacy grid'sehx_submissions_column_*localStorage keys into the unsaved view once (submission-grid-view-migration.ts) and never reads them again. - Audience (
/forms/[formId]/audience): behindpersonalizationFlag(FLAG_PERSONALIZATION/ PostHog keypersonalization, default off). Every server entry goes throughrequireAudienceAccess(permission)/requireAudienceApi(permission)(features/audience/shared/):requireAllPermissionsfor Hub access plusforms.view(page) orforms.edit/tenant.settings.manage(writes), then the flag, then anEndatixApi. Writes add revalidation inwithHubAudienceApi. The page uses the returnedcheckPermissionfor capabilities that must not redirect:Tenant.ManageSettings(match-key editor) andForms.Edit(canEdit: add, edit, rename and remove controls on People and Properties, and Audience coverage). A miss hides the control, Import CSV and Personalized links included (features/audience/import-csv/,features/audience/generate-links/, gated onforms.editlike the other writes). Personalized links go to the participants the list's search keeps: the panel counts them withGET links/preview?search=on every open, and Generate makes onePOST links/batcheswhose links carry their identifiers, because a token exists only in that one answer (personal-links.tswrites the file). An API without those routes answers a bare 404 (its own 404s areproblem+json,shared/missing-route.ts); the panel then keeps the oldPOST linksfor everyone, reading every page of people first for the identifiers (issue-links.server.ts, removed with that API's support), and a search on it says it needs a newer API./share/{formId}/a/{token}is a page that only renders on GET, so a mail scanner or link preview changes nothing; once it has mounted in a browser it redeems by POST (features/public-form/open-personal-link/, a server action, no Hub session), stores the submission token in the form cookie and replaces itself with/share/{formId}. A missing or invalid token shows "This link is not valid.", anything else offers Try again, and the page sends no Referer (endatix-hub#1211). Add property and the import wizard sharefeatures/audience/property-draft.ts:choicesError(the API's choice-key rule: at least one, none blank, no|, distinct by ordinal comparison),toCreateInput,isChoiceTypeandCHOICE_VALUE_SEPARATOR. Import CSV is a staged import (features/audience/import-csv/). The File step states the host's limits from the settings'importLimits: 100,000 rows and 50 MB with background jobs, 5,000 rows and 20 MB inline. It also refuses a file with a 1,000-row chunk over the server action body limit. A column named like no Property is queued to create one; the New properties step (only when one is queued) suggests its name and type from the whole file (type-suggestion.ts,new-properties.ts), warns on names the saved form already writes throughcheckPropertyNamesAction(thesurvey-lintcollision rule, run on the server so the linter stays out of the browser), and its Continue creates the Properties withcreateAudiencePropertyAction, then starts the import. Without a queued column, leaving Columns starts the import. The browser sends the chunks one at a time, because Next runs one server action at a time per client, so parallel sends would only queue. The send action checks the chunk's index and size again as a guard, never splitting a chunk: the API takes exactly 1,000 rows per index. While the import checks or writes, the panel reads it every 2 s, paused while the tab is hidden (use-audience-import.hook.ts). This is the one deliberate exception to the no-polling freshness rule (AGENTS.md"Freshness"), and the Hub reads the import, neverGET jobs/{id}. On mount the panel reads…/imports/currentand opens on an unfinished or stopped import. An upload cut off by a closed tab continues from a re-chosen file, matched by name, row count and header row only: a different file that matches all three would be staged as the same file, and the Check's counts before confirm are where the scripter sees it. A stopped write offers Resume, or Discard, which cancels it before a new import starts. The one-requestapi.audience.importCsvstays only for e2e seeding. The form itself comes from the sharedloadWorkspaceForm. The page only composes; load and paging live infeatures/audience/get-audience-page/. Coverage (the Used in form and Filled in columns, the People marks) is for form editors only:loadAudienceUsagereads the saved definition alongside the variables read (forms.editin the API), works out on the server what the form reads (registerCoreSurveyModelsfirst), and sends the browser only the Property names it reads and the counts. People are paged with?page=and?pageSize=, filtered with?test=, and searched by identifier with?search=; Back from a participant restores all of them (audience-return-to.ts). Test links (Copy test link, Download test links):testLinkAccess(features/audience/shared/test-link-access.server.ts) gives both to a reader withforms.testandforms.editonce a probe finds the API'sPOST …/audience/test-linksroute. The probe sendsmembershipIds: [], which that route's validator refuses with 400 before it reads anything, so it opens nothing; an older API answers 404. On an older API, Download test links is hidden and Copy test link keeps the open-then-mint path (copy-test-link/create-test-link.action.ts), which also needs a submissions grant and deletes the test submission when the mint fails. A 404 from the route itself is shown as is. Download test links ticks Test participants in the People table (features/audience/ui/use-participant-selection.hook.ts; ticks outlive a page or filter change, Remove drops one, Clear selection drops all) and writestest-links-<form>-<date>.csv(download-test-links/). The route's limits are inshared/test-link-limits.ts. Create/edit panel wiring: see PanelForm state below. Auth shape:AGENTS.md"Server Actions".
A create or edit overlay has three layers. Do not invent a fourth (no React Hook Form, no feature-wide form context).
Multi-step overlays keep the same three layers. The slice hook also owns the step, and the panel hands PanelForm the current step's labels, onBack and cancelable (DESIGN.md §6 Create / edit overlay). Split that hook by concern (the input read, the choices, the write, the step) and compose them in one exported hook. When the write's result is the outcome step (an import's counts and rejected rows), the slice hook keeps the result instead of toasting through the feature's mutation hook. Reference: features/audience/import-csv/use-import-csv.hook.ts, with pure parsing and suggestions in csv-preview.ts and column-map.ts beside it. A write that runs on the server after the panel's request (a staged import) keeps its state in a hook of its own, use-audience-import.hook.ts, and the step follows that state. create-tenant-panel.tsx predates this and keeps its state in the panel.
| Layer | Owns | Lives |
|---|---|---|
| Chrome | Header, body scroll, footer, failure strip, Cancel (or Back) + pending submit | components/common/panel-form.tsx (PanelForm) |
| Feature write lifecycle | pending / error, toast + router.refresh on success, failure stays in the overlay so values are kept |
One shared hook per feature that writes this way — audience: useAudienceMutation |
| Slice wiring | Draft fields, open/reset/lock-while-pending, submit → action + onSuccess: close |
Optional use-{noun}.hook.ts in the slice — reference: features/audience/create-person/use-add-person.hook.ts |
Shared panel primitives (same feature, several slices) stay next to the mutation hook, not inside one slice: audience uses usePanelOpen, useValueMap, useRowOverlay in use-panel-state.hook.ts.
One call site is fine. The slice hook is not extracted for reuse; it keeps the panel file as copy + PanelForm + field sections, and keeps DESIGN overlay rules (reset on open, refuse dismiss while pending, error in-panel) out of JSX. Mirror it for the next create panel (e.g. add property); do not merge create and edit into one generic hook — edit often differs (row-keyed open, save only changed fields: useEditPerson).
When to colocate instead: a tiny private useConfirm… used only by an AlertDialog in the same file is OK (confirm-delete-dialog.tsx). Prefer a use-*.hook.ts file when the return value spreads into PanelForm and a sibling edit hook already exists.
Root /forms supports three URL-driven modes (shareable, bookmarkable):
| Mode | URL | API scope | Folder shortcuts | Info alert |
|---|---|---|---|---|
| Unassigned browse (default) | /forms |
unassignedOnly |
Show | No |
| All forms browse | /forms?browse=all |
tenant-wide | Show | No |
| Global search/filter | ?search=… or status=… or visibility=… |
tenant-wide | Hide | Yes (Alert variant="info") |
| Folder browse | /forms/folders/[slug] |
folderId |
N/A | No |
Parsing and helpers live in features/forms/list-forms/utils.ts (parseFormsListParams, resolveRootFormsViewMode, shouldHideFolderShortcuts, isTenantWideFormsList). Breadcrumb dropdown options (Unassigned / All forms / folders) are built in features/folders/view-forms-header/build-forms-breadcrumb-model.server.ts with browse from header searchParams.
Follow-up PRs (not Phase 1):
- Phase 2 — Sorting: OSS
sortBy/sortDironGET /forms; Hub toolbarSelect+ URL params. - Phase 3 — Layout toggle:
layout=cards|tablewith compact table view for large lists. - Phase 4 — Pinning: Backend
UserFormPin+ pinned strip above list. - Phase 5 — Tasks: Assigned/review sections when collaboration exists.
Hub management grids follow the same URL + chrome pattern as forms/users. Parsing stays in the owning slice (not a new query slice).
| Surface | Slice | Hub URL | API |
|---|---|---|---|
| List | features/data-lists/view-lists/ |
search, hasLocale (single BCP-47 code), page, pageSize, action=create |
GET /data-lists (search, hasLocale) |
| Creator picker | features/data-lists/search-data-lists-for-picker/ |
(property grid; no Hub URL) | Same GET /data-lists via getDataListsPageResult |
| Detail items | features/data-lists/view-list-details/ |
search, page, pageSize, action=replace |
GET /data-lists/{id}/items (query) + GET /data-lists/{id}?includeItems=false |
- List → detail "Back to Data Lists" restores filters/paging via
BackToTableButton(tableKey: "data-lists"), not a URL param — see AGENTS.md "Detail → list back navigation". - Replacing items resets the items grid's
page/search(stale values from before the replace would otherwise point past the new item set). - Items are GET-only in Hub. Authors edit via file replace (
replace-items), not per-item CRUD. - Stream the paged promise from the App Router page into the client table (
use()insidePagedListFramewithlistQueryKey). Footer lives insideDataTableSurface. Items keepSuspenseinside the details client section. - Creator Translations CSV wrap lives in
lib/survey-features/data-lists/(compound keys + SurveyJS CSV merge). Hub actions stay infeatures/data-lists/translations/(uploadTranslationsCsvAction,getDataListTranslationCatalogAction). - Creator catalog picker vs bound-question items: Hub session
GET /data-lists(search-data-lists-for-picker) vs public item search (survey-bindings.ts+searchDataListChoices). Do not load the full catalog at Creator init.
- A component mounted by
app/layouts or@slotroute pages lives in its feature slice as{feature}-slot.tsx, not inline in theapp/file.app/stays orchestration: resolve session/params, render the slot. References:features/folders/view-forms-header/forms-folder-header-slot.tsx,features/platform-admin/assume-tenant/ui/support-access-banner-slot.tsx. - A slot mounted by a layout must be synchronous and own its
Suspenseboundaries internally.awaitin the slot (or in the layout) blocks every route under that layout — decide whether to render from data already in hand, and stream only the parts that need a fetch. - Slots call
*.server.tsloaders; they do not constructEndatixApithemselves.
- Server-only read-model loaders and helper orchestration
- Can live inside a slice (preferred) or feature root for shared server-only code
- Keep plain constants (logger names, revalidation paths) in a sibling
*.constants.ts, not in theserver-onlymodule. Importing one string otherwise drags@/authinto every consumer — including client components and unit tests. Example:features/platform-admin/tenant-management.constants.ts. - A list that can fail while the rest of the payload succeeds is
T[] | undefinedon the view model (undefinedfailed,[]loaded empty). Do not add a*Loadedflag or a second mapped copy. Full rule: AGENTS.md “Loaded list vs failed list”. Reference:FormsHeaderData.folders.
For optimal performance and UX, prefer streaming promises from Server Components to Client Components. Use the React use() hook to unwrap these promises. This prevents blocking the initial render while data is being fetched.
Recommended Pattern:
- Server Page/Component: Initiate the fetch and pass the promise (not the awaited result).
- Context Provider (Client): Accept the promise as a prop and use
use(promise)to resolve it.
// features/my-feature/ui/my-feature.context.tsx (Client Component)
'use client';
import { createContext, use, useMemo } from 'react';
export function MyFeatureClientProvider({ children, dataPromise }) {
const data = use(dataPromise); // Resolves via React Suspense
const value = useMemo(() => ({ data }), [data]);
return <MyContext value={value}>{children}</MyContext>;
}
// features/my-feature/ui/my-feature.provider.tsx (Server Component)
import { MyFeatureClientProvider } from './my-feature.context';
export function MyFeatureProvider({ children }) {
const dataPromise = getMyData(); // Start fetching locally on server
return (
<MyFeatureClientProvider dataPromise={dataPromise}>
{children}
</MyFeatureClientProvider>
);
}
// app/(main)/my-feature/page.tsx (Server Page)
export default async function Page() {
return (
<MyFeatureProvider>
<MyFeatureComponent />
</MyFeatureProvider>
);
}Combine use() with useReducer and useOptimistic for features with complex interactions (like forms or AI assistants).
// Example in FormAssistantProvider
export function FeatureProvider({ children, initialDataPromise }) {
const initialData = initialDataPromise ? use(initialDataPromise) : defaultState;
const [state, dispatch] = useReducer(reducer, initialData);
const [optimisticState, setOptimisticState] = useOptimistic(state, (s, u) => ({ ...s, ...u }));
const handleAction = async (payload) => {
setOptimisticState({ isPending: true }); // Immediate UI feedback
const result = await myServerAction(payload); // Next.js Server Action
dispatch({ type: 'UPDATE', payload: result });
};
const value = useMemo(() => ({ state: optimisticState, handleAction }), [optimisticState]);
return <MyContext value={value}>{children}</MyContext>;
}- Thin Providers: Keep context providers focused on data sharing and state management.
- Custom Hooks: Expose context via hooks (e.g.,
useAssetStorage) to provide a clean API. - Server-Side Providers: Use Server Component wrappers (like
AssetStorageProvider) to orchestrate configuration and data fetching on the server. - Zero-Latency Orchestration: By using Server Components for providers, we can pass unresolved promises to the client. This allows the page to start streaming immediately while SAS tokens or other data are generated on the server, avoiding extra HTTP round-trips from the client.
- Reference Implementations:
asset-storage.context.tsx: Clean configuration streaming and client-side state.asset-storage.provider.tsx: Server Component orchestration.form-assistant.context.tsx: Complex state with optimistic updates and reducer.
More on this in the Next.js Data Fetching Documentation.
- kebab-case:
create-form.action.ts,view-forms-header/ - Functions:
camelCase→createFormUseCase - Classes/Types:
PascalCase→CreateFormRequest
- Use-cases:
{verb-noun}.use-case.ts(optional) - Actions:
{verb-noun}.action.ts - Server-only helpers:
{verb-noun}.server.ts - Hooks:
use-{noun}.hook.ts - Components:
{feature-name}-{purpose}.tsx
app/
├── (main)/ # Main application routes
│ ├── dashboard/
│ ├── forms/
│ ├── settings/
│ └── ...
├── (public)/ # Public routes
│ ├── share/
│ └── ...
├── api/ # API routes
├── globals.css
└── layout.tsx
Keep /app focused on Next.js routing only - no business logic.
- Multiple consumers - Used by multiple apps/projects
- Independent versioning - Can be versioned separately
- Clear API boundaries - Well-defined public interface
- No framework coupling - Not tied to Next.js/React
{
"name": "@endatix/api-client",
"version": "1.0.0",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"exports": {
".": "./dist/index.js",
"./types": "./dist/types.js"
},
"peerDependencies": {
"react": "^19.0.0"
}
}// package.json (root)
{
"workspaces": ["apps/*", "packages/*"]
}- Start with a slice - Create
{verb-noun}/and co-locate action, UI, tests, and exports - Keep actions thin - Wrap API calls and orchestration, move complex logic to helpers/use-case files
- Co-locate related code - Keep slice internals inside the slice folder
- Use slice exports first - Import from
features/{name}/{verb-noun}before feature-level barrels - Move to lib/ when reusable - Extract to lib/ when used across projects
- Move to packages/ when publishable - Extract to packages/ when ready for npm
- Document Architecture Updates - Any new architectural items, patterns, or cross-cutting features discovered during planning or development must be documented in a dedicated
ARCHITECTURE.mdfile in the root of the project.
hub/
├── lib/ # Internal utilities
│ ├── endatix-api/ # API client (internal)
│ ├── localization/ # Multi-lingual domain (catalog, submission locale, future i18n)
│ ├── survey-js/ # Shared SurveyJS + Creator types/vocab (vendor first, Hub supersets)
│ └── utils/ # Shared utilities
├── features/ # App-specific features
│ ├── config/ # App configuration
│ ├── auth/ # Auth business logic
│ └── forms/ # Form management
└── packages/ # Future workspace packages
Use lib/localization for cross-feature multi-lingual infrastructure, organized as slices:
| Slice | Responsibility |
|---|---|
catalog/ |
SurveyJS ↔ owned catalog vocabulary (default ↔ "" / runtime default code), culture-code normalize/validate, toCatalogLocales, display names |
submission-locale/ |
Submission metadata language helpers shared by submissions UI and pdf-export |
routing/ (future) |
Locale-prefixed Hub routes / middleware |
messages/ (future) |
Hub UI copy catalogs (e.g. next-intl) |
Keep selection policy in the owning feature (e.g. public-form language picker priority: preselected → localStorage → survey model → browser). Do not move feature-specific preference storage or init order into lib/.
Import from @/lib/localization (root barrel) or a slice path such as @/lib/localization/catalog.
Audience values inside a form. It is cross-feature: the public form, the designer, the Audience tab and Diagnostics all read it, so none of them owns it. It has two entries, one per runtime:
| Path | Runtime | Owns | Consumers |
|---|---|---|---|
apply-personalization.ts |
respondent | Snapshot values onto a survey model | features/public-form, features/audience/preview-as |
snapshot-source.ts |
any | A Snapshot's source label | Test inspector, Submission Details |
to-survey-presets.ts |
any | Wire presets → ISurveyVariablePresets, shared by both entries |
authoring/, coverage/ |
coverage/ (@/lib/personalization/coverage) |
server-safe | What the form reads (audienceUsage, lintedUsage), coverage verdicts (usageVerdicts), the Audience findings (reviewAudience) and their types |
load-audience-usage.server.ts, the Audience tab, the designer (lazily), Diagnostics (types, through the authoring re-export) |
authoring/ (@/lib/personalization/authoring) |
client | The Creator binding (bindAudienceToCreator), Preview as, Find participant, the designer's save body, applying a fix to the canvas |
features/forms/ui/editor, the design page (types) |
coverage/ is survey-core only and imports nothing from authoring/; no-client-imports.test.ts fails on a React, lucide, Creator or "use client" import there, and on any import outside survey-core, survey-lint, the API types, to-survey-presets and coverage/ itself. Server files that need an authoring/ contract type use import type. Import only through the two index.ts files (eslint no-restricted-imports), with one exception: the coverage verdicts (usageVerdicts) have their own browser entry, @/lib/personalization/coverage/audience-usage, and the coverage index exports only their types. The index brings survey-core/linter, and Turbopack keeps it in a client bundle even when only the verdicts are used (+135 KB on the Audience tab).
The one home for definition analysis: checks that need only the survey JSON. Server-safe and UI-free: survey-core and survey-core/linter only, nothing from lib/personalization, form-diagnostics or features/ (pinned by __tests__/no-client-imports.test.ts). It holds the Hub's only lintSurvey call (runLint). Import from @/lib/survey-features/survey-lint.
What goes where:
- A check that needs only the definition (unknown references, collisions, undeclared roots, a SurveyJS rule subset) →
survey-lint. - A check that needs Audience data (Properties, participants, counts) →
lib/personalization/coverage, built onsurvey-lint. To learn which Properties a form reads, callaudienceUsage; do not scan again. - Rendering findings →
lib/survey-features/form-diagnostics/ui/. - Applying a lint fix to the Creator canvas is Creator-side, never
survey-lint: it stays inpersonalization/authoringwhile the binding is its only caller.
Shared SurveyJS + Creator types/vocab only — no behavior, no choice helpers. Vendor types first; Hub unions close vendor strings.
| Path | Owns |
|---|---|
lib/survey-js/creator/tabs.ts |
Creator tab ids — ENDATIX_CREATOR_TAB (built-ins + Hub plugin tabs) and canonicalizeCreatorTabId |
lib/survey-js/creator/tab-url.ts |
?tab= slug ↔ tab id (design → designer; Design omits the param) |
Vocab only here. Creator tab/JSON behavior: lib/survey-features/survey-design/ (ui/use-creator-tab-url.ts, ui/use-creator-json.ts, use-cases/). Do not re-declare vendor types (Question, SurveyCreatorModel). Rules: AGENTS.md (SurveyJS domain).
Import from @/lib/survey-js.
endatix-saas/
├── apps/
│ └── hub/ # Next.js application
└──packages/
├── @endatix/api-client/ # API client package
├── @endatix/ui/ # UI components package
├── @endatix/config/ # Configuration package
└── @endatix/utils/ # Utilities package
- lib/endatix-api/ → packages/@endatix/api-client/
- Includes shared list wire helpers (
SortRequest,DateRangeFilter,list-query.ts,query-params.ts,paged-response.ts). Keep new sort/range contract code inlib/endatix-api/shareduntil that extract; do not place it underfeatures/orlib/date-utils(formatters).lib/endatix-api/themes/is the reference module shape for the extract.
- Includes shared list wire helpers (
- lib/utils/ → packages/@endatix/utils/
- features/config/ → packages/@endatix/config/
- features/auth/ → Keep in apps/hub/features/auth/ (app-specific)