> ## Documentation Index
> Fetch the complete documentation index at: https://getoverlay.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Adding Feature Modules

> Package boundaries, module checklist, and settings panel registration.

Feature modules should keep behavior reusable without coupling presentational UI to the web runtime.

## Package Boundaries

* `@overlay/app-core`: shared contracts, app shell registries, and renderless controller helpers.
* `@overlay/api-client`: typed transport wrappers for the web `/api/v1/*` routes.
* `@overlay/ui`: low-level primitives and design tokens.
* `@overlay/modules-react`: React DOM presentational components for feature modules.
* `src/features/<domain>/*`: web containers and feature-local helpers that bind routing, auth, Convex-backed APIs, uploads, billing, and local browser APIs.
* `src/components/{ui,layout,providers}/*`: shared UI primitives, app chrome, and runtime providers.

Presentational components must accept data and callbacks only. They must not import `fetch`, `next/navigation`, auth contexts, Convex, or `overlayAppClient`. Run `npm run check:module-boundaries` before committing module package changes.

## Module Checklist

1. Add cross-surface contracts to `@overlay/app-core`.
2. Add typed methods to `@overlay/api-client` that call existing `/api/v1/*` routes without changing endpoint behavior.
3. Put pure selection, filtering, sorting, dirty-state, and tree-building logic in `@overlay/app-core/modules`.
4. Put React DOM presentation in `@overlay/modules-react`, built from `@overlay/ui`.
5. Keep the web screen as a container that wires router, auth, upload flows, billing, local storage, and client methods into the shared module.
6. Add Storybook stories that import public package APIs only.

## Settings Panels

Register panel metadata in `src/overlay.config.ts`:

```ts theme={null}
settingsPanels: [
  {
    id: 'security',
    sectionId: 'account',
    label: 'Security',
    componentKey: 'acme.settings.security',
    order: 25,
  },
]
```

Then map `componentKey` to a local renderer in the web settings container. Other surfaces can reuse the registry metadata and provide their own renderer for the same key.

## Extending UI Primitives

Prefer composition over editing existing primitives. Add a new primitive to `@overlay/ui` only when it is broadly reusable and can preserve the current visual language. Feature-specific surfaces belong in `@overlay/modules-react`.