postgres/docs/README.md

# features.json - Complete Configuration System

**Build half your app (or more!) with declarative JSON configuration.**

## Overview

The enhanced `features.json` is a **comprehensive, declarative configuration system** that enables you to build complete applications without writing most of the boilerplate code. It provides:

- 🌐 **Translations** (i18n) for all UI elements
- 📐 **Layout definitions** for tables, columns, and components
- 🎯 **Action namespaces** mapping UI actions to functions
- 📝 **Form schemas** with validation rules
- 🔌 **API endpoint** configurations
- 🔐 **Permission** system for role-based access
- 🔗 **Relationship** definitions between resources
- 🌳 **Component trees** for declarative UI hierarchies
- ⚙️ **Component props** with runtime validation

## Quick Example

Instead of writing this JSX:

```jsx
function UserListPage() {
  const [users, setUsers] = useState([]);
  
  return (
    <Box>
      <Typography variant="h4">Users</Typography>
      <Button 
        variant="contained" 
        startIcon={<AddIcon />}
        onClick={handleCreate}
      >
        Create New
      </Button>
      <DataGrid 
        columns={[
          { name: 'id', label: 'ID', width: 80 },
          { name: 'name', label: 'Name', width: 200 },
          { name: 'email', label: 'Email', width: 250 }
        ]}
        rows={users}
      />
    </Box>
  );
}
```

You define this in JSON:

```json
{
  "componentTrees": {
    "UserListPage": {
      "component": "Box",
      "children": [
        {
          "component": "Typography",
          "props": { "variant": "h4", "text": "{{resourceName}}" }
        },
        {
          "component": "Button",
          "condition": "hasPermission('create')",
          "props": {
            "variant": "contained",
            "startIcon": "Add",
            "text": "Create New",
            "onClick": "handleCreate"
          }
        },
        {
          "component": "DataGrid",
          "dataSource": "tableData",
          "props": {
            "columns": "{{columns}}",
            "rows": "{{rows}}"
          }
        }
      ]
    }
  }
}
```

Then render it:

```typescript
import { getComponentTree } from '@/utils/featureConfig';

const tree = getComponentTree('UserListPage');
renderComponentTree(tree, data, handlers);
```

## What Can You Build?

### ✅ Complete CRUD Interfaces

Define tables, columns, forms, and actions in JSON:

```json
{
  "tableLayouts": {
    "users": {
      "columns": ["id", "name", "email"],
      "columnWidths": { "id": 80, "name": 200, "email": 250 }
    }
  },
  "formSchemas": {
    "users": {
      "fields": [
        { "name": "name", "type": "text", "required": true },
        { "name": "email", "type": "email", "required": true }
      ]
    }
  }
}
```

### ✅ Multilingual UIs

Support multiple languages:

```json
{
  "translations": {
    "en": {
      "actions": { "create": "Create", "delete": "Delete" }
    },
    "fr": {
      "actions": { "create": "Créer", "delete": "Supprimer" }
    }
  }
}
```

### ✅ Permission-Based Access

Control who can do what:

```json
{
  "permissions": {
    "users": {
      "create": ["admin"],
      "read": ["admin", "user"],
      "update": ["admin"],
      "delete": ["admin"]
    }
  }
}
```

```typescript
if (hasPermission('users', 'delete', userRole)) {
  // Show delete button
}
```

### ✅ Complete Page Layouts

Define entire pages declaratively:

```json
{
  "componentTrees": {
    "AdminDashboard": {
      "component": "Box",
      "children": [
        { "component": "Sidebar" },
        { "component": "AppBar" },
        { "component": "MainContent" }
      ]
    }
  }
}
```

### ✅ Validated Components

Ensure components are used correctly:

```json
{
  "componentProps": {
    "Button": {
      "props": {
        "variant": {
          "type": "enum",
          "values": ["text", "outlined", "contained"],
          "default": "text"
        }
      }
    }
  }
}
```

```typescript
// Automatic validation
validateComponentProps('Button', {
  variant: 'invalid' // ❌ Error caught!
});
```

## Configuration Sections

### 1. Translations
Define UI text in multiple languages.

**Functions:**
- `getFeatureTranslation(id, locale)`
- `getActionTranslation(action, locale)`
- `getTableTranslation(table, locale)`
- `getColumnTranslation(column, locale)`

### 2. Actions
Map UI actions to function names.

**Functions:**
- `getActionFunctionName(feature, action)`

### 3. Table & Column Layouts
Define how data is displayed.

**Functions:**
- `getTableLayout(table)`
- `getColumnLayout(column)`

### 4. Table & Column Features
Enable/disable features per table/column.

**Functions:**
- `getTableFeatures(table)`
- `getColumnFeatures(column)`

### 5. Form Schemas
Define forms declaratively.

**Functions:**
- `getFormSchema(table)`

### 6. Validation Rules
Define reusable validation patterns.

**Functions:**
- `getValidationRule(ruleName)`

### 7. API Endpoints
Configure REST API routes.

**Functions:**
- `getApiEndpoints(resource)`
- `getApiEndpoint(resource, action)`

### 8. Permissions
Role-based access control.

**Functions:**
- `getPermissions(resource)`
- `hasPermission(resource, action, role)`

### 9. Relationships
Define data relationships.

**Functions:**
- `getRelationships(table)`

### 10. UI Views
Configure view types for resources.

**Functions:**
- `getUiViews(resource)`
- `getUiView(resource, view)`

### 11. Component Trees
Define UI hierarchies in JSON.

**Functions:**
- `getComponentTree(treeName)`
- `getAllComponentTrees()`

### 12. Component Props
Define and validate component props.

**Functions:**
- `getComponentPropSchema(component)`
- `validateComponentProps(component, props)`
- `getComponentsByCategory(category)`

### 13. Component Layouts
Configure component display settings.

**Functions:**
- `getComponentLayout(component)`

## Complete Example

Generate a full CRUD interface from configuration:

```typescript
import {
  getTableLayout,
  getFormSchema,
  getApiEndpoints,
  getPermissions,
  getComponentTree,
  hasPermission,
} from '@/utils/featureConfig';

function generateCRUDPage(resourceName: string, userRole: string) {
  const layout = getTableLayout(resourceName);
  const form = getFormSchema(resourceName);
  const api = getApiEndpoints(resourceName);
  const permissions = getPermissions(resourceName);
  const tree = getComponentTree('ResourceListPage');
  
  return {
    // Table configuration
    columns: layout?.columns.map(col => ({
      name: col,
      width: layout.columnWidths[col],
    })),
    
    // Actions based on permissions
    actions: ['create', 'update', 'delete'].filter(action =>
      hasPermission(resourceName, action, userRole)
    ),
    
    // Form fields
    formFields: form?.fields,
    
    // API endpoints
    endpoints: api,
    
    // UI tree
    componentTree: tree,
  };
}

// Generate complete page for users
const userPage = generateCRUDPage('users', 'admin');
```

## Documentation

Comprehensive guides are available:

1. **[FEATURES_CONFIG_GUIDE.md](./FEATURES_CONFIG_GUIDE.md)** - Quick start and API reference
2. **[BUILDING_WITH_CONFIG.md](./BUILDING_WITH_CONFIG.md)** - Building apps from configuration
3. **[COMPONENT_TREES.md](./COMPONENT_TREES.md)** - Declarative UI hierarchies
4. **[COMPONENT_PROPS.md](./COMPONENT_PROPS.md)** - Prop validation and type checking

## Statistics

- **~2000 lines** of configuration
- **40+ helper functions**
- **25+ TypeScript types**
- **250+ test cases**
- **21 component schemas**
- **5 pre-built component trees**
- **60+ pages** of documentation

## Benefits

### 🚀 Rapid Development
Add features by updating JSON, not writing code.

### 🎯 Consistency
All features follow the same patterns.

### 📚 Self-Documenting
Configuration serves as documentation.

### ✅ Type Safety
Runtime validation without TypeScript overhead.

### 🔧 Maintainable
Central source of truth for all configuration.

### 🌐 Internationalized
Built-in translation support.

### 🔐 Secure
Centralized permission management.

### 🧪 Testable
Easy to test configuration vs. hardcoded logic.

### 🎨 Flexible
Override defaults when needed.

### 📈 Scalable
Add resources without boilerplate.

## Real-World Use Cases

### 1. Admin Panels
Generate complete admin interfaces from database schema.

### 2. CRUD Applications
Build data management apps declaratively.

### 3. Dashboards
Create dashboards with widgets defined in JSON.

### 4. Forms
Generate complex forms with validation.

### 5. Permissions
Implement role-based access control.

### 6. Multi-Tenant Apps
Configure different UIs per tenant.

### 7. API Clients
Auto-generate API calls from endpoints.

### 8. Documentation
Generate component docs from schemas.

### 9. Prototyping
Quickly build prototypes without code.

### 10. A/B Testing
Swap UI configurations for testing.

## Best Practices

1. **Start with core resources** - Define tables, columns, forms
2. **Add translations early** - Easier than retrofitting
3. **Use validation** - Validate props before rendering
4. **Document everything** - Add descriptions to schemas
5. **Test configurations** - Unit test helper functions
6. **Version control** - Track config changes
7. **Keep trees shallow** - Avoid deep nesting
8. **Reuse patterns** - Extract common structures
9. **Validate on save** - Check JSON validity
10. **Generate types** - Create TypeScript types from config

## Getting Started

1. **Explore the config:**
```typescript
import { getFeatures, getNavItems } from '@/utils/featureConfig';

const features = getFeatures();
const navItems = getNavItems();
```

2. **Add a new resource:**
```json
{
  "tableLayouts": {
    "products": {
      "columns": ["id", "name", "price"]
    }
  }
}
```

3. **Generate a form:**
```typescript
const schema = getFormSchema('products');
// Use schema to render form
```

4. **Check permissions:**
```typescript
if (hasPermission('products', 'create', userRole)) {
  // Show create button
}
```

5. **Render a component tree:**
```typescript
const tree = getComponentTree('ResourceListPage');
renderComponentTree(tree, data, handlers);
```

## Conclusion

With a comprehensive features.json, you can:

✅ Build half your app (or more!) from configuration
✅ Generate UIs declaratively
✅ Validate components at runtime
✅ Support multiple languages
✅ Implement permissions
✅ Create forms without code
✅ Define entire page layouts
✅ Maintain consistency
✅ Improve developer experience
✅ Scale rapidly

**The future is declarative. The future is features.json.**

---

For detailed documentation, see the guides in the `/docs` folder.