Django-Style React Admin Panel Generator

A declarative admin panel generator that creates full-featured CRUD interfaces from JSON schema definitions. Inspired by Django's admin panel, this tool lets you define data models and UI configuration declaratively without writing component code.

Features

• Declarative Schema Definition - Define your entire data model in JSON
• Automatic CRUD Generation - List views, forms, validation automatically generated
• Field Types - String, text, number, boolean, date, datetime, email, URL, select, relations, JSON
• Advanced Features - Sorting, filtering, search, validation, relationships
• Persistent Storage - Data automatically saved using Spark KV storage
• Live Schema Editing - Edit schemas in real-time through the UI
• CI/CD Pipeline - Automated testing, linting, and deployment
• AI-Assisted Development - Automated code reviews and issue triage
• E2E Testing - Comprehensive Playwright test suite

Quick Start

1. Clone the repository
2. Install dependencies: npm install
3. Launch the app: npm run dev
4. Use the sidebar to navigate between models
5. Click "Create New" to add records
6. Edit or delete records using the action buttons
7. Click "Edit Schema" to customize your data models

Development

Available Scripts

npm run dev              # Start development server
npm run build            # Build for production
npm run lint             # Run ESLint
npm run lint:fix         # Auto-fix linting issues
npm run test             # Run unit tests in watch mode
npm run test:unit        # Run unit tests once
npm run test:unit:watch  # Run unit tests in watch mode
npm run test:unit:ui     # Run unit tests with UI
npm run test:unit:coverage # Run unit tests with coverage report
npm run test:e2e         # Run Playwright e2e tests
npm run test:e2e:ui      # Run tests with Playwright UI
npm run test:e2e:headed  # Run tests in headed browser mode
npm run test:all         # Run all tests (unit + e2e)
npm run preview          # Preview production build
npm run act              # Run GitHub Actions workflows locally with act
npm run act:lint         # Run only lint job locally
npm run act:e2e          # Run only e2e tests job locally
npm run db:generate      # Generate Prisma client from schema
npm run db:push          # Apply schema changes to the local SQLite database
npm run db:migrate       # Apply migrations in CI/production environments

Database (Prisma)

The project now uses Prisma with a SQLite database for local development.

1. Copy the sample environment file: cp .env.example .env
2. Ensure DATABASE_URL points to the SQLite database (default: file:./dev.db relative to prisma/)
3. Generate the client: npm run db:generate
4. Create or update the local database schema: npm run db:push

GitHub Actions runs prisma generate and prisma migrate deploy to validate the schema on every pull request.

Testing GitHub Actions Locally with Act

Test workflows locally before pushing to catch issues early:

# Quick diagnostics (no act installation required)
./scripts/diagnose-workflows.sh

# Interactive workflow testing menu
./scripts/test-workflows.sh

# Or use act directly
act -l                    # List all workflows
act push                  # Run full CI pipeline
act -j lint              # Test specific job

Installation:

# macOS
brew install act

# Linux
curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Windows
choco install act-cli

📖 Complete Guide: ACT_TESTING.md
⚡ Quick Reference: ACT_QUICK_REFERENCE.md

Code Quality

This project uses strict ESLint rules with TypeScript support:

• No explicit any types (warnings)
• Promise handling required
• React hooks dependencies validated
• Console statements flagged (except warn/error)

Run npm run lint:fix before committing to auto-fix issues.

Testing

The project includes comprehensive testing at multiple levels:

Unit Tests (Vitest)

• Package metadata validation
• Component structure tests
• Configuration validation
• Run with npm run test:unit
• Coverage reports with npm run test:unit:coverage
• Interactive UI with npm run test:unit:ui

Each package in /packages has a tests/ folder with unit tests. See PACKAGE_TESTS.md for details.

E2E Tests (Playwright)

• Login and authentication flows
• Navigation between sections
• CRUD operations
• Form validation
• Schema editor functionality
• Run with npm run test:e2e

Tests run automatically on every PR via GitHub Actions.

CI/CD & Automation

Automated Workflows

1. CI/CD Pipeline - Runs on every push and PR

   • Linting with ESLint
   • TypeScript compilation
   • Production build
   • E2E tests with Playwright
   • Code quality checks

2. Automated Code Review - Reviews every PR

   • Security vulnerability checks
   • Code quality analysis
   • Type safety validation
   • Best practices enforcement
   • Auto-approves PRs with no issues

3. Auto-Merge - Merges approved PRs automatically

   • Waits for all CI checks to pass
   • Requires PR approval
   • Uses squash merge
   • Automatically deletes branch after merge

4. Issue Triage - Categorizes and labels issues

   • Auto-labels by type (bug, feature, docs)
   • Assigns priority levels
   • Flags AI-fixable issues
   • Welcomes contributors

5. PR Management - Organizes pull requests

   • Auto-labels based on changed files
   • Validates PR descriptions
   • Links related issues
   • Size indicators (small/medium/large)

See .github/workflows/README.md for detailed workflow documentation.

Contributing

1. Create a branch for your changes
2. Make your changes and test locally
3. Push your branch - workflows run automatically
4. Address any review comments
5. Once approved and tests pass, PR merges automatically

The automated workflows will:

• Review your code
• Run tests
• Approve if everything looks good
• Merge and cleanup after approval

Packages

This project uses a modular package system. The packages/ folder contains component packages that are committed to the repository.

If you need to add a new package, use:

npm run setup-packages <package-name>

This will create the required package structure with placeholder files.

Schema Structure

The schema is a JSON object with the following structure:

{
  "apps": [
    {
      "name": "app_name",
      "label": "App Label",
      "models": [
        {
          "name": "model_name",
          "label": "Model Label",
          "labelPlural": "Models",
          "icon": "IconName",
          "listDisplay": ["field1", "field2"],
          "listFilter": ["field3"],
          "searchFields": ["field1", "field2"],
          "ordering": ["-field2"],
          "fields": [
            {
              "name": "field_name",
              "type": "string",
              "label": "Field Label",
              "required": true,
              "unique": false,
              "default": "value",
              "helpText": "Help text or array of strings",
              "validation": {
                "min": 0,
                "max": 100,
                "minLength": 3,
                "maxLength": 200,
                "pattern": "^[a-z]+$"
              },
              "listDisplay": true,
              "searchable": true,
              "sortable": true,
              "editable": true
            }
          ]
        }
      ]
    }
  ]
}

Field Types

Basic Types

• string - Single-line text input
• text - Multi-line textarea
• number - Numeric input with min/max validation
• boolean - Switch/toggle control
• email - Email input with validation
• url - URL input with validation

Date/Time

• date - Date picker
• datetime - Date and time picker

Advanced Types

• select - Dropdown with predefined choices
• relation - Foreign key to another model
• json - JSON editor for complex data

Select Field Choices

For select fields, define choices as an array:

{
  "name": "status",
  "type": "select",
  "choices": [
    { "value": "draft", "label": "Draft" },
    { "value": "published", "label": "Published" },
    { "value": "archived", "label": "Archived" }
  ]
}

Relationships

Define relationships between models using the relation type:

{
  "name": "author",
  "type": "relation",
  "relatedModel": "author",
  "required": true
}

The related model must exist in the same app.

Validation

Add validation rules to fields:

{
  "validation": {
    "min": 0,
    "max": 100,
    "minLength": 3,
    "maxLength": 200,
    "pattern": "^[a-z0-9-]+$"
  }
}

Help Text

Provide help text as a string or array of strings:

{
  "helpText": "Single line help text"
}

Or for multi-line help:

{
  "helpText": [
    "First line of help",
    "Second line of help"
  ]
}

List View Configuration

Control which fields appear in the list view:

{
  "listDisplay": ["title", "author", "status", "publishedAt"],
  "listFilter": ["status", "author"],
  "searchFields": ["title", "content"],
  "ordering": ["-publishedAt"]
}

• listDisplay - Fields to show in the table
• listFilter - Fields to offer as filters (select/boolean only)
• searchFields - Fields to search when using the search box
• ordering - Default sort order (prefix with - for descending)

Example Schemas

See example-schemas.json for complete examples including:

• Blog with posts and authors
• Task manager with projects and tasks
• E-commerce with products and categories

Tips

1. Start Simple - Begin with basic string and text fields, add complexity later
2. Use Relations - Connect related data with relation fields
3. Add Validation - Prevent bad data with field validation rules
4. Leverage Defaults - Set sensible defaults for better UX
5. Help Text - Guide users with helpful field descriptions
6. Test Incrementally - Edit and test schema changes one model at a time

Technical Details

• Built with React, TypeScript, and Tailwind CSS
• Uses shadcn/ui components for consistent design
• Data persisted with Spark KV storage
• Framer Motion for smooth animations
• Full type safety with TypeScript

Keyboard Shortcuts

• Click table headers to sort
• Use search box for quick filtering
• Forms validate on blur and submit

Limitations

• Relations only work within the same app
• No many-to-many relationships (use JSON arrays)
• No file uploads (use URL fields to reference external files)
• Maximum recommended records per model: 1000

Architecture

The system consists of:

1. Schema Parser - Validates and processes JSON schemas
2. Field Renderer - Dynamically renders form inputs based on field types
3. Model List View - Table view with sorting, filtering, search
4. Record Form - Auto-generated create/edit forms with validation
5. Schema Editor - Live JSON editor for schema modifications

All data is stored in the Spark KV store with keys like records_appname_modelname.