Design That Fits the Codebase

gemini "@models.py @database.py @spec/recurring-tasks.json
Design a RecurringTask SQLAlchemy model that fits the existing patterns
in models.py. Requirements from the JSON spec:
- Fields: task_id (FK), schedule_type, interval_value, next_run_at, is_active, created_at
- Relationship: one-to-one with Task (each task has at most one recurrence)

Match these patterns from models.py:
- Use Column(DateTime(timezone=True), server_default=func.now()) for timestamps
- Use relationship() with back_populates
- Follow the same import structure
- Add the relationship to the existing Task class too

Output only the Python code for the new model plus the modification
to the Task class. No explanations."

# ── Add to models.py ──────────────────────────────────────────

class RecurringTask(Base):
    __tablename__ = "recurring_tasks"

    id = Column(Integer, primary_key=True, index=True)
    task_id = Column(Integer, ForeignKey("tasks.id"), unique=True, nullable=False)
    schedule_type = Column(String, nullable=False)  # daily | weekly | monthly
    interval_value = Column(Integer, nullable=True)  # e.g. every N days
    next_run_at = Column(DateTime(timezone=True), nullable=False)
    is_active = Column(Boolean, default=True)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

    task = relationship("Task", back_populates="recurrence")


# ── Modification to existing Task class ──────────────────────
# Add this line inside class Task, after the 'tags' relationship:
recurrence = relationship(
    "RecurringTask",
    back_populates="task",
    uselist=False,      # one-to-one: a task has at most one recurrence
    cascade="all, delete-orphan",
)

gemini "@models.py Generate a Mermaid erDiagram showing all tables in
TaskFlow including the new RecurringTask table.
Show: primary keys, foreign keys, field types, and relationships.
Use Mermaid erDiagram syntax. Output only the Mermaid code block." \
  > docs/er-diagram.md

```mermaid
erDiagram
    users {
        int id PK
        string email
        string username
        string hashed_password
        bool is_active
        datetime created_at
    }
    tasks {
        int id PK
        string title
        string description
        bool completed
        string priority
        datetime due_date
        datetime created_at
        datetime updated_at
        int owner_id FK
    }
    tags {
        int id PK
        string name
        string color
    }
    task_tags {
        int task_id FK
        int tag_id FK
    }
    recurring_tasks {
        int id PK
        int task_id FK
        string schedule_type
        int interval_value
        datetime next_run_at
        bool is_active
        datetime created_at
    }
    users ||--o{ tasks : "owns"
    tasks }o--o{ tags : "has"
    task_tags }o--|| tasks : ""
    task_tags }o--|| tags : ""
    tasks ||--o| recurring_tasks : "has recurrence"
```

gemini "@routers/tasks.py @auth.py @models.py
Generate a Mermaid sequence diagram showing the complete flow for:
PATCH /tasks/{id} where completed=True on a task with an active recurrence.

Actors: Client, FastAPI, auth.py, tasks.py router, Database, Scheduler
Show: JWT validation, task update, recurrence check, spawn logic.
Use Mermaid sequenceDiagram syntax."

gemini "@routers/tasks.py @schemas.py @spec/recurring-tasks.json
Draft the OpenAPI 3.1 YAML for these three new endpoints:
  POST   /tasks/{task_id}/recurrence
  GET    /tasks/{task_id}/recurrence
  DELETE /tasks/{task_id}/recurrence

Follow the patterns in the existing TaskFlow routes:
- All endpoints require Bearer auth (JWT)
- Error responses use {detail: string} format (FastAPI default)
- 404 when task_id doesn't exist or doesn't belong to the current user

Output valid YAML only. Use $ref for reusable schemas." \
  > docs/recurrence-api.yaml

openapi: "3.1.0"
info:
  title: TaskFlow Recurrence API
  version: "1.0"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    RecurringTaskCreate:
      type: object
      required: [schedule_type]
      properties:
        schedule_type:
          type: string
          enum: [daily, weekly, monthly]
          description: "How often the task recurs"
        interval_value:
          type: integer
          nullable: true
          description: "e.g. every 2 weeks — set schedule_type=weekly, interval_value=2"

    RecurringTask:
      type: object
      properties:
        id:          { type: integer }
        task_id:     { type: integer }
        schedule_type: { type: string, enum: [daily, weekly, monthly] }
        interval_value: { type: integer, nullable: true }
        next_run_at: { type: string, format: date-time }
        is_active:   { type: boolean }
        created_at:  { type: string, format: date-time }

    HTTPError:
      type: object
      properties:
        detail: { type: string }

paths:
  /tasks/{task_id}/recurrence:
    post:
      summary: Set a recurrence schedule on a task
      security: [{ BearerAuth: [] }]
      parameters:
        - name: task_id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/RecurringTaskCreate' }
      responses:
        "201":
          description: Recurrence created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RecurringTask' }
        "404":
          description: Task not found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HTTPError' }
        "401":
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HTTPError' }

    get:
      summary: Get recurrence settings for a task
      security: [{ BearerAuth: [] }]
      parameters:
        - name: task_id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: Recurrence settings
          content:
            application/json:
              schema: { $ref: '#/components/schemas/RecurringTask' }
        "404":
          description: Task not found or no recurrence set

    delete:
      summary: Remove recurrence from a task
      security: [{ BearerAuth: [] }]
      parameters:
        - name: task_id
          in: path
          required: true
          schema: { type: integer }
      responses:
        "204":
          description: Recurrence deleted
        "404":
          description: Task or recurrence not found

gemini "@models.py @database.py
Design the Alembic migration script to add the recurring_tasks table.
The table needs these columns (match the RecurringTask model patterns):
- id, task_id (FK + UNIQUE), schedule_type, interval_value, next_run_at, is_active, created_at

Requirements:
- The upgrade() function adds the table and FK constraint
- The downgrade() function drops the table cleanly
- Use op.create_table() and op.drop_table() (Alembic style)
- Handle the CASCADE: deleting a task should delete its recurrence

Output only the migration file content."

"""add recurring_tasks table

Revision ID: 001_recurring
Revises:
Create Date: 2026-06-10
"""
from alembic import op
import sqlalchemy as sa

revision = '001_recurring'
down_revision = None
branch_labels = None
depends_on = None


def upgrade() -> None:
    op.create_table(
        'recurring_tasks',
        sa.Column('id', sa.Integer(), primary_key=True, index=True),
        sa.Column('task_id', sa.Integer(),
                  sa.ForeignKey('tasks.id', ondelete='CASCADE'),
                  unique=True, nullable=False),
        sa.Column('schedule_type', sa.String(), nullable=False),
        sa.Column('interval_value', sa.Integer(), nullable=True),
        sa.Column('next_run_at', sa.DateTime(timezone=True), nullable=False),
        sa.Column('is_active', sa.Boolean(), server_default='1'),
        sa.Column('created_at', sa.DateTime(timezone=True),
                  server_default=sa.text('CURRENT_TIMESTAMP')),
    )
    op.create_index('ix_recurring_tasks_task_id', 'recurring_tasks', ['task_id'])


def downgrade() -> None:
    op.drop_index('ix_recurring_tasks_task_id', table_name='recurring_tasks')
    op.drop_table('recurring_tasks')

gemini "@models.py @routers/tasks.py @spec/recurring-tasks.json
Write an Architecture Decision Record (ADR) for the following decision:

Decision: How should recurring task spawning be triggered?
Option A: Cron expression (server-side background scheduler polls every minute)
Option B: Interval-based (client calls POST /tasks/{id}/spawn on a schedule)
Option C: Event-driven (SQLAlchemy event listener on Task.completed change)

For each option: list pros, cons, and fit with TaskFlow's current architecture.
Include: Context, Decision Drivers, Considered Options, Decision Outcome,
Consequences (positive and negative).
Use Michael Nygard's ADR template format." > docs/adr-001-recurrence-trigger.md

# ADR-001: Recurring Task Spawn Trigger Mechanism

## Status
Accepted

## Context
TaskFlow (FastAPI + SQLite) needs to auto-spawn new tasks when a recurring
task is completed. Three mechanisms were considered. The system currently
has no background workers, no message queue, and no event system.

## Decision Drivers
- Simplicity: TaskFlow is a single-server app; no Celery or Redis
- Reliability: tasks must spawn even if the server restarts
- Consistency with existing architecture

## Considered Options
**Option A: Background Scheduler (APScheduler)**
- Pros: server-side control, survives client disconnects, predictable timing
- Cons: adds dependency, must handle scheduler restart on server boot
- Fit: poor for serverless but good for always-on uvicorn deployment

**Option B: Client-triggered endpoint**
- Pros: zero new infrastructure, simplest implementation
- Cons: relies on clients to call reliably — breaks if client is offline
- Fit: bad for a task manager (tasks should recur even if user is inactive)

**Option C: SQLAlchemy event listener on Task.completed**
- Pros: automatic, no polling, fires synchronously on task update
- Cons: synchronous spawn blocks the PATCH /tasks/{id} response;
         tested in tasks.py but not in scheduler tests
- Fit: viable but mixes spawning logic with the update handler

## Decision Outcome
**Chosen: Option A — APScheduler background scheduler**

Reasoning: TaskFlow runs as a persistent uvicorn process. A scheduler
polling every 60 seconds is invisible to users, survives client disconnects,
and doesn't block the PATCH /tasks/{id} response. The added complexity
(one new dependency, scheduler startup in main.py) is justified by
reliability requirements from FR-3 ("within 60 seconds").

## Positive Consequences
- Recurring tasks spawn reliably regardless of client activity
- PATCH /tasks/{id} response time is unaffected

## Negative Consequences
- APScheduler must be added to requirements.txt
- Tests must mock the scheduler or use a test-only trigger endpoint
- If the server process restarts, the scheduler must re-initialize
  (mitigation: store next_run_at in the DB, not memory)

gemini "@GEMINI.md @main.py @routers/ @models.py
Generate a C4 model for TaskFlow at the Context and Container levels.
Use Mermaid C4Context and C4Container diagram syntax.

Context level: who are the users, what external systems exist?
Container level: what processes run (FastAPI app, SQLite DB, Scheduler)?
  Show: technology labels, relationships, data flows.

After the Mermaid code, add a 3-sentence plain-English summary
of TaskFlow's architecture for a new team member." > docs/architecture-c4.md