Project Structure

This is a high-level map of the katalyst-vite codebase.

Visual overview

src/
├── main.tsx                    # App entrypoint
├── App.tsx                     # Root component
│
├── app/                        # App shell
│   ├── config/                 # App-level configuration
│   ├── providers/              # React context providers
│   └── router/                 # Routing setup
│
├── core/                       # Core infrastructure
│   ├── di/                     # Dependency injection container
│   └── router/                 # Route utilities
│
├── modules/                    # Feature modules
│   ├── apps/                   # App features (email, kanban, invoicing...)
│   ├── dashboards/             # Dashboard modules
│   ├── management/             # Users, teams, notifications
│   ├── settings/               # Settings module
│   ├── auth/                   # Authentication
│   └── showcase/               # Reference implementations
│
└── shared/                     # Shared code
    ├── hooks/                  # Behavior primitives (useBulkSelection, etc.)
    ├── ui/
    │   ├── shadcn/         # shadcn-style UI (Button, Dialog, etc.)
    │   ├── components/         # Thin shared components
    │   └── layouts/            # Layout components
    └── infrastructure/         # Cross-cutting services
        ├── config/             # Environment config
        ├── http/               # HTTP client
        ├── storage/            # Storage service
        └── events/             # Event bus

How the layers relate

┌─────────────────────────────────────────────────────────────┐
│                      Feature Modules                        │
│   (src/modules/apps/, dashboards/, management/, etc.)       │
│                                                             │
│   • Own domain-specific pages and flows                     │
│   • Consume shared primitives and components                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Shared Components                        │
│              (src/shared/ui/components/)                    │
│                                                             │
│   • Thin wrappers around primitives + hooks                 │
│   • ConfirmDialog, InlineEditable, CommandPalette           │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│          Shared Primitives          │    UI Primitives      │
│         (src/shared/hooks/)         │ (src/shared/ui/shadcn)│
│                                     │                       │
│   • useBulkSelection                │                       │
│   • useInlineEdit                   │   • Button, Dialog    │
│   • useConfirmation                 │   • Checkbox, Input   │
│   • useKeyboardShortcut             │   • Table, Tabs       │
│   • useCommandPalette               │   • (shadcn-style)    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Shared Infrastructure                     │
│              (src/shared/infrastructure/)                   │
│                                                             │
│   • Config, HTTP client, storage, events                    │
│   • Cross-cutting concerns used by all layers               │
└─────────────────────────────────────────────────────────────┘

Top-level

• src/main.tsx — App entrypoint. MSW mocking is enabled when VITE_USE_MSW === 'true'.
• src/App.tsx — Root app component.

App shell

• src/app/ — App-level config, providers, and routing.
  • providers/ — React context providers (DI, Theme, i18n, React Query, Tour)
  • router/ — Route definitions and protected route wrapper
  • config/ — App-level configuration

Core

• src/core/ — Core infrastructure that bootstraps the app.
  • di/ — Inversify container setup and module loader
  • router/ — Route utilities

Feature modules

• src/modules/ — Feature modules grouped by domain area.
  • apps/ — Application features (email, kanban, calendar, chat, invoicing)
  • dashboards/ — Dashboard modules (executive, sales, projects, ecommerce)
  • management/ — User and team management, notifications
  • settings/ — User and app settings
  • auth/ — Authentication flows

Each feature module typically follows a consistent internal structure:

modules/<feature>/
├── application/        # React Query hooks, use cases
├── di/                 # Module-specific DI bindings
├── domain/             # TypeScript interfaces, models
├── infrastructure/     # Repositories, API handlers, mocks
└── ui/                 # Pages, components, routes

Showcase

• src/modules/showcase/ — Demonstrates how to use shared primitives and components in realistic screens. The Patterns docs are based on these examples.

Shared primitives (hooks)

• src/shared/hooks/ — Shared behavior primitives (the "logic" layer). These are documented under Primitives.

Shared UI

• src/shared/ui/shadcn/ — shadcn-style UI primitives built on Radix/cmdk and Tailwind.
• src/shared/ui/components/ — Thin shared components composed from primitives + hooks (e.g. ConfirmDialog, CommandPalette, InlineEditable).
• src/shared/ui/layouts/ — Layout components (vertical layout, topbar, sidebar).

Shared infrastructure

• src/shared/infrastructure/ — Cross-cutting services:
  • config/ — Environment configuration and validation
  • http/ — HTTP client with auth and error handling
  • storage/ — Local storage service
  • events/ — Event bus for cross-module communication
  • repositories/ — Base repository patterns

Suggested reading

• Start with Primitives for the core hooks.
• Use Patterns for end-to-end interaction workflows.