187 lines
19 KiB
Markdown
187 lines
19 KiB
Markdown
# CRM Decision Report
|
|
|
|
## Decision
|
|
|
|
Decision: `extract-plugin`.
|
|
|
|
CRM is an optional CRM vertical/plugin candidate, not boilerplate Core and not an immediate-removal target. The retained core should provide auth, tenancy, admin/app shell, rows/entities runtime, transactional email, and stable extension points; CRM should own its product opinion around companies, contacts, opportunities, submissions, marketing subscriber state, CRM-specific routes, icons, commands, translations, and any Email Marketing coupling that depends on contacts as campaign recipients.
|
|
|
|
This slice does not change runtime code. It records the canonical decision and execution order for a later extraction/removal slice.
|
|
|
|
## Scope
|
|
|
|
In scope for this decision:
|
|
|
|
- Classify CRM as an optional plugin/vertical with action `extract-plugin`.
|
|
- Identify current CRM surfaces and couplings that a future extraction/removal task must audit.
|
|
- Preserve retained CRM code, data, and docs surfaces until a dedicated implementation slice moves or removes CRM. Default core route registration disables CRM route trees.
|
|
- Define a sequential, atomic execution plan and verification plan for later work.
|
|
|
|
Out of scope for this decision:
|
|
|
|
- Deleting CRM routes, modules, entity templates, translations, or command entries in this slice.
|
|
- Refactoring Email Marketing, Rows/Entities, user sync, or sidebar code in this slice.
|
|
- Deciding final packaging mechanics for a future plugin runtime beyond the extraction order and required checks.
|
|
|
|
Human-review notes that should not block execution:
|
|
|
|
- Confirm whether Email Marketing remains a plugin that depends on CRM contacts, or whether it should introduce a separate audience/list abstraction before CRM extraction.
|
|
- Confirm whether existing installations with CRM entities should receive a migration path, export instructions, or compatibility shim before CRM is disabled by default.
|
|
- Confirm whether `submission` remains part of CRM or is split into a generic contact-form/audience plugin.
|
|
|
|
## Current Code Surfaces
|
|
|
|
The current known CRM surfaces are retained plugin-candidate code surfaces. Route paths listed here are not active default core route registrations:
|
|
|
|
| Surface | Current role | Future handling |
|
|
| --- | --- | --- |
|
|
| `apps/web/app/modules/crm` | CRM module root; currently includes `apps/web/app/modules/crm/services/CrmService.ts`. | Move to plugin package/module or delete only after dependents are removed. |
|
|
| `apps/web/app/modules/crm/services/CrmService.ts` | Validates CRM entity presence and reads/writes company/contact/opportunity/submission rows; handles contact form, newsletter fallback, ConvertKit fallback, user sync helpers, and CRM summaries. | Plugin-owned service; extraction must replace core callers with an interface, feature flag, or no-op path. |
|
|
| `apps/web/app/routes/admin/crm.tsx` | Admin CRM layout route; validates CRM entities and builds CRM icon navigation including Overview, entity routes, and Sync. | Plugin admin route shell. |
|
|
| `apps/web/app/routes/admin/crm/*` | Admin CRM nested routes for overview/entity/sync flows. The current filesystem contains `apps/web/app/routes/admin/crm` as the route directory. | Move/delete atomically with admin CRM layout and route registration. |
|
|
| `apps/web/app/routes/app.$tenant/crm.tsx` | Tenant CRM layout route; validates tenant CRM entities and builds tenant CRM icon navigation. | Plugin tenant route shell. |
|
|
| `apps/web/app/routes/app.$tenant/crm/*` | Tenant CRM nested routes for overview/entity flows. The current filesystem contains `apps/web/app/routes/app.$tenant/crm` as the route directory. | Move/delete atomically with tenant CRM layout and route registration. |
|
|
| `apps/web/app/modules/templates/defaultEntityTemplates.ts` | Defines `CRM_ENTITIES_TEMPLATE` for `company`, `opportunity`, `contact`, and `submission` plus relationships. | Decide whether the template is plugin-owned, installable as optional seed data, or removed from default template loading. |
|
|
| `apps/web/app/utils/api/.server/EntitiesApi.ts` | Provides CRM-specific entity route generation for admin CRM and tenant CRM paths. | Remove CRM branches from core or make route generation plugin-aware. |
|
|
| `apps/web/app/services/command-registry/commandRegistry.ts` | Owns command palette actions. CRM command entries are currently absent from the generic registry. | Keep CRM commands out of core or register them through plugin command contribution. |
|
|
| `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` | Imports `CrmService` and `ContactDto`; campaign previews/sends require contact rows, `marketingSubscriber`, and contact variable replacement. | Must be audited before CRM extraction; Email Marketing either depends on CRM plugin or receives its own audience abstraction. |
|
|
| `apps/web/app/utils/db/users.db.server.ts` | Imports `CrmService` and `ContactStatus`; user creation/update paths can create CRM contacts and log CRM sync. | Move CRM sync to plugin event subscriber or guard behind optional plugin availability. |
|
|
| `apps/web/public/locales/en/translations.json` | Contains `crm.title` and `crm.settings.*` strings. | Move/remove CRM translations with plugin UI. |
|
|
| `apps/web/public/locales/de/translations.json` | Contains `crm.title` and `crm.settings.*` strings. | Move/remove CRM translations with plugin UI. |
|
|
| `docs/feature-manifests/plugin-candidates.json` | Lists CRM as plugin candidate with code areas `apps/web/app/modules/crm`, `apps/web/app/routes/admin/crm*`, and `apps/web/app/routes/app.$tenant/crm*`; pruning action is `extract-plugin`. | Keep consistent with this decision report and later split into a CRM-specific plugin manifest if extraction begins. |
|
|
|
|
Additional evidence from current inventory:
|
|
|
|
- `docs/feature-inventory.md` classifies CRM as Optional/Plugin because it is a strong product opinion coupled to default entities and Email Marketing.
|
|
- The filesystem still retains `apps/web/app/routes/admin/crm`, `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/app.$tenant/crm`, and `apps/web/app/routes/app.$tenant/crm.tsx`, while default core route discovery excludes those plugin trees.
|
|
- `apps/web/app/modules/crm/services/CrmService.ts` depends on Rows/Entities APIs, row relationships, row values, notifications, cache helpers, and default entity names.
|
|
|
|
## Couplings
|
|
|
|
### Rows and default entities
|
|
|
|
CRM is coupled to the generic rows/entities runtime through entity names and slugs rather than isolated CRM tables. `CrmService.validate()` requires `company`, `opportunity`, and `contact`, plus `submission` for admin/global CRM. The service uses rows APIs and row relationship APIs for contact, company, opportunity, and submission behavior. A future extraction must preserve rows/entities as core infrastructure while ensuring CRM entity templates are optional plugin seed data.
|
|
|
|
### Email Marketing
|
|
|
|
`apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` directly imports `CrmService` and `ContactDto`. It uses CRM contacts as campaign recipients, blocks sends to contacts without `marketingSubscriber`, replaces email variables from contact fields, and loads contacts from contact entity views. This is the most important downstream dependency: CRM cannot be removed from core unless Email Marketing is either extracted together with CRM, made dependent on the CRM plugin, or refactored to a separate audience/contact-list abstraction.
|
|
|
|
### User lifecycle sync
|
|
|
|
`apps/web/app/utils/db/users.db.server.ts` imports `CrmService` and `ContactStatus` and can create CRM contact rows for users. The future extraction must move this behavior into plugin-owned lifecycle hooks or guard it so core user persistence no longer imports CRM.
|
|
|
|
### Route and entity routing helpers
|
|
|
|
`apps/web/app/utils/api/.server/EntitiesApi.ts` contains route-generation branches for admin CRM and tenant CRM paths. These branches make CRM route paths part of shared entity routing. A future extraction must either remove those branches or replace them with plugin-provided route builders.
|
|
|
|
### Navigation and commands
|
|
|
|
`apps/web/app/services/command-registry/commandRegistry.ts` is the current command-registration surface. CRM command entries are not registered in the generic registry; the admin/app CRM layout routes still build CRM-specific local navigation with CRM icons. A future extraction must keep command registration plugin-owned and remove route/sidebar visibility unless the CRM plugin is installed.
|
|
|
|
### Translations and icons
|
|
|
|
CRM strings live in shared locale files under `crm.*`. CRM route layouts import CRM-specific icon components from `~/components/ui/icons/crm/*`. A future extraction must move translations and icon usage with the plugin or delete them when CRM is removed.
|
|
|
|
### Manifest and documentation
|
|
|
|
`docs/feature-manifests/plugin-candidates.json` already classifies CRM as a plugin candidate. This report becomes the human-readable canonical decision; T02 should verify that report references remain resolvable and consistent with the manifest.
|
|
|
|
## Schema and Template Impact
|
|
|
|
CRM does not appear as a dedicated Prisma model surface in the reviewed task inputs. Its data model is represented through the rows/entities runtime and `CRM_ENTITIES_TEMPLATE` in `apps/web/app/modules/templates/defaultEntityTemplates.ts`:
|
|
|
|
- `company` with slug `companies`, type `AdminOnly`, properties such as `name`, `address`, `phone`, `source`, and `logo`.
|
|
- `opportunity` with slug `opportunities`, type `AdminOnly`, properties such as `name`, `value`, and `expectedCloseDate`.
|
|
- `contact` with slug `contacts`, type `AdminOnly`, properties such as `firstName`, `lastName`, `email`, `jobTitle`, `status`, and `marketingSubscriber`.
|
|
- `submission` with slug `submissions`, type `AdminOnly`, properties such as `users` and `message`.
|
|
- Relationships: `company` to `contact`, `company` to `opportunity`, and `contact` to `submission`.
|
|
|
|
Future extraction decision for templates must be explicit and atomic:
|
|
|
|
1. If CRM becomes an installable plugin, move `CRM_ENTITIES_TEMPLATE` into plugin seed/install code and keep core template loading independent from CRM.
|
|
2. If CRM is removed for minimal boilerplate builds, remove default availability of company/contact/opportunity/submission templates and document migration/export for existing installations.
|
|
3. If Email Marketing still needs contacts, do not remove `contact`/`marketingSubscriber` until Email Marketing owns or imports an audience template.
|
|
|
|
## Sidebar Command Docs Impact
|
|
|
|
Sidebar and route navigation impact:
|
|
|
|
- Admin CRM route code is retained at `apps/web/app/routes/admin/crm.tsx` and nested `apps/web/app/routes/admin/crm/*` routes, but is disabled in default core route registration.
|
|
- Tenant CRM route code is retained at `apps/web/app/routes/app.$tenant/crm.tsx` and nested `apps/web/app/routes/app.$tenant/crm/*` routes, but is disabled in default core route registration.
|
|
- CRM layout routes build their own icon subnavigation for Overview, opportunities, companies, contacts, submissions, and, in admin, Sync.
|
|
- Any global AdminSidebar/AppSidebar references discovered in a future implementation slice must be removed or made plugin-aware. Current sidebar tests already assert some optional admin routes, including canonical admin-host CRM paths, are not present in the admin sidebar serialization.
|
|
|
|
Command impact:
|
|
|
|
- `apps/web/app/services/command-registry/commandRegistry.ts` is the command registry surface and should remain free of CRM commands unless a CRM plugin contributes them.
|
|
- Future extraction must remove this core command or move it to plugin command registration.
|
|
|
|
Docs and i18n impact:
|
|
|
|
- `apps/web/public/locales/en/translations.json` and `apps/web/public/locales/de/translations.json` contain CRM translations and should move with plugin UI.
|
|
- `docs/feature-manifests/plugin-candidates.json` must remain aligned with this report; if CRM receives a dedicated plugin manifest later, `plugin-candidates.json` should point to it or retain a consistent summary entry.
|
|
|
|
## Execution Plan
|
|
|
|
The future CRM extraction/removal work must run in this sequence, with each step atomic and independently verifiable:
|
|
|
|
1. Decision/report: land this `extract-plugin` decision report and the T02 verifier before runtime changes.
|
|
2. Email Marketing dependency check: inspect `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts`, Email Marketing routes, campaign recipient storage, and tests to choose one of three paths: extract Email Marketing together with CRM, declare Email Marketing dependent on CRM plugin, or introduce a non-CRM audience abstraction.
|
|
3. Route/module extraction or deletion: move or remove `apps/web/app/modules/crm`, `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/admin/crm/*`, `apps/web/app/routes/app.$tenant/crm.tsx`, and `apps/web/app/routes/app.$tenant/crm/*` in one implementation slice after dependencies are guarded.
|
|
4. Default entity template decision: move `CRM_ENTITIES_TEMPLATE` from `apps/web/app/modules/templates/defaultEntityTemplates.ts` into plugin install/seed code, or remove it from default loading only after Email Marketing/user sync no longer requires it.
|
|
5. Command/sidebar/i18n update: remove or plugin-register CRM command palette entries, CRM route/sidebar links, CRM route helpers in `apps/web/app/utils/api/.server/EntitiesApi.ts`, CRM locale keys in `apps/web/public/locales/en/translations.json` and `apps/web/public/locales/de/translations.json`, and CRM docs/manifest entries.
|
|
6. Tests/static scans: add or update static scans and focused tests so core no longer imports `~/modules/crm`, CRM routes are absent when the plugin is disabled, Email Marketing behavior is explicit, and docs/manifests stay consistent.
|
|
|
|
## Verification Plan
|
|
|
|
T02 must add a local static verifier, expected at `scripts/verify-crm-decision-report.mjs`, that fails when this decision contract drifts. The verifier must check:
|
|
|
|
- Required report sections exist: Decision, Scope, Current Code Surfaces, Couplings, Schema and Template Impact, Sidebar Command Docs Impact, Execution Plan, Verification Plan, Risks.
|
|
- The report contains the exact decision token `extract-plugin`.
|
|
- No TODO, TBD, or unresolved placeholder text exists in the report.
|
|
- Required referenced paths are present in the report and resolvable where they are concrete current paths: `apps/web/app/modules/crm`, `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/admin/crm/*`, `apps/web/app/routes/app.$tenant/crm.tsx`, `apps/web/app/routes/app.$tenant/crm/*`, `apps/web/app/modules/templates/defaultEntityTemplates.ts`, `apps/web/app/utils/api/.server/EntitiesApi.ts`, `apps/web/app/services/command-registry/commandRegistry.ts`, `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts`, `apps/web/app/utils/db/users.db.server.ts`, `apps/web/public/locales/en/translations.json`, `apps/web/public/locales/de/translations.json`, `docs/feature-manifests/plugin-candidates.json`.
|
|
- Glob-style references such as `apps/web/app/routes/admin/crm/*` and `apps/web/app/routes/app.$tenant/crm/*` resolve to existing route directories or files.
|
|
- `docs/feature-manifests/plugin-candidates.json` still contains a CRM component and `pruning.action` remains `extract-plugin` unless a later migration intentionally updates both manifest and report.
|
|
|
|
Manual verification for a future runtime extraction should cover:
|
|
|
|
- Core app and admin shells start without CRM installed.
|
|
- Email Marketing either works with its declared CRM dependency or fails with a clear disabled-plugin message.
|
|
- User creation/update no longer imports or calls CRM from core when CRM is disabled.
|
|
- Existing CRM installations have a documented export/migration path if runtime deletion is chosen instead of plugin packaging.
|
|
|
|
## Risks
|
|
|
|
- Incomplete surface map can cause later removal to miss imports; this report therefore names all known coupling files from the slice research and the task inputs.
|
|
- Email Marketing has direct CRM service and contact DTO coupling, so removing CRM first would break campaign preview/send flows.
|
|
- User lifecycle CRM sync creates hidden coupling outside CRM routes and must be moved or guarded before extraction.
|
|
- CRM entities are generic rows/entities templates, so deleting only route/module code can leave orphaned templates or data.
|
|
- Translation, command, and route-helper leftovers can keep CRM visible or navigable after the module is removed.
|
|
- Existing tenants may rely on CRM rows and relationships; plugin extraction should include compatibility and migration notes rather than silent data loss.
|
|
|
|
## Update (R-P6 typed CRM)
|
|
|
|
This boilerplate report classified CRM as an optional `extract-plugin` vertical and asked to preserve the entity-builder CRM surfaces until a dedicated implementation slice. HiveGrid ticket R-P6 (2026-06-29) is that slice and takes a different product direction (AD-2 "Entity-Builder raus", AD-20 project-centric pivot — pivot precedence per AGENTS.md): CRM is a typed first-class core, not a plugin candidate.
|
|
|
|
What R-P6 changed relative to this report:
|
|
|
|
- The entity-builder CRM route trees were deleted: `apps/web/app/routes/admin/crm.tsx`, `apps/web/app/routes/admin/crm/*`, `apps/web/app/routes/app.$tenant/crm.tsx`, `apps/web/app/routes/app.$tenant/crm/*`. The typed CRM now lives under `apps/web/app/routes/app.$tenant/contacts.*` with services in `apps/web/app/utils/integrations/crm/*` and view-models in `packages/view-models/src/crm/*`, backed by `prisma/schema/crm.prisma`.
|
|
- `apps/web/app/modules/crm` is retained as a LEGACY surface: only the entity-builder contact-row readers (`getContact`, `getContactsInRowIds`, `ContactDto`) still consumed by Email Marketing (AK-P14) remain. Full removal is deferred to the Email Marketing typed-Kontakt migration (follow-up ticket) — exactly the coupling this report flagged as a human-review note.
|
|
- The decision token remains `extract-plugin` for the residual legacy surface; the strategic target for the typed CRM core is "retain as core", not extraction. The route-existence checks in `scripts/verify-crm-decision-report.mjs` were updated accordingly.
|
|
|
|
## Update (R-P14C)
|
|
|
|
HiveGrid ticket R-P14C (2026-06-30) executes the Email Marketing typed-Kontakt
|
|
migration the R-P6 section above flagged as a follow-up. Under **Variante A** the
|
|
legacy Entity-Builder campaign editor is removed rather than migrated:
|
|
|
|
- `apps/web/app/modules/emailMarketing/services/EmailMarketingService.ts` (the
|
|
`CrmService.getContact`/`getContactsInRowIds`/`ContactDto` consumer this report
|
|
tracked) was deleted; its only typed survivor (the overview summary) now reads
|
|
the typed `OutboundEmail` counters directly. The file-existence assertion for
|
|
it was dropped from `scripts/verify-crm-decision-report.mjs`; the historical
|
|
coupling reference is retained above.
|
|
- The residual `apps/web/app/modules/crm` legacy reader is removed in the same
|
|
ticket once the last consumer is gone (see the Email Marketing decision report
|
|
update for the full removal record).
|