Project Structure

Understanding how Dashforge projects are organized and the role of each package in the ecosystem.

Package Architecture

Dashforge follows a modular architecture

@dashforge/
├── forms/              # Form management system
│   ├── DashForm        # Main form component
│   └── Provider        # Form context provider
│
├── ui/                 # UI component library
│   ├── TextField       # Intelligent text input
│   ├── Select          # Intelligent select dropdown
│   ├── NumberField     # Intelligent number input
│   └── ...             # More components
│
├── theme-core/         # Core theming system
│   ├── Provider        # Theme context
│   └── Utilities       # Theme helpers
│
├── theme-mui/          # Material-UI integration
│   └── Adapter         # MUI theme adapter
│
└── ui-core/            # Internal package
    ├── Engine          # Predictive form engine
    ├── Bridge          # Form integration contract
    └── Types           # Shared type definitions

Layer Separation

Clear boundaries between layers

Application Layer

Your app code

Business logic, routing, API calls, state management

UI Layer

@dashforge/ui

Form-aware components with automatic integration

Form Layer

@dashforge/forms

Form state management, validation, submission

Theme Layer

@dashforge/theme-core, @dashforge/theme-mui

Styling, theming, design tokens

Core Layer

@dashforge/ui-core

Predictive engine, bridge contracts, shared types

Typical Project Structure

Example application organization

my-dashforge-app/
├── src/
│   ├── App.tsx                 # Root component with providers
│   ├── main.tsx                # Application entry point
│   │
│   ├── components/             # Shared components
│   │   ├── Layout/
│   │   └── ...
│   │
│   ├── features/               # Feature modules
│   │   ├── auth/
│   │   │   ├── LoginForm.tsx
│   │   │   └── RegisterForm.tsx
│   │   ├── profile/
│   │   │   └── ProfileForm.tsx
│   │   └── settings/
│   │       └── SettingsForm.tsx
│   │
│   ├── hooks/                  # Custom hooks
│   │   ├── useAuth.ts
│   │   └── useApi.ts
│   │
│   ├── services/               # API services
│   │   ├── api.ts
│   │   └── auth.ts
│   │
│   └── types/                  # TypeScript types
│       └── index.ts
│
├── package.json
└── tsconfig.json

Import Patterns

Recommended import organization

Organize imports by layer for clarity:

// 1. React imports
import { useState, useEffect } from 'react';

// 2. Third-party libraries
import { useNavigate } from 'react-router-dom';

// 3. Dashforge imports (organized by package)
import { DashForm } from '@dashforge/forms';
import { TextField, Select } from '@dashforge/ui';
import { useDashTheme } from '@dashforge/theme-core';

// 4. MUI imports (when needed)
import Button from '@mui/material/Button';
import Stack from '@mui/material/Stack';

// 5. Local imports
import { useAuth } from '../../hooks/useAuth';
import { api } from '../../services/api';
import type { User } from '../../types';

File Organization

Best practices for organizing form components

Feature-Based Organization

Group related forms and components by feature:

features/
├── profile/
│   ├── ProfileForm.tsx         # Main form component
│   ├── ProfileForm.types.ts    # Form-specific types
│   ├── ProfileForm.schema.ts   # Validation schema
│   └── ProfileForm.test.tsx    # Tests
│
└── settings/
    ├── SettingsForm.tsx
    ├── AccountSettings.tsx      # Sub-form
    ├── PrivacySettings.tsx      # Sub-form
    └── NotificationSettings.tsx # Sub-form

Shared Form Utilities

Create reusable validation rules and form helpers:

utils/
├── validation/
│   ├── email.ts        # Email validation rules
│   ├── password.ts     # Password validation rules
│   └── phone.ts        # Phone validation rules
│
└── forms/
    ├── submitHandlers.ts   # Reusable submission logic
    └── transforms.ts       # Data transformation utilities

Best Practices

Recommendations for maintainable Dashforge projects

Keep Forms Focused

Each form component should have a single responsibility. Break complex forms into smaller, composable sections.

Colocate Form Logic

Keep form-specific validation, types, and utilities close to the form component that uses them.

Extract Reusable Validation

Common validation rules (email, phone, password) should be extracted into shared utilities.

Use TypeScript

Define explicit types for form values. This provides autocomplete and catches errors at compile time.

Separate Concerns

Keep business logic, API calls, and form UI separate. Forms should focus on user input, not data fetching.