Project Folder Structure

Developer guide to the repository layout, key folders, and how the pieces fit together.

Project Folder Structure

This page gives you a quick tour of the repository so you can find things fast.

Top-level layout

.
├─ api/                     # Utility/serverless scripts (e.g., SCSS pre-processing)
├─ dist-widget/             # Production build of the embeddable widget (static assets)
├─ dist-widget-debug/       # Debug build of the embeddable widget (+ maps & demo assets)
├─ docs/                    # Documentation site (Mintlify) content
├─ public/                  # Static assets served by Vite at the site root
├─ scripts/                 # Maintenance utilities (e.g., i18n tooling)
├─ src/                     # Application source (React + TypeScript)
├─ widget/                  # Standalone widget demo/host page and locales
├─ dev.mjs                  # Local dev helpers
├─ i18next-parser.config.cjs# i18n extraction config
├─ index.html               # Vite root HTML (app entry in dev/prod)
├─ jest.config.js           # Jest configuration (if/when used)
├─ vite.config.ts           # Vite configuration for builds and dev server
├─ vitest.config.ts         # Vitest configuration for unit tests
├─ vitest.setup.ts          # Test setup (jsdom, mocks, etc.)
├─ tsconfig*.json           # TypeScript configuration(s)
├─ bun.lockb                # Bun lockfile
├─ package.json             # Scripts and dependencies
└─ vercel.json              # Vercel deployment config (for docs or widget hosting)

Source code (src/)

• api/ – Client-side API helpers (endpoints, fetch wrappers, param parsing, suspense wrappers)
• assets/ – Static assets used by the app (images, data, SCSS sources)
• components/ – Reusable UI components
• errorBoundries/ – Error boundary components and fallbacks
• helpers/ – Pure helper utilities and formatting helpers
• hooks/ – Reusable React hooks
• layouts/ – Layout wrappers (shared chrome)
• routes/ – Route-level components and loaders
• states/ – Global or module-level state containers
• transitions/ – Animation/transition helpers
• types/ – TypeScript type definitions
• utils/ – Generic utilities not tied to React
• views/ – Page-level or feature-complete views
• Root files
  • App.tsx – App root
  • main.tsx – Vite entry
  • i18n.ts – i18next initialization
  • widget.tsx – Widget bootstrapping/entry

Builds and distributions

• dist-widget/ – Production bundle of the widget and its assets. This is what you deploy/embed.
• dist-widget-debug/ – Debug build (includes source maps and demo assets for easier testing).

Static assets (public/)

Files in public/ are served as-is at the site root by Vite. Use this for icons, manifest, and images that should not pass through the bundler.

Documentation (docs/)

Mintlify-powered documentation lives here. MDX pages are organized by topic (e.g., api/, overview/, customisation/). The navigation is defined in docs/docs.json.

Scripts and utilities

• api/scss-to-css.ts – SCSS-to-CSS processing script (used in build/deploy pipelines)
• scripts/ – i18n and maintenance utilities; for example translate-missing.mjs and ignored translations lists.

Widget demo (widget/)

Contains a minimal host page (index.htm) and locales for trying the widget in isolation.

Testing

• vitest.config.ts, vitest.setup.ts – Unit test configuration (Vitest)
• jest.config.js – Jest config (kept for compatibility in some environments)

Notes

• Build and dev flows are handled by Vite. Check package.json scripts for standard commands.
• Internationalization is i18next-based; see src/i18n.ts and public/locales/*.