Chapter 4.4: Domain Builder — Visual Configuration Without Code

"The best domain builder is the one that prevents you from making mistakes you didn't know were possible."

The Problem This Solves

Let's be honest: editing domain-config.json by hand is error-prone work. A missing comma breaks the entire file. A typo in a table name creates a silent failure. A malformed regex pattern in a validation rule causes runtime errors that are nearly impossible to debug. And adding advanced features like table groups (Chapter 4.5), form generation metadata (Chapter 4.6), OAuth configuration (Chapter 4.7), template filters (Chapter 4.8), and AI recommendations (Chapter 4.9) requires you to read documentation, remember exact JSON schemas, and hope you got the nesting right.

You are a domain expert, not a JSON schema validator.

The Domain Builder is Data Publisher's answer to this problem. It is a visual, step-by-step wizard that guides you through every aspect of domain creation — from basic metadata to advanced AI configuration — without requiring you to touch a single line of JSON. It validates your input in real-time, prevents common errors before they happen, generates perfectly-formed configuration files, and packages everything into a deployment-ready ZIP file.

The statistics tell the story:

But the bigger win is not speed — it is correctness. The Domain Builder eliminates syntax errors, enforces schema compliance, and ensures that every relationship you define actually references tables and columns that exist.

Accessing the Domain Builder

Go to the Data tab, choose Data Sets and clone an existing domain. It can be one that comes by default in Data Publisher or one you uploaded. You will see an "Edit in Builder" button in the Data Set card. That's where you can change and save as a new domain. That's a pretty good shortcut.

Upon loading, you see the 8-step wizard interface:

┌─────────────────────────────────────────────────────────┐
│  Domain Builder                                         │
├─────────────────────────────────────────────────────────┤
│  ⊙ 1. Basic Info                                        │
│  ○ 2. Data Tables                                       │
│  ○ 3. Table Groups                                      │
│  ○ 4. Relationships                                     │
│  ○ 5. Templates                                         │
│  ○ 6. External Data                                     │
│  ○ 7. AI Configuration                                  │
│  ○ 8. Review & Export                                   │
└─────────────────────────────────────────────────────────┘

Each step must be completed before you can advance. The wizard saves your progress automatically so you can close the browser and return later without losing work.

Step 1: Basic Domain Information

The first step collects the foundational metadata that every domain requires.

Domain ID

This is the machine-readable identifier that appears in URLs, API endpoints, and folder structures. Once set, it should never change.

Requirements: - Lowercase letters only - Hyphens to separate words (not underscores) - No spaces, no special characters - 3-30 characters

Valid examples: legal-services, school-coop, real-estate-showings

Invalid examples: Legal_Services, SchoolCoop, legal services, legal-srv-v2

The Domain Builder validates this in real-time. If you type an uppercase letter, it converts it to lowercase automatically. If you type a space, it replaces it with a hyphen. If you try to include a character that is not allowed, it rejects the keystroke.

Domain Name

This is the human-readable name that appears in the marketplace, in the domain selection dropdown, and in the user interface.

Example: "Legal Services Manager" for domain ID legal-services

No character restrictions here. Use proper capitalization, spaces, and punctuation as appropriate.

Description

Write 2-3 sentences that explain what this domain does and who it is for. This appears in the marketplace listing and helps potential users understand whether your domain meets their needs.

Good example:

"Manage client matters, track deadlines, generate invoices, and produce court documents for solo attorneys and small law firms. Includes templates for demand letters, discovery requests, motions, and client communications."

Bad example:

"This domain has legal templates."

Icon

Click the icon field to open the comprehensive Icon Picker, which organizes over 100 emojis into categories:

• 👥 People
• 💰 Finance
• 🎓 Education
• ⚖️ Legal
• 🏥 Medical
• 🏢 Real Estate
• 💼 Business
• 📧 Communication
• 📄 Documents
• 📅 Calendar
• ⭐ Symbols

Use the search box to find icons by keyword, or browse by category. The picker remembers your recently-used icons for quick access.

Choose an icon that visually represents your domain's purpose. Users see this icon in the domain selection menu, so make it distinctive and relevant.

Category

Select from: - Business & Operations - Education - Healthcare - Legal & Compliance - Real Estate - Financial Services - Non-Profit - Personal & Family - Other

This determines how your domain appears in marketplace filters and search results.

Version

Default is 1.0.0. Use semantic versioning: MAJOR.MINOR.PATCH

• Increment MAJOR when you make breaking changes (remove tables, change schema)
• Increment MINOR when you add features in a backward-compatible manner
• Increment PATCH for bug fixes and minor improvements

Tags

Comma-separated keywords that improve discoverability in marketplace search.

Example for legal domain: legal, law firm, attorney, client management, billing, court documents

Step 2: Data Tables

This is where you upload your CSV sample data files (see Chapter 4 for guidance on creating high-quality sample data).

Uploading CSV Files

Click "Upload CSV Files" and select one or more CSV files from your computer. The Domain Builder:

1. Parses each CSV file
2. Extracts column headers
3. Detects column data types automatically
4. Counts rows
5. Displays a summary card for each table

The type detection is smart but not perfect. It examines sample values and guesses:

• Text: Default for most columns
• Number: All values are numeric
• Date: Values match YYYY-MM-DD pattern
• Currency: Values start with $ and are numeric
• Email: Values contain @ symbol
• URL: Values start with http:// or https://
• Boolean: Values are only "true"/"false"

Viewing and Editing Columns

Click "View Columns" on any table card to expand the column list. Each column displays:

• Icon indicating detected type
• Column name
• Dropdown to change type
• Sample values from the CSV
• "⚙️ Edit Field" button

The Enhanced Field Editor

This is where the Domain Builder shines. Click "⚙️ Edit Field" on any column to open the tabbed Field Editor modal.

Tab 1: Basic Properties

• Field Name: The column name from your CSV
• Display Label: User-friendly label shown in forms (defaults to field name)
• Field Type: Select from the full type list:
• Text, Number, Date, Currency, Email, URL, Boolean
• Lookup: Foreign key to another table
• Select: Dropdown with predefined options
• Description: Help text explaining what this field contains

Tab 2: Form Generation

These settings control how the field appears in the Data Sets form:

• ☑️ Show in filter forms (filterable): Users can filter records by this field
• ☑️ Required field: Field must have a value
• ☑️ Default to first option: For lookups/selects, automatically select the first choice

These map directly to the form generation metadata described in Chapter 4.6. But instead of editing JSON by hand, you check boxes.

Tab 3: Validation

The Domain Builder provides validation templates for common patterns:

Click any template to apply it instantly:

Or check "Custom regex pattern" and write your own. The validated pattern is stored in the field's validation.pattern property, exactly as Chapter 4.6 describes — but you never had to look up the JSON structure.

You can also set: - Minimum Length: Reject values shorter than X characters - Maximum Length: Reject values longer than X characters

Tab 4: Lookup Configuration

If you set Field Type to "Lookup", this tab activates. Configure the foreign key relationship:

• References Table: Which table does this field point to?
• Display Field: Which column from that table should users see? (e.g., "FullName")
• Value Field: Which column holds the actual ID? (e.g., "ClientID")

Example: A ClientID field in the matters table might reference the clients table, display the ClientName column, and store the ClientID value.

The Domain Builder validates that the referenced table exists and that the display/value fields are real columns in that table. No more broken foreign keys from typos.

Why This Matters

Without the Field Editor, configuring validation for a single field requires:

{
  "name": "Email",
  "type": "email",
  "required": true,
  "filterable": true,
  "displayLabel": "Client Email",
  "validation": {
    "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
  }
}

One typo in that regex breaks the entire configuration. One missing comma makes the JSON invalid. One wrong property name causes a silent failure.

With the Field Editor, you click "Email Address" and check two boxes. Done. Correct. Validated.

Step 3: Table Groups

This step implements Chapter 4.5's progressive disclosure pattern — organizing your tables into logical categories so users are not overwhelmed by a flat list of 15+ tables.

Creating a Table Group

Click "Create Table Group". A modal opens:

1. Group Name: What should this category be called?
   Example: "People", "Financial", "Academic"

2. Icon: Click "Choose Icon..." to open the Icon Picker
   The same categorized, searchable picker from Step 1

3. Description: One sentence explaining what tables belong in this group
   Example: "Families, students, teachers, and parents"

4. Select Tables: Check the tables that belong in this group
   A scrollable list with checkboxes for every table you uploaded

Click "Create Group" and the group appears immediately as a card showing: - The icon and name - The description - How many tables are in the group - A list of the table names - [Edit] and [Remove] buttons

The Ungrouped Tables Warning

If any tables remain ungrouped, a yellow warning banner appears:

⚠️ Ungrouped Tables: emergency_contacts, medical_info, field_trips

Consider adding these tables to a group for better organization.

This is informational only — ungrouped tables still work. But users will see them in a separate "Other Tables" section rather than grouped logically.

Why This Matters

Creating table groups manually requires editing domain-config.json to add:

"tableGroups": [
  {
    "id": "people",
    "name": "People",
    "icon": "👥",
    "description": "Families, students, teachers, and parents",
    "tables": ["families", "students", "teachers", "parents"]
  }
]

You must ensure: - The id is kebab-case derived from the name - The icon is a valid emoji - Every table name matches exactly (case-sensitive) - The JSON structure is correct

The Domain Builder handles all of this. You just name the group, pick an icon, and check some boxes. It generates the JSON perfectly.

And because 85% of users will define table groups with the visual interface (compared to only 20% who did it manually), your users get better-organized domains.

Step 4: Table Relationships

This step is familiar if you read Chapter 4 — it defines foreign key relationships between tables so the system knows how entities connect.

Adding a Relationship Manually

Click "Add Relationship" to open the relationship editor:

1. Parent Table: The table being referenced
   Example: clients
2. Parent Key: The primary key column
   Example: ClientID
3. Child Table: The table with the foreign key
   Example: matters
4. Child Key: The foreign key column
   Example: ClientID
5. Relationship Name: Auto-generated but editable
   Example: "clients → matters"

The dropdowns are populated from your tables and columns, so you cannot select something that does not exist.

Auto-Detecting Relationships

Or click "Auto-Detect Relationships" and let the Domain Builder find foreign keys for you.

It looks for columns matching common patterns: - ClientID, FamilyID, StudentID (ends with ID) - client_id, family_id (ends with _id) - Column name matches a table name (singular or plural)

Example: If you have a clients table with a ClientID primary key, and a matters table with a ClientID column, the auto-detector creates:

clients.ClientID → matters.ClientID (one-to-many)

Review the auto-detected relationships and delete any false positives. This feature typically finds 80-90% of relationships correctly, saving you 10+ minutes of manual configuration.

Viewing Relationships

Each relationship displays as a card:

┌─────────────────────────────────────────────────────┐
│ clients.ClientID → matters.ClientID                 │
│ one-to-many                            [Preview] [x] │
└─────────────────────────────────────────────────────┘

Click [Preview] to see a sample join of the related data, confirming that the relationship is correctly defined.

Step 5: Word Templates

Upload the .docx template files generated by your generator script (Chapter 5), or upload placeholder templates now and replace them later.

Uploading Templates

Click "Upload Templates" and select one or more .docx files. Each template appears as a card showing: - Template name - File size - Number of custom filters (if configured) - Number of sort options (if configured) - [⚙️ Configure] and [Remove] buttons

The Template Configuration Modal

This is where Chapter 4.8 (Template Filters) comes to life visually.

Click [⚙️ Configure] on any template to open the Template Filter Designer.

Adding Custom Filters

Click "✚ Add Filter" and fill in:

1. Field Name: Which field should users filter by?
   Example: CoopID
2. Display Label: What should the filter be called?
   Example: "Select Co-op"
3. Filter Type: Select / Multi-select / Text / Number / Date / Range
4. Required: Must users set this filter before generating?

The filter appears in the list:

┌──────────────────────────────────────────────────┐
│ Select Co-op                         [Remove]    │
│ Field: CoopID • Type: select • Required          │
└──────────────────────────────────────────────────┘

These filters generate the template-filters.json file described in Chapter 4.8. Without the Domain Builder, you would write:

{
  "1": {
    "filters": [
      {
        "field": "CoopID",
        "label": "Select Co-op",
        "type": "select",
        "required": true
      }
    ]
  }
}

The Domain Builder writes this for you, with template IDs assigned automatically and validated structure.

Adding Sort Options

Click "✚ Add Sort Option" and specify:

1. Field Name: Which field to sort by?
   Example: LastName
2. Display Label: How should this appear?
   Example: "Sort by Last Name (A-Z)"
3. Make Default?: Should this be the default sort?

Sort options appear in the list with a [DEFAULT] badge if applicable.

Why This Matters

Before the Domain Builder, template filters were used in only 15% of domains because they required: 1. Reading Chapter 4.8 to understand the JSON schema 2. Creating a separate template-filters.json file 3. Manually typing field names (typos cause silent failures) 4. Remembering to use the template ID as a string, not a number

With the visual interface, usage jumps to 75%+ of domains. Users configure filters in 2 minutes per template because the interface is obvious and validates everything.

Step 6: External Data Sources

This step enables Chapter 4.7's OAuth integration for live data sync.

Two checkboxes:

• ☑️ Enable Microsoft Excel / OneDrive
  Users can sync data from Excel Online or OneDrive files

• ☑️ Enable Google Sheets
  Users can sync data from Google Sheets

A blue info box explains:

💡 Tip: External data source configuration allows users to sync their own data instead of manually managing CSV files. This is optional — your domain will work with CSV files by default.

Check the boxes that apply and move on. The Domain Builder adds the OAuth configuration to your domain package automatically.

Without the Domain Builder, enabling OAuth requires: 1. Reading Chapter 4.7 2. Understanding OAuth flows and redirect URIs 3. Configuring multiple JSON files 4. Testing the integration

With the Domain Builder, you check a box. That's it.

Step 7: AI Configuration

This step implements Chapter 4.9's AI-powered template selection.

Enabling AI Recommendations

Check "☑️ Enable AI Template Recommendations" to activate the feature.

Domain Description

Write 2-3 sentences describing what users accomplish with this domain. The AI uses this as context when recommending templates.

Example:

"This domain helps homeschool co-ops manage student records, class enrollment, and family information. Users can generate rosters, reports, and communication letters."

Auto-Generating AI Tags

Click "⚡ Auto-Generate AI Tags from Templates".

The Domain Builder: 1. Looks at each template name 2. Extracts significant words (ignoring "the", "and", etc.) 3. Creates searchable tags 4. Generates sample use cases 5. Creates sample questions users might ask

Example: For template name Class_Roster.docx, it generates:

{
  "templateName": "Class Roster",
  "tags": ["class", "roster", "students"],
  "useCases": ["Generate class roster", "Create attendance sheets"],
  "sampleQuestions": [
    "I need a class roster",
    "How do I create an attendance sheet?"
  ]
}

Manual AI Configuration

Or click [Configure AI] on any template to set tags manually via a simple prompt. This is useful when the auto-generated tags are not quite right.

The AI configuration generates ai-knowledge-base.json (Chapter 4.9) without requiring you to understand the schema or manually write sample questions.

Why This Matters

Without the Domain Builder, creating AI configuration requires: 1. Running a Node.js script 2. Reviewing and editing the generated JSON 3. Understanding natural language processing concepts 4. Testing the recommendations

Only 5% of domains had AI configuration before the visual interface. With the Domain Builder, that jumps to 80%+ because it takes 5 minutes and requires zero technical knowledge.

Step 8: Review & Export

The final step validates your entire domain and prepares it for deployment.

Comprehensive Validation Report

The Domain Builder runs validation across all configuration:

✓ Info Messages (Green) - ✓ 8 tables configured - ✓ 12 fields have validation rules - ✓ 18 fields configured as filterable - ✓ 5 table groups defined - ✓ 12 relationships configured - ✓ 8 templates added - ✓ 3 templates have custom filters - ✓ AI recommendations enabled (8/8 templates configured)

⚠️ Warnings (Yellow) - ⚠️ 3 tables not assigned to groups: emergency_contacts, medical_info, field_trips - ⚠️ 2 templates have no custom filters configured

❌ Errors (Red) - ❌ Template "Invoice.docx" has a filter referencing field "Total" which does not exist in any table

Errors must be fixed before you can export. Warnings are advisory only — they suggest improvements but do not block export.

Domain Summary

The review step displays: - Domain name, ID, and category - Table count and total records - Relationship count - Template count - Enabled features (table groups, external data, AI)

JSON Preview

Click "Show JSON Preview" to see the generated domain-config.json file. This is read-only — you cannot edit it here — but it lets you verify that the Domain Builder generated exactly what you expect.

The JSON is syntax-highlighted and properly formatted with 2-space indentation, matching the examples throughout Volume 5.

Export Options

When validation passes, four buttons activate:

1. 📥 Download Complete Package (.zip)

Downloads a ZIP file containing: - domain-config.json (validated and complete) - template-filters.json (if any templates have filters) - ai-knowledge-base.json (if AI is enabled) - csv/ folder with all your CSV files - word-templates/ folder with all your templates - README.md (placeholder — you fill this in per Chapter 6)

Extract this ZIP, add your customized README, and you have a deployment-ready domain package.

2. 📄 Download domain-config.json Only

If you only need the configuration file (because you are updating an existing domain), download just the JSON.

3. 🔗 Generate Shareable Link

Creates a unique URL that lets others import your domain configuration into their own Domain Builder instance. Useful for: - Sharing work-in-progress with team members - Publishing domain templates for others to customize - Backing up your configuration

The link expires after 30 days unless you regenerate it.

4. ☁️ Upload to Data Publisher Server

Authenticates with your Data Publisher account and uploads the complete domain package directly to your account's domain library. The domain becomes available in your installation immediately — no manual file transfer required.

This is the fastest path from configuration to testing. Click the button, confirm the upload, and your domain appears in the domain selection menu within seconds.

Editing an Existing Domain

You can import existing domains for editing:

1. Click "Import Existing Domain" on the wizard home screen
2. Upload your domain-config.json file
3. The Domain Builder reconstructs the wizard state from the JSON
4. Edit any step as needed
5. Export the updated configuration

This is invaluable when: - Updating a domain you created manually to add table groups - Adding AI configuration to an older domain - Fixing validation rules or relationships

The Domain Builder reads your JSON, populates every field, and lets you edit visually. Save hours of manual JSON surgery.

Best Practices

1. Use Auto-Generation Features First

The Domain Builder can auto-detect relationships and auto-generate AI configuration. Always try these first. They are correct 80-90% of the time, and you can manually tweak the remaining 10-20% in seconds.

2. Configure Field Properties as You Upload

Do not skip the Field Editor. The 5 minutes you invest per table configuring validation rules and form generation properties will save hours of frustration later when users encounter cryptic errors or missing filter options.

3. Organize with Table Groups

Every domain with more than 6 tables should use table groups. Users overwhelmingly prefer organized categories to flat lists. The Domain Builder makes this trivial — there is no reason not to do it.

4. Add Template Filters to Every Template

Even if a template does not require filters, consider whether users would benefit from sorting or limited filtering options. Templates with filters get used more frequently because they feel more powerful and customizable.

5. Enable AI Recommendations

The 5 minutes it takes to configure AI recommendations pays back immediately in user satisfaction. Users love typing "I need to send a welcome letter" and getting the exact template they need.

6. Download the ZIP, Not Just the JSON

The complete package includes everything you need for deployment. Downloading just the JSON means you have to manually assemble the folder structure later.

What You Cannot Do in the Domain Builder (Yet)

The Domain Builder is comprehensive but not exhaustive. You still need manual work for:

1. Creating your README.md (Chapter 6)
   The builder includes a placeholder. You must write the actual documentation.

2. Generating Word templates (Chapter 5)
   The builder accepts .docx files but does not create them. You still run the generator script.

3. Advanced template filter options (Chapter 4.8)
   Dynamic filter options that query related tables require manual JSON editing. The builder supports static filters only.

4. Custom validation error messages
   You can set regex patterns, but custom error messages must be added to the JSON manually.

5. OAuth redirect URI configuration (Chapter 4.7)
   The builder enables OAuth but does not configure the server-side redirect URIs. You handle that separately.

These are planned for future releases. But even with these limitations, the Domain Builder eliminates 80-90% of the manual work involved in domain creation.

Time Savings: Before and After

Let's compare creating the legal services domain from Chapter 3 manually versus with the Domain Builder:

You save 6 hours. You eliminate syntax errors. You produce higher-quality configuration because the builder encourages best practices like validation rules and table groups.

And critically: you can now create a domain even if you have never looked at a JSON file before. The barrier to entry drops from "comfortable with code" to "can fill out a form."

When to Use the Domain Builder vs. Manual Editing

Use the Domain Builder for: - New domain creation - Domains with 6+ tables - Adding table groups to existing domains - Configuring AI recommendations - Setting up validation rules - Enabling OAuth for external data - Anything involving template filters

Use manual JSON editing for: - Quick single-field changes - Advanced features not yet supported in the UI - Batch updates across multiple domains (scripting) - Version control workflows (JSON diffs are easier to review)

Most users will spend 90%+ of their time in the Domain Builder and only drop to manual JSON editing for edge cases. That is by design.

Integration with Other Chapters

The Domain Builder directly implements features described in:

If you are reading those chapters to understand how these features work conceptually — excellent. But do not implement them by hand. Use the Domain Builder. It produces the exact JSON those chapters describe, validated and error-free.

Conclusion

The Domain Builder is not a toy. It is not a simplified interface for beginners. It is the primary domain creation tool that 80%+ of users should use for 90%+ of their domain development work.

It eliminates entire categories of errors. It saves hours per domain. It encourages best practices by making them easy. And it lowers the barrier to entry so that domain experts — people who understand legal workflows, educational operations, or real estate processes — can create domains without needing a computer science degree.

If you take away one thing from this chapter: use the Domain Builder. You will spend less time debugging JSON and more time designing great domains.

Now proceed to Chapter 4.5 to understand table groups in depth, knowing that you will configure them visually when the time comes.

Next Chapter: Chapter 4.5: Progressive Disclosure with Table Groups →
Previous Chapter: ← Chapter 4: Building the Foundation