@dv.nghiem/flowdeck 0.2.3 → 0.3.0

package/src/skills/cqrs/SKILL.md

@@ -0,0 +1,230 @@
+# CQRS (Command Query Responsibility Segregation)
+
+## When to Activate
+
+Activate when:
+- Designing read-heavy or write-heavy systems separately
+- Implementing complex domain models with divergent read/write logic
+- Building systems that need different data representations for reading vs. writing
+- Scaling read and write workloads independently
+- Implementing event sourcing alongside specialized read models
+
+## Steps
+
+### 1. Separate Command and Query Models
+
+| Aspect | Command | Query |
+|--------|---------|-------|
+| Purpose | Modify state | Read state |
+| Returns | Void / ACK | Data |
+| Side Effects | Yes | No |
+| Complexity | Business logic | Data shaping |
+
+Commands and queries should use **different models** with different schemas optimized for their specific use case.
+
+### 2. Design Command Side
+
+- Commands are **intent-based** (present tense: `PlaceOrder`, `UpdatePrice`)
+- Validate business rules **before** executing
+- Return success/failure, not data
+- Keep command handlers small and focused
+
+```typescript
+interface Command {
+  id: string;          // Correlation ID
+  type: string;        // Command type
+  payload: unknown;    // Command data
+  metadata: {
+    userId: string;
+    timestamp: string;
+    correlationId: string;
+  };
+}
+
+interface CommandHandler<T extends Command> {
+  execute(command: T): Promise<CommandResult>;
+}
+```
+
+### 3. Design Query Side
+
+- Queries are **data-focused** (past/read tense: `GetUserOrders`, `FindActiveProducts`)
+- Queries should be **side-effect free**
+- Return **read-optimized** data structures (possibly denormalized)
+- Support pagination, filtering, sorting
+
+```typescript
+interface Query {
+  id: string;
+  type: string;
+  parameters: Record<string, unknown>;
+  pagination?: { page: number; limit: number };
+  sorting?: { field: string; direction: 'asc' | 'desc' }[];
+}
+
+interface QueryHandler<T extends Query> {
+  execute(query: T): Promise<QueryResult>;
+}
+```
+
+### 4. Implement Synchronization
+
+When commands and queries share data:
+
+1. **Synchronous** (same DB): Update the read model transactionally
+2. **Asynchronous** (event-driven): Project events to read models
+3. **Dual writes**: Update both models, handle eventual consistency
+
+```typescript
+// Synchronous synchronization
+async function placeOrder(command: PlaceOrderCommand): Promise<void> {
+  const order = Order.create(command.payload);
+
+  await this.transactionManager.execute(async (tx) => {
+    // Write to command model
+    await this.orderRepo.save(order, tx);
+
+    // Synchronize to read model
+    const readModel = {
+      orderId: order.id,
+      customerId: order.customerId,
+      status: order.status,
+      total: order.total,
+      placedAt: order.placedAt
+    };
+    await this.orderReadRepo.save(readModel, tx);
+  });
+}
+```
+
+### 5. Handle Eventual Consistency
+
+If read and write models are updated asynchronously:
+
+- Document **expected consistency lag**
+- Design UIs to handle stale data gracefully
+- Implement **cache invalidation** strategies
+- Use **version numbers** or timestamps for cache validation
+
+## Examples
+
+### Command Implementation
+
+```typescript
+// commands/place-order.command.ts
+interface PlaceOrderCommand {
+  orderId?: string;        // Optional, generated if not provided
+  customerId: string;
+  items: OrderItem[];
+  paymentMethod: 'CARD' | 'PAYPAL';
+}
+
+class PlaceOrderCommandHandler implements CommandHandler<PlaceOrderCommand> {
+  async execute(command: PlaceOrderCommand): Promise<CommandResult> {
+    // 1. Validate command
+    const validation = this.validate(command);
+    if (!validation.success) {
+      return CommandResult.failure(validation.errors);
+    }
+
+    // 2. Check business invariants
+    const customer = await this.customerRepo.findById(command.customerId);
+    if (!customer.isActive) {
+      return CommandResult.failure('Customer account is not active');
+    }
+
+    // 3. Create aggregate
+    const order = Order.create({
+      id: command.orderId,
+      customerId: command.customerId,
+      items: command.items
+    });
+
+    // 4. Persist
+    await this.orderRepo.save(order);
+
+    // 5. Emit event for async processing
+    await this.eventBus.publish(OrderPlacedEvent.fromOrder(order));
+
+    return CommandResult.success({ orderId: order.id });
+  }
+}
+```
+
+### Query Implementation
+
+```typescript
+// queries/get-order-details.query.ts
+interface GetOrderDetailsQuery {
+  orderId: string;
+  includeItems?: boolean;
+}
+
+interface OrderDetailsReadModel {
+  orderId: string;
+  customerId: string;
+  customerName: string;
+  status: string;
+  total: number;
+  placedAt: string;
+  items?: OrderItemReadModel[];
+}
+
+class GetOrderDetailsQueryHandler implements QueryHandler<GetOrderDetailsQuery, OrderDetailsReadModel> {
+  async execute(query: GetOrderDetailsQuery): Promise<OrderDetailsReadModel> {
+    const order = await this.readModelRepo.findOrderWithDetails(query.orderId);
+
+    if (!order) {
+      throw new QueryNotFoundError('Order not found');
+    }
+
+    const result: OrderDetailsReadModel = {
+      orderId: order.orderId,
+      customerId: order.customerId,
+      customerName: order.customerName,
+      status: order.status,
+      total: order.total,
+      placedAt: order.placedAt
+    };
+
+    if (query.includeItems) {
+      result.items = await this.readModelRepo.findOrderItems(query.orderId);
+    }
+
+    return result;
+  }
+}
+```
+
+### Mediator Pattern for CQRS
+
+```typescript
+class CqrsMediator {
+  private commandHandlers: Map<string, CommandHandler<any>>;
+  private queryHandlers: Map<string, QueryHandler<any>>;
+
+  async send<T>(message: Command | Query): Promise<CommandResult | QueryResult> {
+    const handler = message instanceof Command
+      ? this.commandHandlers.get(message.type)
+      : this.queryHandlers.get(message.type);
+
+    if (!handler) {
+      throw new HandlerNotFoundError(message.type);
+    }
+
+    return handler.execute(message);
+  }
+}
+
+// Usage
+const result = await mediator.send(new PlaceOrderCommand({ ... }));
+const orderDetails = await mediator.send(new GetOrderDetailsQuery({ orderId: '123' }));
+```
+
+## Related Skills
+
+- api-design
+- event-driven-architecture
+- backend-patterns
+- event-sourcing
+- hexagonal-architecture

package/src/skills/ddd-architecture/SKILL.md

@@ -0,0 +1,104 @@
+# ddd-architecture
+
+## When to Activate
+When modeling complex business domains where deep understanding of the problem space, ubiquitous language, and bounded contexts are critical for long-term maintainability.
+
+## Steps
+1. **Establish the bounded context** - Identify the explicit boundary within which a single model (ubiquitous language) holds.
+2. **Build the domain model** - Create entities, value objects, aggregates, and domain events that reflect real business concepts.
+3. **Define aggregates** - Group related entities and value objects under a root aggregate that enforces invariants.
+4. **Identify domain events** - Capture meaningful business occurrences that other parts of the system may need to react to.
+5. **Create domain services** - Model operations that don't naturally belong to a single entity or value object.
+6. **Define repository interfaces** - Create ports for persisting and retrieving aggregates (implementation is infrastructure).
+7. **Implement application services** - Orchestrate the domain model, handle transactions, and coordinate multiple aggregates.
+8. **Establish anti-corruption layers** - Translate between external systems (legacy, third-party) and your domain model.
+
+## Examples
+```typescript
+// Value Object - Immutable concept with equality
+class Money {
+  constructor(
+    public readonly amount: number,
+    public readonly currency: Currency
+  ) {}
+
+  static of(amount: number, currency: Currency): Money {
+    return new Money(Math.round(amount * 100) / 100, currency)
+  }
+
+  add(other: Money): Money {
+    if (this.currency !== other.currency) {
+      throw new Error('Currency mismatch')
+    }
+    return Money.of(this.amount + other.amount, this.currency)
+  }
+}
+
+// Aggregate Root - Enforces invariants for the aggregate
+class Order extends AggregateRoot {
+  constructor(
+    private readonly id: OrderId,
+    private readonly customer: Customer,
+    private items: OrderItem[],
+    private status: OrderStatus
+  ) {
+    super()
+    this.validate()
+  }
+
+  private validate(): void {
+    if (this.items.length === 0) {
+      throw new DomainException('Order must have at least one item')
+    }
+  }
+
+  get total(): Money {
+    return this.items.reduce(
+      (sum, item) => sum.add(item.subtotal),
+      Money.of(0, Currency.USD)
+    )
+  }
+
+  // Business methods that enforce invariants
+  addItem(item: OrderItem): void {
+    if (this.status !== OrderStatus.DRAFT) {
+      throw new DomainException('Cannot add items to a non-draft order')
+    }
+    this.items.push(item)
+    this.addDomainEvent(new OrderItemAddedEvent(this.id, item))
+  }
+
+  submit(): void {
+    if (!this.canSubmit()) {
+      throw new DomainException('Order cannot be submitted')
+    }
+    this.status = OrderStatus.SUBMITTED
+    this.addDomainEvent(new OrderSubmittedEvent(this))
+  }
+
+  private canSubmit(): boolean {
+    return this.status === OrderStatus.DRAFT && this.items.length > 0
+  }
+}
+
+// Domain Event - Business facts that may trigger reactions
+class OrderSubmittedEvent extends DomainEvent {
+  constructor(public readonly order: Order) {
+    super('order.submitted', order.id)
+  }
+}
+
+// Repository Interface (Port) - Persistence abstraction
+interface OrderRepository {
+  findById(id: OrderId): Promise<Order | null>
+  findByCustomer(customerId: CustomerId): Promise<Order[]>
+  save(order: Order): Promise<void>
+}
+```
+
+## Related Skills
+- clean-architecture
+- hexagonal-architecture
+- layered-architecture
+- saga-architecture
+- backend-patterns

package/src/skills/django-patterns/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: django-patterns
+description: Django patterns covering models, ORM queries, views, class-based views, middleware, URL routing, forms, and project structure. Activate when writing or reviewing Django code.
+origin: FlowDeck
+---
+
+# Django Patterns Skill
+
+Idiomatic Django for production systems. Covers models, views, ORM patterns, and project layout.
+
+## When to Activate
+
+Activate when:
+- Writing new Django apps or services
+- Reviewing Django code for correctness and idiom
+- Designing model relationships and ORM queries
+- Building views with class-based views or function-based views
+- Configuring URL routing and middleware
+
+## Project Structure
+
+### Standard Layout
+
+```text
+manage.py
+mysite/
+    __init__.py
+    settings.py
+    urls.py
+    wsgi.py
+myapp/
+    __init__.py
+    models.py
+    views.py
+    urls.py
+    admin.py
+    apps.py
+```
+
+### Decoupled Layout (Recommended)
+
+```text
+manage.py
+myapp/
+    __init__.py
+    models.py
+    views.py
+    urls.py
+mysite/
+    __init__.py
+    settings.py
+    urls.py
+    wsgi.py
+```
+
+Import apps as top-level modules without project prefix.
+
+## Models and ORM
+
+### Basic Model Definition
+
+```python
+from django.db import models
+
+class Reporter(models.Model):
+    full_name = models.CharField(max_length=70)
+
+    def __str__(self):
+        return self.full_name
+
+class Article(models.Model):
+    pub_date = models.DateField()
+    headline = models.CharField(max_length=200)
+    content = models.TextField()
+    reporter = models.ForeignKey(Reporter, on_delete=models.CASCADE)
+
+    def __str__(self):
+        return self.headline
+```
+
+### Field Types and Options
+
+```python
+class Book(models.Model):
+    class Status(models.TextChoices):
+        DRAFT = 'draft', 'Draft'
+        PUBLISHED = 'published', 'Published'
+        ARCHIVED = 'archived', 'Archived'
+
+    title = models.CharField(max_length=200)
+    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books')
+    isbn = models.CharField(max_length=13, unique=True)
+    published_date = models.DateField()
+    price = models.DecimalField(max_digits=10, decimal_places=2)
+    status = models.CharField(max_length=10, choices=Status.choices, default=Status.DRAFT)
+    tags = models.ManyToManyField('Tag', blank=True)
+
+    class Meta:
+        ordering = ['title']
+        indexes = [
+            models.Index(fields=['title', 'author']),
+            models.Index(fields=['published_date']),
+        ]
+```
+
+### QuerySet Operations
+
+```python
+# Create
+author = Author.objects.create(name="Jane Doe", email="jane@example.com")
+book = Book.objects.create(title="Django Mastery", author=author, isbn="9781234567890")
+
+# Read with filtering
+published_books = Book.objects.filter(status=Book.Status.PUBLISHED)
+expensive_books = Book.objects.filter(price__gte=30.00)
+
+# Complex queries with Q objects
+from django.db.models import Q, F, Count, Avg
+books = Book.objects.filter(
+    Q(title__icontains='django') | Q(author__name__icontains='django')
+).exclude(status=Book.Status.ARCHIVED)
+
+# Aggregations
+author_stats = Author.objects.annotate(
+    book_count=Count('books'),
+    avg_price=Avg('books__price')
+).filter(book_count__gt=0)
+
+# Update with F expressions
+Book.objects.filter(pk=1).update(price=F('price') * 1.1)
+
+# Select related (prevents N+1)
+books_with_authors = Book.objects.select_related('author').all()
+```
+
+## Views
+
+### Class-Based Views
+
+```python
+from django.http import HttpResponse
+from django.views import View
+from django.views.generic import ListView, DetailView, CreateView
+
+class MyView(View):
+    def get(self, request, *args, **kwargs):
+        return HttpResponse("Hello, World!")
+
+# URL routing
+from django.urls import path
+urlpatterns = [
+    path("about/", MyView.as_view()),
+]
+```
+
+### Generic Class-Based Views
+
+```python
+class ArticleListView(ListView):
+    model = Article
+    template_name = "articles/list.html"
+    context_object_name = "articles"
+
+    def get_queryset(self):
+        return Article.objects.filter(status='published').select_related('author')
+
+class ArticleDetailView(DetailView):
+    model = Article
+    template_name = "articles/detail.html"
+    context_object_name = "article"
+
+class ArticleCreateView(CreateView):
+    model = Article
+    fields = ['title', 'content', 'author', 'status']
+    template_name = "articles/form.html"
+    success_url = reverse_lazy('article-list')
+```
+
+### Function-Based Views
+
+```python
+from django.http import JsonResponse
+from django.shortcuts import get_object_or_404
+
+def article_detail(request, pk):
+    article = get_object_or_404(Article, pk=pk)
+    return JsonResponse({
+        'id': article.id,
+        'title': article.title,
+        'content': article.content,
+    })
+```
+
+## URL Routing
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    path("articles/", include("articles.urls")),
+    path("about/", AboutView.as_view(), name="about"),
+]
+
+# In articles/urls.py
+from django.urls import path
+from .views import ArticleListView, ArticleDetailView
+
+urlpatterns = [
+    path("", ArticleListView.as_view(), name="article-list"),
+    path("<int:pk>/", ArticleDetailView.as_view(), name="article-detail"),
+]
+```
+
+## Middleware
+
+### Function-Based Middleware
+
+```python
+def simple_middleware(get_response):
+    def middleware(request):
+        # Code executed before view
+        response = get_response(request)
+        # Code executed after view
+        return response
+    return middleware
+```
+
+### Adding to Settings
+
+```python
+MIDDLEWARE = [
+    'django.middleware.security.SecurityMiddleware',
+    'django.contrib.sessions.middleware.SessionMiddleware',
+    'django.middleware.common.CommonMiddleware',
+    'myapp.middleware.simple_middleware',
+]
+```
+
+## Forms
+
+### Model Forms
+
+```python
+from django import forms
+from .models import Article
+
+class ArticleForm(forms.ModelForm):
+    class Meta:
+        model = Article
+        fields = ['title', 'content', 'author', 'status']
+
+    def clean_title(self):
+        title = self.cleaned_data['title']
+        if 'spam' in title.lower():
+            raise forms.ValidationError("No spam allowed")
+        return title
+```
+
+## Common Pitfalls
+
+### N+1 Query Problem
+
+```python
+# Bad: causes N+1 queries
+articles = Article.objects.all()
+for article in articles:
+    print(article.author.name)  # N additional queries
+
+# Good: use select_related or prefetch_related
+articles = Article.objects.select_related('author').all()
+for article in articles:
+    print(article.author.name)  # No additional queries
+```
+
+### Using Q Objects for Complex Queries
+
+```python
+from django.db.models import Q
+
+# OR conditions
+Book.objects.filter(Q(title__icontains='django') | Q(author__name__icontains='django'))
+
+# AND with exclusion
+Book.objects.filter(status='published').exclude(Q(title__icontains='old'))
+```
+
+### Bulk Operations
+
+```python
+# Create multiple objects efficiently
+Book.objects.bulk_create([
+    Book(title='Book 1', author=author),
+    Book(title='Book 2', author=author),
+])
+
+# Update multiple objects
+Book.objects.filter(status='archived').update(status='published')
+```
+
+## Related Skills
+
+- django-tdd
+- python-patterns
+- api-design