# 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

```bash
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

# C++ Build Assistant (for DBAL daemon)
npm run cpp:check        # Check C++ build dependencies
npm run cpp:full         # Complete C++ build workflow
npm run cpp:build        # Build C++ project with Ninja
npm run cpp:test         # Run C++ tests
npm run cpp:clean        # Clean C++ build artifacts
```

### 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:

```bash
# 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:**
```bash
# 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](docs/ACT_TESTING.md)  
**⚡ Quick Reference:** [ACT_QUICK_REFERENCE.md](docs/ACT_QUICK_REFERENCE.md)

### C++ Build System

The project includes a C++ daemon (DBAL) with integrated build automation using Conan and Ninja:

```bash
# First time setup
npm run cpp:full

# Daily development
npm run cpp:build       # Incremental build
npm run cpp:test        # Run C++ tests
npm run cpp:rebuild     # Clean rebuild
```

**Prerequisites:** CMake, Conan, Ninja, GCC/Clang

```bash
# macOS
brew install cmake conan ninja gcc

# Linux
sudo apt-get install cmake ninja-build g++
pip install conan

# Windows
choco install cmake conan ninja
```

**📖 Complete Guide:** [CPP_BUILD_ASSISTANT.md](docs/CPP_BUILD_ASSISTANT.md)  
**⚡ Quick Reference:** [CPP_BUILD_QUICK_REF.md](docs/CPP_BUILD_QUICK_REF.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](docs/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](.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:
```bash
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:

```json
{
  "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:

```json
{
  "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:

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

The related model must exist in the same app.

## Validation

Add validation rules to fields:

```json
{
  "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:

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

Or for multi-line help:

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

## List View Configuration

Control which fields appear in the list view:

```json
{
  "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`.