Modules

Overview~5 min

Self-contained feature units that keep domain logic isolated, organized, and removable.

Read this when you're adding a new feature, removing an existing one, or understanding how domain code is organized.
Useful for developers working on feature-specific functionality.

What Are Modules?

Modules are self-contained feature packages. Each module owns its components, hooks, services, types, and even database migrations. This isolation means you can add, modify, or remove a feature without touching unrelated code.

Unlike surfaces (which separate UI by audience) or platform (which provides shared capabilities), modules encapsulate domain logic — the specific features that make your application unique.

Why This Matters

Modules solve common problems in growing codebases:

Clear boundaries

No accidental coupling. Modules can't import from other modules, preventing the tangled dependencies that slow teams down.

Everything in one place

Co-located code. Components, hooks, services, and migrations live together. Find what you need without hunting across folders.

Clean removal

Delete the folder, run cleanup SQL. Modules include their own removal scripts. No orphaned code, no broken imports.

Available Modules

Catalyst includes these production-ready modules:

Activity

Activity feeds and notifications. Track user actions, broadcast updates via Supabase realtime.

ActivityFeed componentNotificationBellRealtime broadcastsActivity types

AI

AI provider management and chatbot. Multi-provider support with Vercel AI SDK.

Multi-providerAuto-detectionStreaming chatConnection testing

CRM

Contact and deal management. Full CRUD with notes, status tracking, and activity integration.

Contact managementDeal pipelineNotes and timelineStatus workflows

Diagrams

Canvas-based diagram editor. Create flow diagrams with nodes, connections, and AI-assisted generation.

Canvas editorMultiple node typesImport/exportAI prompts

Feedback

User feedback collection and management. Drawer widget, element selection, admin triage.

Feedback drawerCategoriesStatus trackingAttachments

Projects

Project tracking with tasks and milestones. Integrated with Activity for notes and audit trails.

ProjectsTasksDue datesActivity integration

Module Structure

modules/
├── MODULES.md              # Architecture docs
└── <module>/
    ├── MODULE-<NAME>.md    # Module-specific docs (e.g., MODULE-CRM.md)
    ├── index.ts            # Public API
    ├── components/         # UI components
    ├── hooks/              # React hooks
    ├── services/           # Business logic
    ├── server/             # Server-only code
    ├── types/              # TypeScript types
    ├── constants.ts        # Module constants
    └── supabase/
        ├── migrations/     # Database migrations
        ├── seeders/        # Test data
        └── cleanup.sql     # Removal script

Import Rules

Allowed

  • modules/* → components/*
  • modules/* → lib/*
  • modules/* → same module
  • app/* → modules/* (via public API)

Forbidden

  • modules/* → other modules/*
  • Client components → server/*
  • External → module internals

Always import from the module's index.ts, never reach into internal files directly.

Modules are meant to be removed. The isolation isn't just for organization — it's so you can delete a feature cleanly when requirements change. Each module includes a cleanup.sql script that removes its database objects.

Adding & Removing Modules

Adding a Module

  1. Create modules/your-module/
  2. Add MODULE-NAME.md with documentation
  3. Create index.ts with public exports
  4. Add components, hooks, services
  5. Create migrations if using database

Removing a Module

  1. Run supabase/cleanup.sql
  2. Delete the module directory
  3. Remove any app routes that import it
  4. Update navigation if needed

Next Steps

Explore the available modules:

Activity

Feeds, notifications, and realtime updates.

AI

Multi-provider AI chat and management.

CRM

Contacts, deals, and relationship tracking.

Diagrams

Canvas editor for flow diagrams.

Feedback

User feedback collection and triage.

Projects

Project tracking with tasks.