# Front End Documentation

Front-end documentation for the Synthex monorepo.

**New here?** Start with [Contributing](../CONTRIBUTING.md) to get the project running and learn how changes ship, then [Project Structure](./guidelines/PROJECT_STRUCTURE.md) to learn where code goes.

## Getting started

| Doc | What it covers |
| --- | --- |
| [Contributing](../CONTRIBUTING.md) | Requirements, Git LFS, running locally, branch and commit rules, pull request workflow, and the full npm command reference |
| [Environment files](./ENV_FILE.md) | Generating `.env` with the 1Password CLI, and mock-API variables |

## Guidelines — [`guidelines/`](./guidelines/)

How to write code here. These are the source of truth; the `.cursor/rules/*.mdc` files point at them.

| Doc | What it covers |
| --- | --- |
| [Frontend standards](./guidelines/FRONTEND_STANDARDS.md) | The bar every change is held to: architecture, scalability, ownership, reliability, state, design patterns, testing, and delivery |
| [Project Structure](./guidelines/PROJECT_STRUCTURE.md) | Monorepo layout, every package, [which folder rules apply where](./guidelines/PROJECT_STRUCTURE.md#which-folder-rules-apply-where), linter, view naming, state management, generated files |
| [TypeScript](./guidelines/TYPESCRIPT.md) | Strict typing, imports and aliases, code patterns |
| [React Components](./guidelines/REACT_COMPONENTS.md) | Component structure, typing, hooks, a11y pointers, route views (`{domain}-{action}-view`) |
| [Styling and Theme](./guidelines/STYLING_AND_THEME.md) | SCSS functions, mixins, breakpoints, and the complete color token list |
| [Code Comments](./guidelines/CODE_COMMENTS.md) | When to comment, TSDoc for generated docs, which files' comments are protected |
| [Forms](./guidelines/FORMS.md) | The `createForm` factory, view usage, and Zod validation |
| [API Handling](./guidelines/API_HANDLING.md) | `useApi` queries and mutations, [fetch placement](./guidelines/API_HANDLING.md#fetch-placement) / provider error contract, pagination, cache invalidation, `WsClient` |
| [UX quality](./guidelines/UX_QUALITY.md) | Accessibility, copy/i18n, error/empty UX, and performance soft standards |

### Patterns — [`guidelines/patterns/`](./guidelines/patterns/)

Recipes for features that already exist and should be copied rather than reinvented.

| Doc | What it covers |
| --- | --- |
| [Filters and Search Params](./guidelines/patterns/FILTERS_AND_SEARCH_PARAMS.md) | The two-layer filter architecture: `useEnhancedUrlParams` plus per-feature filter hooks |
| [Column Visibility](./guidelines/patterns/COLUMN_VISIBILITY.md) | Optional table columns via `useTableColumnVisibility` with persisted UI settings |
| [Tables](./guidelines/patterns/TABLES.md) | List `Table` wiring: filters, sort, empty/loading, row actions (not `DataTable`) |
| [Modals](./guidelines/patterns/MODALS.md) | `useConfirmationModal` for destructive actions; custom `Modal` flows |
| [Routing](./guidelines/patterns/ROUTING.md) | `route-registry` + `view-resolver`, lazy `{domain}-{action}-view` modules |
| [RBAC UI](./guidelines/patterns/RBAC_UI.md) | Capabilities via `usePermissions` / `PermissionGate` at route, nav, and inline UI |
| [MFE host](./guidelines/patterns/MFE_HOST.md) | Job-correction: in-monorepo package import vs remote `MfeIntegrationClient` |
| [Search](./guidelines/patterns/SEARCH.md) | Global cross-entity search and the reusable search input components |
| [Conversation Features](./guidelines/patterns/CONVERSATION_FEATURES.md) | The real-time conversation system: factory, adapters, and WebSocket wiring |
| [Feedback](./guidelines/patterns/FEEDBACK.md) | Shared feedback hook, form, and modal across executions and messages |

## Decision records — [`decision-records/`](./decision-records/)

Cross-cutting forks the team locked in. Index: [`decision-records/README.md`](./decision-records/README.md). How to write one: [Write a decision record](./guides/WRITING_DECISION_RECORDS.md).

## Architecture — [`architecture/`](./architecture/)

Deployable apps and the core patterns used across them.

| Doc | What it covers |
| --- | --- |
| [App Anatomy](./architecture/APP_ANATOMY.md) | Shared app bootstrap: `mountApp`, providers, `createAuthApp` |
| [Front Office](./architecture/APP_FRONT_OFFICE.md) | End-user SPA (Vite) |
| [Back Office](./architecture/APP_BACK_OFFICE.md) | Admin / configuration SPA (Vite) |
| [Dynamic UI Editor](./architecture/APP_DYNAMIC_UI_EDITOR.md) | Editor app for the dynamic-ui engine |
| [Job Correction MFE](./architecture/APP_JOB_CORRECTION_MFE.md) | Microfrontend for flow execution result correction |
| [Maintenance](./architecture/APP_MAINTENANCE.md) | Standalone maintenance / fallback page |
| [State Management](./architecture/STATE_MANAGEMENT.md) | Which tool to use for server, form, UI, URL, and preference state |
| [Routing](../src/lib/app-shell/README.md) | `RouteRegistry`, `ViewResolver`, private/permission gates |
| [Theming](../src/lib/theme-provider/README.md) | Branding-aware `ThemeProviderStyled` / `Unstyled` |
| [Microfrontend](../src/lib/microfrontend/README.md) | SystemJS MFE client/provider and Shadow DOM mounting |
| [Form Validation](../src/lib/form/README.md) | Global Zod config and `createForm` validation rules |
| [Error Handling](../src/lib/error-boundary/README.md) | Error boundaries + `errorService` / Sentry |
| [Authentication](../src/lib/app-shell/AUTH.md) | OAuth 2.0 session flow, token refresh, RBAC, WebSocket auth |
| [API Client](../src/lib/api-client/README.md) | The `@synthexhq/fe-api-client` package and regenerating types from OpenAPI |
| [API Client WS](../src/lib/api-client-ws/README.md) | The `@synthexhq/fe-api-client-ws` package, `WsClient`, and AsyncAPI types |
| [Mock API Server](../src/test/mock-api-server/README.md) | Running and configuring the mock server: modes, delays, troubleshooting |
| [Dynamic UI](../src/lib/dynamic-ui/README.md) | The runtime-driven UI renderer and visual builder |

## Features — [`features/`](./features/)

One flat file per domain — `docs/features/<FEATURE_NAME>.md` (e.g. `ASSISTANT.md`). Front Office / Back Office specifics are **inlined** as sections in that file. Do **not** use `docs/features/<slug>/README.md` or separate `FRONT_OFFICE.md` / `BACK_OFFICE.md` files.

Template: [`templates/FEATURE.md`](./templates/FEATURE.md).

| Doc | What it covers |
| --- | --- |
| [Platform](./features/PLATFORM.md) | Tenant allowlist and cross-domain entity registry |
| [Assistant](./features/ASSISTANT.md) | Versioned AI assistants and FO chat entry |
| [Branding](./features/BRANDING.md) | Company logo, colors, Teams bot assets |
| [Calendar](./features/CALENDAR.md) | Calendar list and OAuth sync |
| [Conversation](./features/CONVERSATION.md) | Conversation list/detail and admin inspection |
| [Data Model](./features/DATA_MODEL.md) | Data model CRUD and versioning |
| [Data Point](./features/DATA_POINT.md) | Evaluation data points and runs |
| [Data Source](./features/DATA_SOURCE.md) | Knowledge-base data source list items |
| [Developer](./features/DEVELOPER.md) | Admin bulk-delete tools |
| [Email](./features/EMAIL.md) | Email browsing and inbox management |
| [Evaluation](./features/EVALUATION.md) | Evaluation CRUD and runs |
| [File](./features/FILE.md) | File manager, folders, upload |
| [Flow](./features/FLOW.md) | Flow definition CRUD and canvas |
| [Flow Execution](./features/FLOW_EXECUTION.md) | Flow execution lifecycle and dynamic UI |
| [Home](./features/HOME.md) | FO/BO home dashboards |
| [Transfer](./features/TRANSFER.md) | Entity import wizard and export |
| [Knowledge Base](./features/KNOWLEDGE_BASE.md) | RAG knowledge base configuration |
| [Meeting](./features/MEETING.md) | Meetings and summary config |
| [Node](./features/NODE.md) | Node CRUD and node executions |
| [Process](./features/PROCESS.md) | Process definition CRUD |
| [Process Execution](./features/PROCESS_EXECUTION.md) | Process execution lifecycle and chat |
| [Project](./features/PROJECT.md) | Project CRUD |
| [Rename](./features/RENAME.md) | Shared rename modal/hook |
| [Role](./features/ROLE.md) | Roles and permissions |
| [Scheduling](./features/SCHEDULING.md) | Cron triggers on nodes/flows |
| [Search](./features/SEARCH.md) | FO global search route/config |
| [Secret](./features/SECRET.md) | Encrypted secrets |
| [Settings](./features/SETTINGS.md) | Teams, calendar sync, UI preferences |
| [Team](./features/TEAM.md) | Team CRUD and members |
| [Triage](./features/TRIAGE.md) | Triage configuration and results |
| [Usage Metrics](./features/USAGE_METRICS.md) | Usage metrics dashboard and print |
| [User](./features/USER.md) | Users and impersonation settings |
| [Project Variable](./features/PROJECT_VARIABLE.md) | Project/runtime variables |

## Guides — [`guides/`](./guides/)

| Doc | What it covers |
| --- | --- |
| [Write a decision record](./guides/WRITING_DECISION_RECORDS.md) | When and how to add a cross-cutting decision under `docs/decision-records/` |
| [Mock API Workflow](./guides/MOCK_API_WORKFLOW.md) | Spec-first endpoint creation for REST (OpenAPI) and WebSocket (AsyncAPI) |
| [Unit Testing](./guides/TESTING_UNIT.md) | Jest unit tests: `spec/` placement, Testing Library templates, mocks, and how to run them |
| [Integration Testing](./guides/TESTING_INTEGRATION.md) | Jest integration tests: when to use them, `*.integration.test.*` naming, server-backed patterns |
| [E2E Testing](./guides/TESTING_E2E.md) | Playwright e2e: auth projects, fixtures, journey templates, local vs `E2E_TEST_URL` |
| [Accessibility Testing](./guides/TESTING_ACCESSIBILITY.md) | Playwright CT a11y: `AccessibilityTest`, axe, aria snapshots (`*.snapshot.test.tsx`) |
| [Visual Testing](./guides/TESTING_VISUAL.md) | Playwright visual regression: mocking, templates, Docker, snapshots, CI, plus a quick reference |
| [Deployment](./guides/DEPLOYMENT.md) | Manual and GitHub Actions deployment to Azure Static Web Apps, including prerequisites |
| [Release](./guides/RELEASE.md) | Semantic Release, package versioning, and publishing to registries |
| [Iterate on a ui-lib component](./guides/ITERATE_UI_LIB_COMPONENT.md) | Changing a design system component and updating its consumers and tests |
| [Scope validation](./guides/SCOPE_VALIDATION.md) | One concern per PR: slice order, path heuristics, pass/warn/fail, author and reviewer workflows |
| [Code quality validation](./guides/CODE_QUALITY_VALIDATION.md) | Line-by-line review checklist (correctness, conventions, TypeScript); agent posting behavior lives in `code-quality-validation.mdc` |
| [Architecture validation](./guides/ARCHITECTURE_VALIDATION.md) | Structural review: layering, package boundaries, coupling; Architecture section via `architecture-validation.mdc` |
| [Documentation validation](./guides/DOCUMENTATION_VALIDATION.md) | Docs gap analysis, addition quality, duplicates / wrong home, hub links; Documentation section via `documentation-validation.mdc` |
| [Accessibility validation](./guides/ACCESSIBILITY_VALIDATION.md) | A11y checklist (semantics, names, keyboard, focus); file comments via `accessibility-validation.mdc` (PR review automation) |
| [Performance validation](./guides/PERFORMANCE_VALIDATION.md) | Runtime performance checklist (lazy routes, compiler vs memo, lists); file comments via `performance-validation.mdc` (PR review automation) |
| [Security validation](./guides/SECURITY_VALIDATION.md) | Client security checklist (secrets, XSS, auth/RBAC trust); Security section via `security-validation.mdc` |
| [Plan creation](./guides/PLAN_CREATION.md) | Draft FE sub-plans: recon, product/business-logic bar, write location, Suggested PR mapping |
| [Plan implementation](./guides/PLAN_IMPLEMENTATION.md) | Implement FE sub-plan sections: target selection, scope discipline, author/reviewer workflows |
| [Cursor agents, rules, and automations](./guides/CURSOR_AGENTS_RULES_AUTOMATIONS.md) | Dependency model: automation → agent → rule → docs; what belongs at each layer; inverse rule for agent-only content |

## CI/CD and operations

| Doc | What it covers |
| --- | --- |
| [Preview Environments](./PREVIEW_ENVIRONMENTS.md) | Branch-scoped GitHub Pages previews for apps, Storybook, docs, and test reports |

## Templates — [`templates/`](./templates/)

| Doc | What it covers |
| --- | --- |
| [Decision record](./templates/DECISION_RECORD.md) | Blank form for `docs/decision-records/00N-*.md` |
| [Feature](./templates/FEATURE.md) | Blank form for `docs/features/<FEATURE_NAME>.md` |
| [Plan](./templates/PLAN_TEMPLATE.md) | Blank form for FE repository sub-plans (Synthex-global planning) |

## Rule to doc mapping

Each `.cursor/rules/*.mdc` file is a short pointer holding only the non-negotiables. The detail lives in the doc it links to.

| Rule | Detail lives in |
| --- | --- |
| `global.mdc` (always applied) | [Project Structure](./guidelines/PROJECT_STRUCTURE.md), [Frontend standards](./guidelines/FRONTEND_STANDARDS.md) |
| `typescript.mdc` | [TypeScript](./guidelines/TYPESCRIPT.md), [Code Comments](./guidelines/CODE_COMMENTS.md) |
| `react-components.mdc` | [React Components](./guidelines/REACT_COMPONENTS.md), [Styling and Theme](./guidelines/STYLING_AND_THEME.md) |
| `forms.mdc` | [Forms](./guidelines/FORMS.md) |
| `api-handling.mdc` | [API Handling](./guidelines/API_HANDLING.md) |
| `mock-api-openapi-schemas.mdc` | [Mock API Workflow](./guides/MOCK_API_WORKFLOW.md) |
| `code-quality-validation.mdc` | [Code quality validation](./guides/CODE_QUALITY_VALIDATION.md); pairs with `.cursor/agents/code-quality-validator.md` |
| `scope-validation.mdc` | [Scope validation](./guides/SCOPE_VALIDATION.md); pairs with `.cursor/agents/scope-validator.md` |
| `architecture-validation.mdc` | [Architecture validation](./guides/ARCHITECTURE_VALIDATION.md); pairs with `.cursor/agents/architecture-validator.md` |
| `documentation-validation.mdc` | [Documentation validation](./guides/DOCUMENTATION_VALIDATION.md); pairs with `.cursor/agents/documentation-validator.md` |
| `accessibility-validation.mdc` | [Accessibility validation](./guides/ACCESSIBILITY_VALIDATION.md); pairs with `.cursor/agents/accessibility-validator.md` |
| `performance-validation.mdc` | [Performance validation](./guides/PERFORMANCE_VALIDATION.md); pairs with `.cursor/agents/performance-validator.md` |
| `security-validation.mdc` | [Security validation](./guides/SECURITY_VALIDATION.md); pairs with `.cursor/agents/security-validator.md` |
| `dependency-upgrade.mdc` | [Contributing](../CONTRIBUTING.md), [Frontend standards](./guidelines/FRONTEND_STANDARDS.md); pairs with `.cursor/agents/dependency-upgrader.md` (weekly automation + chat; no dedicated guide) |
| `cursor-agents-rules-automations.mdc` | [Cursor agents, rules, and automations](./guides/CURSOR_AGENTS_RULES_AUTOMATIONS.md) |
| `task-preparation.mdc` | Self-contained agent workflow |
| `plan-building.mdc` | [Plan creation](./guides/PLAN_CREATION.md); form via [Plan template](./templates/PLAN_TEMPLATE.md); Suggested PR sizing via [Scope validation](./guides/SCOPE_VALIDATION.md); pairs with `.cursor/agents/plan-builder.md` |
| `plan-implementation.mdc` | [Plan implementation](./guides/PLAN_IMPLEMENTATION.md); pairs with `.cursor/agents/plan-implementator.md` |

When a convention changes, update the doc first. Only update the rule if the change touches one of its non-negotiables.

## Generated API reference (TypeDoc)

TypeDoc output from source comments is published under [`public/generated/`](./public/generated/) and regenerated with `npm run docs`. The TypeDoc site landing page is [`public/README.md`](./public/README.md).

When browsing the generated docs:

1. Use the package list in the left sidebar
2. Search for any reference in the top right corner
3. API references are generated from TypeScript definitions, so they stay in sync with the code
4. Examples and guides are included where applicable
5. Changelogs are available for each package