# Simple Task Manager

> **Complexity**: Beginner | **Entities**: 3 | **DSL Lines**: ~680

A team task management application demonstrating DAZZLE's core SaaS patterns. This is the recommended starting point for learning the DSL because it includes entities, relationships, access rules, workspaces, and generated runtime contracts in one small project.

## Quick Start

```bash
cd examples/simple_task
dazzle serve
```

- **UI**: http://localhost:3000
- **API**: http://localhost:8000/docs

## What This Example Demonstrates

### DSL Features

| Feature | Usage |
|---------|-------|
| **Entity Definition** | `User`, `Task`, and `TaskComment` entities |
| **Field Types** | `uuid`, `str(n)`, `text`, `enum`, `date`, `datetime` |
| **Field Modifiers** | `required`, `pk`, `auto_add`, `auto_update`, defaults |
| **Surfaces** | All 4 CRUD modes: `list`, `view`, `create`, `edit` |
| **UX Block** | `purpose`, `sort`, `filter`, `search`, `empty` |
| **Attention Signals** | `warning` and `notice` with conditional expressions |
| **Workspaces** | Metrics aggregation, filtered regions, limits |

### Architecture Pattern

```
SPEC.md          →  Human-readable requirements
    ↓
dsl/app.dsl      →  DAZZLE DSL implementation
    ↓
Dazzle Runtime  →  Live application (no code generation)
    ↓
E2E Tests        →  Automated validation
```

## Project Structure

```
simple_task/
├── SPEC.md              # Product specification (refined requirements)
├── README.md            # This file
├── dazzle.toml          # Project configuration
├── dsl/
│   └── app.dsl          # DAZZLE DSL definition
├── tests/
│   └── e2e/             # E2E test files
└── testspec.json        # Generated test specification
```

## The Specification Journey

### 1. SPEC.md - The Starting Point

The `SPEC.md` represents a refined product specification - what a founder might produce after working with an LLM assistant to clarify their requirements. It includes:

- **Vision Statement**: What problem does this solve?
- **User Personas**: Who will use this?
- **Domain Model**: Entities, fields, and business rules
- **UI Specification**: Surfaces with purpose, fields, and behaviors
- **Workspace Specification**: Dashboard layouts and data regions
- **User Stories**: Acceptance criteria with test flows

### 2. DSL - The Implementation

The `dsl/app.dsl` translates the spec into DAZZLE's declarative syntax. This excerpt shows the core `Task` entity:

```dsl
entity Task "Task":
  id: uuid pk
  title: str(200) required
  status: enum[todo,in_progress,review,done]=todo
  priority: enum[low,medium,high,urgent]=medium
  assigned_to: ref User
  created_by: ref User
  ...

surface task_list "Task List":
  uses entity Task
  mode: list
  ux:
    attention warning:
      when: due_date < today and status != done
      message: "Overdue task"
```

### 3. Running App - The Result

`dazzle serve` starts a fully functional application:
- **Backend**: FastAPI with PostgreSQL persistence
- **Frontend**: Server-rendered typed Fragments with HTMX behavior
- **Features**: Full CRUD, filtering, search, attention signals, access rules

## User Stories

| ID | Story | Test Status |
|----|-------|-------------|
| US-1 | Create a Task | Automated |
| US-2 | View Task Details | Automated |
| US-3 | Update Task Status | Automated |
| US-4 | Track Overdue Tasks | Automated |
| US-5 | Delete a Task | Automated |

## Running Tests

```bash
# Generate test specification from DSL
dazzle test generate

# Run E2E tests (requires running server)
dazzle test run

# Or run directly with pytest
pytest tests/e2e/ -v
```

## Learning Path

After understanding this example, progress to:

1. **contact_manager** (Beginner+) - List+detail pattern, DUAL_PANE_FLOW archetype
2. **support_tickets** (Intermediate) - Multi-entity relationships, refs
3. **ops_dashboard** (Intermediate+) - Personas, COMMAND_CENTER archetype
4. **fieldtest_hub** (Advanced) - Complex domain, access rules, persona scoping

## Key Concepts Illustrated

### Attention Signals
```dsl
attention warning:
  when: due_date < today and status != done
  message: "Overdue task"
```
Attention signals highlight important data conditions in the UI without writing custom code.

### Workspace Regions
```dsl
workspace dashboard "Task Dashboard":
  metrics:
    source: Task
    aggregate:
      total: count(Task)
      todo: count(Task where status = todo)
```
Workspaces compose multiple data views with aggregations and filters.

### UX Directives
```dsl
ux:
  purpose: "View and manage all tasks at a glance"
  sort: created_at desc
  filter: status, priority
  search: title, description
  empty: "No tasks yet. Create your first task!"
```
The `ux` block provides semantic hints for the UI layer.

## DSL Quick Reference

### Field Types
| Type | Example | Description |
|------|---------|-------------|
| `str(N)` | `title: str(200)` | String with max length |
| `text` | `description: text` | Unlimited text |
| `enum[...]` | `status: enum[a,b,c]` | Enumerated values |
| `date` | `due_date: date` | Date only |
| `datetime` | `created_at: datetime` | Date and time |
| `uuid` | `id: uuid pk` | Unique identifier |

### Field Modifiers
| Modifier | Example | Description |
|----------|---------|-------------|
| `required` | `title: str required` | Must have value |
| `pk` | `id: uuid pk` | Primary key |
| `=value` | `status: enum[...]=todo` | Default value |
| `auto_add` | `created_at: datetime auto_add` | Set on create |
| `auto_update` | `updated_at: datetime auto_update` | Set on update |

### Surface Modes
| Mode | Purpose |
|------|---------|
| `list` | Table/grid of multiple records |
| `view` | Read-only detail of one record |
| `create` | Form to create new record |
| `edit` | Form to update existing record |

## Customization Ideas

Try extending this example:

1. Add a `category` enum field to Task
2. Create a new workspace for "Weekly Review"
3. Add an attention signal for tasks due tomorrow
4. Create a surface for bulk status updates

## Screenshots

### Dashboard
![Dashboard](screenshots/dashboard.png)

### List View with Data
![List View](screenshots/14_list_view_data.png)

### Create Form
![Create Form](screenshots/05_create_form_no_inputs.png)

---

*Part of the DAZZLE Examples collection. See `/examples/README.md` for the full learning path.*
