Skip to content

Latest commit

 

History

History

example

README.md

Appwrite Generator - To-Do List Example

A comprehensive Flutter example app showcasing the Appwrite Generator package with a fully-functional to-do list application featuring 5 interconnected database tables.

Overview

This example demonstrates how to use the Appwrite Generator to create type-safe, production-ready Dart models from Appwrite database schemas. The app showcases:

  • ✅ 5 Database Tables with relationships
  • ✅ Enum Types for priority and status
  • ✅ DateTime Fields for tracking and due dates
  • ✅ Many-to-Many Relationships (todos ↔ tags)
  • ✅ One-to-Many Relationships (projects → todos, todos → comments)
  • ✅ Type-Safe Attribute Constants
  • ✅ Null-Safety based on required flags

Database Schema

1. Projects (projects)

Organize todos into workspaces

  • title (string, required)
  • description (string, optional)
  • color (string, required) - Hex color code
  • icon (string, optional)
  • status (enum, required) - active, archived, completed
  • created_at, updated_at (datetime, required)

2. Todos (todos)

Individual task items

  • title (string, required)
  • description (string, optional)
  • project_id (string, required) - Foreign key to projects
  • priority (enum, required) - low, medium, high, urgent
  • status (enum, required) - todo, in_progress, blocked, done
  • due_date, completed_at (datetime, optional)
  • estimated_hours (integer, optional)
  • created_at, updated_at (datetime, required)

3. Tags (tags)

Labels for categorization

  • name (string, required, unique)
  • color (string, required) - Hex color code
  • created_at (datetime, required)

4. TodoTags (todo_tags)

Many-to-many junction table

  • todo_id (string, required)
  • tag_id (string, required)
  • created_at (datetime, required)
  • Unique constraint on (todo_id, tag_id)

5. Comments (comments)

Discussion threads on tasks

  • todo_id (string, required) - Foreign key to todos
  • content (string, required)
  • author_name (string, optional)
  • created_at, updated_at (datetime, required)

Generated Models

The generator creates the following files for each table:

lib/models/
├── models.dart                    # Barrel export file
├── projects/
│   ├── project.dart              # Main model with fromJson, toJson, copyWith
│   ├── project_enums.dart        # Status enum
│   └── project_attributes.dart   # Type-safe attribute constants
├── todos/
│   ├── todo.dart
│   ├── todo_enums.dart           # Priority and Status enums
│   └── todo_attributes.dart
├── tags/
│   ├── tag.dart
│   └── tag_attributes.dart
├── todo_tags/
│   ├── todo_tag.dart
│   └── todo_tag_attributes.dart
└── comments/
    ├── comment.dart
    └── comment_attributes.dart

Usage Examples

Creating a Todo

import 'package:example/models/models.dart';
import 'package:example/models/todos/todo_enums.dart';

final todo = Todo(
  title: 'Review Appwrite Documentation',
  description: 'Go through all features',
  projectId: 'project_123',
  priority: Priority.high,
  status: Status.todo,
  dueDate: DateTime.now().add(Duration(days: 7)),
  estimatedHours: 5,
  createdAt: DateTime.now(),
  updatedAt: DateTime.now(),
);

// Convert to JSON for Appwrite
final json = todo.toJson();

// Parse from Appwrite response
final parsedTodo = Todo.fromJson(json);

Using Type-Safe Attributes

import 'package:example/models/todos/todo_attributes.dart';

// Use constants instead of magic strings
final query = [
  Query.equal(TodoAttributes.status, 'todo'),
  Query.lessThan(TodoAttributes.dueDate, DateTime.now().toIso8601String()),
];

Working with Enums

import 'package:example/models/todos/todo_enums.dart';

// Type-safe enum usage
final priority = Priority.urgent;
print(priority.value); // 'urgent'

// Parse from string (from Appwrite)
final status = Status.fromString('in_progress');
print(status); // Status.inProgress

Updating a Todo

// Use the generated copyWith method
final updatedTodo = todo.copyWith(
  status: Status.done,
  completedAt: DateTime.now(),
);

Running the Example

  1. Install dependencies:

    flutter pub get

  2. Run the app:

    flutter run

  3. Explore the features:

    • Navigate between projects using the drawer
    • View tasks with different priorities and statuses
    • Check task details including comments
    • See overdue indicators
    • Browse all tags

Regenerating Models

If you modify the appwrite.json schema:

# From the example directory
dart run ../bin/appwrite_generator.dart generate --input appwrite.json --output lib/models

Or use the configuration file approach:

# Create appwrite_generator.yaml
cat > appwrite_generator.yaml << EOF
input: appwrite.json
output: lib/models
clean: true
model_prefix: ''
EOF

# Generate models
dart run ../bin/appwrite_generator.dart generate

Connecting to Real Appwrite

To connect this example to an actual Appwrite instance:

  1. Update appwrite.json with your project details:

    {
  "projectId": "your-project-id",
  "endpoint": "https://cloud.appwrite.io/v1"
}

  2. Initialize the Appwrite client in main.dart:

    import 'package:appwrite/appwrite.dart';

final client = Client()
  .setEndpoint('https://cloud.appwrite.io/v1')
  .setProject('your-project-id');

final databases = Databases(client);

  3. Use the generated models with Appwrite SDK:

    // Create a document
final response = await databases.createDocument(
  databaseId: 'todo_db',
  collectionId: 'todos',
  documentId: ID.unique(),
  data: todo.toJson(),
);

// Parse the response
final savedTodo = Todo.fromJson(response.data);

Features Demonstrated

  • Type Safety: All models are strongly typed with null-safety
  • Enums: Automatic enum generation for constrained string fields
  • Attributes: Constants for all column names to avoid typos
  • Relationships: Proper modeling of foreign keys and junction tables
  • DateTime Handling: Automatic parsing of ISO 8601 datetime strings
  • JSON Serialization: Built-in fromJson and toJson methods
  • Immutability: copyWith method for updating immutable models

What's Next?

  • Add authentication (user login/logout)
  • Implement real CRUD operations with Appwrite SDK
  • Add real-time subscriptions for live updates
  • Implement the tag filtering functionality
  • Add search and filter capabilities
  • Export data to different formats

Learn More

License

This example is part of the appwrite_generator package and follows the same license.