Skip to main content

Convex Module Map

This is the locked V1 Convex module map for IED.

Use this as the source of truth for:

  • required first-wave Convex modules
  • which domain entities each module owns
  • what each module is allowed to persist or mutate
  • which modules are later or optional

First-Wave Required Modules​

leads​

Primary intake and customer-record module.

Owns:

  • lead record creation
  • lead lifecycle state
  • customer identity and contact details
  • lead source and contact preferences
  • selected path
  • persisted assessment snapshot
  • persisted recommendation snapshot

V1 rule:

  • assessment and recommendation persistence stay lead-owned in the first wave

installers​

Installer ownership module.

Owns:

  • installer company records
  • contacts
  • services offered
  • operational status
  • quality/internal notes
  • installer-to-region relationships

Does not own:

  • routing assignments
  • region ownership

regions​

Region and serviceability ownership module.

Owns:

  • region records
  • postcode ownership mappings
  • region active/inactive behavior
  • region-level installer relationships

Does not own:

  • installer company status
  • lead lifecycle

routing​

Lead assignment and routing workflow module.

Owns:

  • lead-to-installer assignment records
  • routing decisions
  • routing-specific timestamps and notes
  • compare-quotes versus recommended-installer assignment behavior

Does not own:

  • lead lifecycle
  • installer company records
  • follow-up records

followUps​

Post-install trust and quality module.

Owns:

  • follow-up records
  • follow-up workflow state
  • satisfaction outcomes
  • issue-tracking fields

V1 rule:

  • follow-up records remain secondary and should not block the core lead delivery workflow

system​

Transitional operational module only.

Owns:

  • current system snapshots and baseline operational scaffolding

V1 rule:

  • system is transitional and should not shape the long-term domain model

Later Or Optional Modules​

recommendations​

Not required as a standalone first-wave module.

It may be extracted later if recommendation generation, versioning, or auditing becomes independently complex.

analytics​

Later derived/reporting module.

It should read from source-of-truth operational modules rather than owning primary business state.

activityLog​

Not its own V1 module.

Timeline and activity history should be produced by the owning modules in the first wave.

content​

Not part of the admin Convex first wave unless content editing becomes operationally necessary.

Entity Ownership Map​

Recommended V1 ownership:

  • Lead owned by leads
  • Assessment owned by leads
  • Recommendation owned by leads
  • Installer owned by installers
  • Region owned by regions
  • LeadAssignment owned by routing
  • FollowUp owned by followUps

Table Direction​

V1 should prefer a small number of obvious tables and modules over premature normalization.

Recommended table direction:

  • leads lead record plus lead-owned assessment and recommendation data
  • installers installer records and installer operational metadata
  • regions region records and postcode ownership mappings
  • routing lead-assignment records
  • followUps follow-up records
  • system transitional system snapshot records only

Ownership Rules​

Lock these V1 boundaries:

  • assessment answers persist with the leads boundary
  • recommendation outputs persist with the leads boundary
  • assignment progress persists in routing
  • satisfaction and issue outcomes persist in followUps
  • activity and timeline entries stay with the owning module for now

Do not create these standalone first-wave modules:

  • assessments
  • recommendations
  • activityLog
  • analytics

unless a real implementation need appears later.

Validation Scenarios​

The module map should support these scenarios:

  • a public submission can persist lead, assessment, and recommendation data without forcing three separate first-wave modules
  • admin lead detail can load customer info, assessment answers, recommendation output, assignment state, and follow-up status through clear module boundaries
  • routing can evolve independently without taking ownership of lead lifecycle or installer company state
  • region postcode checks can evolve independently without taking ownership of installer records
  • follow-up records start only after install confirmation and are not mixed into routing state
  • analytics can be added later from existing source-of-truth modules without restructuring the whole backend
  • the current system.ts can coexist temporarily without distorting the final domain map