low-code-react-app-b/docs/JSON_CONFIG_GUIDE.md

JSON Configuration Quick Reference

📚 Configuration Files Overview

CodeForge now uses JSON configuration files for all major settings. This guide shows what each file contains and how to use them.

---

📄 File Locations

/workspaces/spark-template/
├── app.config.json              # Main application configuration
├── component-registry.json      # Component lazy loading definitions
├── feature-toggles.json         # Feature flag defaults and profiles
├── deployment-config.json       # Platform-specific deployment settings
├── theme.json                   # Tailwind theme customization (empty but supported)
├── components.json              # shadcn component configuration
├── architecture.json            # Architecture and page renderer config
└── src/config/
    ├── pages.json              # Page definitions and navigation
    ├── seed-data.json          # Default project data
    └── component-trees/        # JSON component tree definitions

---

🔧 app.config.json

Purpose: Main application settings including branding, server, build, and features

Key Sections:

App Metadata

{
  "app": {
    "name": "CodeForge",
    "title": "CodeForge - Low-Code Development Platform",
    "version": "6.0.0",
    "themeColor": "#8b5cf6"
  }
}

Server Configuration

{
  "server": {
    "development": {
      "host": "0.0.0.0",
      "port": 5000
    },
    "production": {
      "host": "0.0.0.0",
      "port": 80,
      "basePath": "./"
    }
  }
}

Build Settings

{
  "build": {
    "outDir": "dist",
    "sourcemap": false,
    "minify": "terser",
    "chunks": {
      "react-vendor": ["react", "react-dom"],
      "ui-core": ["@radix-ui/..."]
    }
  }
}

Feature Flags

{
  "features": {
    "preloadCriticalComponents": true,
    "bundleMetrics": true
  }
}

---

🎨 component-registry.json

Purpose: Define all lazy-loaded components with preload strategies

Structure:

{
  "components": [
    {
      "name": "ProjectDashboard",
      "path": "@/components/ProjectDashboard",
      "export": "ProjectDashboard",
      "type": "feature",
      "preload": true,
      "preloadPriority": "high",
      "category": "dashboard"
    }
  ],
  "dialogs": [...],
  "pwa": [...],
  "preloadStrategy": {
    "critical": ["ProjectDashboard", "CodeEditor"],
    "preloadDelay": 100
  }
}

Component Properties:

• name - Unique component identifier
• path - Import path
• export - Named export from module
• type - Component type (feature, dialog, pwa)
• preload - Whether to preload component
• preloadPriority - Priority level (high, medium, low)
• category - Grouping category
• dependencies - External dependencies (e.g., monaco-editor)
• experimental - Mark as experimental feature

---

🎛️ feature-toggles.json

Purpose: Feature flag defaults, profiles, and environment overrides

Structure:

{
  "defaults": {
    "codeEditor": {
      "enabled": true,
      "description": "Monaco code editor...",
      "category": "core"
    }
  },
  "categories": {
    "core": {
      "label": "Core Features",
      "icon": "StarFour"
    }
  },
  "environments": {
    "development": {
      "overrides": {
        "modelsJSON": true
      }
    }
  },
  "profiles": {
    "minimal": {
      "enabled": ["codeEditor", "documentation"]
    }
  }
}

Usage:

1. Default State - All features have a default enabled/disabled state
2. Environment Overrides - Override defaults per environment (dev, staging, prod)
3. Profiles - Predefined feature sets (minimal, designer, developer, testing-focused)
4. Categories - Group related features for UI organization

---

🚀 deployment-config.json

Purpose: Platform-specific deployment configurations and optimizations

Platforms Supported:

• ✅ CapRover
• ✅ Docker Compose
• ⚪ Heroku (disabled by default)
• ⚪ Vercel (disabled by default)
• ⚪ Netlify (disabled by default)
• ⚪ AWS ECS (disabled by default)
• ⚪ Kubernetes (disabled by default)

CapRover Configuration:

{
  "platforms": {
    "caprover": {
      "enabled": true,
      "appName": "codeforge",
      "containerHttpPort": 80,
      "healthCheck": {
        "path": "/health",
        "interval": 30
      },
      "buildOptimizations": {
        "simplifiedChunks": true,
        "aggressiveMinification": true
      }
    }
  }
}

Build Profiles:

{
  "buildProfiles": {
    "caprover-optimized": {
      "chunks": {
        "strategy": "simple",
        "groups": {
          "vendor": ["node_modules"],
          "app": ["src"]
        }
      }
    }
  }
}

---

📋 pages.json

Purpose: Define all pages, navigation, shortcuts, and component mappings

Location: src/config/pages.json

Page Structure:

{
  "pages": [
    {
      "id": "dashboard",
      "title": "Dashboard",
      "icon": "ChartBar",
      "component": "ProjectDashboard",
      "enabled": true,
      "shortcut": "ctrl+1",
      "order": 1,
      "props": {
        "state": ["files", "models"],
        "actions": ["onFileChange:handleFileChange"]
      }
    }
  ]
}

Page Properties:

• id - Unique page identifier (used in URLs)
• title - Display name in navigation
• icon - Phosphor icon name
• component - Component name from registry
• enabled - Show/hide page
• toggleKey - Feature toggle key (optional)
• shortcut - Keyboard shortcut (optional)
• order - Navigation order
• props - State and action mappings
• resizableConfig - Split pane configuration (optional)

---

🎨 theme.json

Purpose: Tailwind theme customization (currently empty, ready for use)

Location: theme.json (root)

Usage:

{
  "extend": {
    "colors": {
      "brand": {
        "50": "#f0f9ff",
        "500": "#3b82f6",
        "900": "#1e3a8a"
      }
    },
    "fontFamily": {
      "custom": ["Custom Font", "sans-serif"]
    }
  }
}

Tailwind config already reads from this file via tailwind.config.js

---

🏗️ architecture.json

Purpose: High-level architecture configuration

Location: architecture.json (root)

Structure:

{
  "pages": {
    "dashboard": {
      "renderer": "json",
      "schema": "./pages/dashboard.json"
    }
  },
  "hooks": {
    "data": ["useDataSource", "useCRUD"],
    "forms": ["useFormField"],
    "ui": ["useDialog"]
  },
  "atomicComponents": {
    "maxLOC": 150,
    "categories": {
      "atoms": [...],
      "molecules": [...],
      "organisms": [...]
    }
  }
}

---

🔧 Usage Examples

1. Change App Name and Branding

Edit app.config.json:

{
  "app": {
    "name": "MyApp",
    "title": "MyApp - Custom Platform",
    "themeColor": "#ff0000"
  }
}

Then update index.html to read from config (requires build script)

2. Enable Experimental Features in Development

Edit feature-toggles.json:

{
  "environments": {
    "development": {
      "overrides": {
        "modelsJSON": true,
        "componentTreesJSON": true
      }
    }
  }
}

3. Optimize Build for CapRover

Use the caprover-optimized build profile from deployment-config.json:

# Set environment variable
export BUILD_PROFILE=caprover-optimized

# Build with profile
npm run build

4. Add New Page

Edit src/config/pages.json:

{
  "pages": [
    {
      "id": "my-page",
      "title": "My Page",
      "icon": "Rocket",
      "component": "MyComponent",
      "enabled": true,
      "order": 100
    }
  ]
}

Add component to component-registry.json:

{
  "components": [
    {
      "name": "MyComponent",
      "path": "@/components/MyComponent",
      "export": "MyComponent",
      "type": "feature",
      "preload": false
    }
  ]
}

5. Change Server Port

Edit app.config.json:

{
  "server": {
    "development": {
      "port": 3000
    }
  }
}

Then update vite.config.ts to read from config

---

🛠️ Implementation Status

File	Status	Needs Update
app.config.json	✅ Created	vite.config.ts, index.html
component-registry.json	✅ Created	component-registry.ts
feature-toggles.json	✅ Created	FeatureToggleSettings component
deployment-config.json	✅ Created	Dockerfile, CI/CD scripts
pages.json	✅ Exists	No changes needed
theme.json	✅ Supported	Ready for customization
architecture.json	✅ Exists	No changes needed

---

🚀 Next Steps

To Use New Configs:

1. Update vite.config.ts to import app.config.json
2. Update component-registry.ts to read from component-registry.json
3. Update feature toggle hook to load from feature-toggles.json
4. Create build script to generate index.html from template + config
5. Update Dockerfile to use deployment-config.json settings
6. Test all configurations in development and production

Benefits:

• ✅ No rebuilds for config changes (in development)
• ✅ Environment-specific settings
• ✅ Platform-optimized builds
• ✅ Easy customization and branding
• ✅ Version control friendly
• ✅ Documentation via JSON schemas

---

📚 Related Documentation

• HARDCODED_ANALYSIS.md - Detailed analysis of hardcoded values
• README.md - Full project documentation
• DEPLOYMENT.md - Deployment guide
• src/config/pages.json - Page configuration

---

Last Updated: 2024 Version: 1.0.0