# Scheduled Synthesis Generation — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Per-theme scheduled generation + email delivery. Background scheduler checks every 60s for due schedules, generates synthesis, and emails it to up to 3 addresses.

**Architecture:** New `theme_schedules` table (1:1 with themes). Schedule CRUD via REST API. Internal `tokio::spawn` scheduler in `main.rs` (same pattern as session cleanup). Scheduler calls `run_generation_inner` directly, then `send_synthesis_email` for each recipient.

**Tech Stack:** Rust (Axum, sqlx, tokio), SolidJS

**Spec:** `docs/superpowers/specs/2026-03-27-scheduled-generation-design.md`

---

### Task 1: Migration + model + DB

**Files:**
- Create: `backend/migrations/20260327000030_create_theme_schedules.sql`
- Create: `backend/src/models/schedule.rs`
- Create: `backend/src/db/schedules.rs`
- Modify: `backend/src/models/mod.rs`, `backend/src/db/mod.rs`
- Modify: `CLAUDE.md`

- [ ] **Step 1: Create migration**

```sql
CREATE TABLE theme_schedules (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    theme_id UUID NOT NULL UNIQUE REFERENCES themes(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    enabled BOOLEAN NOT NULL DEFAULT true,
    days JSONB NOT NULL DEFAULT '[]',
    time_utc TEXT NOT NULL DEFAULT '08:00',
    emails JSONB NOT NULL DEFAULT '[]',
    last_run_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE INDEX idx_theme_schedules_enabled ON theme_schedules(enabled) WHERE enabled = true;
```

- [ ] **Step 2: Create `models/schedule.rs`**

Structs:
- `ThemeSchedule` — DB row struct (sqlx::FromRow + Serialize)
- `UpsertScheduleRequest` — { enabled, days, time_utc, emails } with validation
- `ScheduleResponse` — API response with parsed JSON arrays

Validation for `UpsertScheduleRequest`:
- `emails` max 3, each validated with basic email regex
- `days` each must be one of `mon,tue,wed,thu,fri,sat,sun`
- `time_utc` must match `HH:MM` (00-23:00-59)

- [ ] **Step 3: Create `db/schedules.rs`**

Functions:
- `get_for_theme(pool, user_id, theme_id) -> Option<ThemeSchedule>`
- `upsert(pool, user_id, theme_id, &UpsertScheduleRequest) -> ThemeSchedule`
- `delete(pool, user_id, theme_id) -> bool`
- `find_due_schedules(pool) -> Vec<ThemeSchedule>` — query for enabled schedules where:
  ```sql
  enabled = true
  AND days @> to_jsonb($1::text)   -- today's day code
  AND time_utc <= $2               -- current HH:MM
  AND (last_run_at IS NULL OR last_run_at::date < CURRENT_DATE)
  ```
- `mark_run(pool, schedule_id)` — update `last_run_at = now()`

- [ ] **Step 4: Register modules + update CLAUDE.md**

`models/mod.rs`: add `pub mod schedule;`
`db/mod.rs`: add `pub mod schedules;`
`CLAUDE.md`: change to `## Database (30 migrations)`

- [ ] **Step 5: Build and commit**

```bash
cd backend && cargo build
git add -A && git commit -m "feat: add theme_schedules table, model, and DB queries"
```

---

### Task 2: Schedule CRUD handler + routes

**Files:**
- Create: `backend/src/handlers/schedules.rs`
- Modify: `backend/src/handlers/mod.rs`
- Modify: `backend/src/router.rs`

- [ ] **Step 1: Create handler**

Three handlers following existing patterns (read `handlers/themes.rs` for style):

```rust
// GET /api/v1/themes/:id/schedule
pub async fn get_schedule(auth_user, state, Path(theme_id)) -> schedule or null

// PUT /api/v1/themes/:id/schedule
pub async fn upsert_schedule(auth_user, state, Path(theme_id), Json(body)) -> schedule
// Verify theme belongs to user before upserting

// DELETE /api/v1/themes/:id/schedule
pub async fn delete_schedule(auth_user, state, Path(theme_id)) -> 204
```

- [ ] **Step 2: Register + routes**

`handlers/mod.rs`: add `pub mod schedules;`

In `router.rs`, add after theme routes:
```rust
.route("/themes/{id}/schedule", get(handlers::schedules::get_schedule))
.route("/themes/{id}/schedule", put(handlers::schedules::upsert_schedule))
.route("/themes/{id}/schedule", delete(handlers::schedules::delete_schedule))
```

- [ ] **Step 3: Build, test, commit**

```bash
cd backend && cargo build && cargo test --lib
git add -A && git commit -m "feat: add schedule CRUD endpoints"
```

---

### Task 3: Background scheduler service

**Files:**
- Create: `backend/src/services/scheduler.rs`
- Modify: `backend/src/services/mod.rs`
- Modify: `backend/src/main.rs`

- [ ] **Step 1: Create `services/scheduler.rs`**

```rust
//! Background scheduler for automated synthesis generation.
//!
//! Checks every 60 seconds for due theme schedules and triggers
//! generation + email delivery.

use crate::app_state::AppState;
use crate::db;
use crate::services::{email, synthesis};
use std::sync::atomic::AtomicBool;
use std::sync::Arc;
use tokio::sync::watch;
use uuid::Uuid;

/// Check for due schedules and run them.
pub async fn run_scheduled_jobs(state: &AppState) {
    let due = match db::schedules::find_due_schedules(&state.pool).await {
        Ok(schedules) => schedules,
        Err(e) => {
            tracing::warn!(error = %e, "Failed to query due schedules");
            return;
        }
    };

    if due.is_empty() {
        return;
    }

    tracing::info!(count = due.len(), "Found due scheduled jobs");

    for schedule in due {
        // Skip if user has a manual generation in progress
        if state.job_store.has_active_job(schedule.user_id).is_some() {
            tracing::info!(user_id = %schedule.user_id, theme_id = %schedule.theme_id, "Skipping scheduled job — manual generation in progress");
            continue;
        }

        tracing::info!(
            schedule_id = %schedule.id,
            theme_id = %schedule.theme_id,
            user_id = %schedule.user_id,
            "Running scheduled generation"
        );

        // Run generation with a dummy progress channel
        let (tx, _rx) = watch::channel(synthesis::ProgressEvent::Progress {
            step: "init".into(),
            message: "Scheduled generation...".into(),
            percent: 0,
        });

        let job_id = Uuid::new_v4();
        let cancelled = AtomicBool::new(false);

        let result = synthesis::run_generation_inner(
            job_id,
            state,
            schedule.user_id,
            schedule.theme_id,
            &tx,
            None,  // no provider override
            &cancelled,
        )
        .await;

        match result {
            Ok(synthesis_id) => {
                tracing::info!(synthesis_id = %synthesis_id, "Scheduled generation completed");

                // Send email to all recipients
                let emails: Vec<String> = serde_json::from_value(schedule.emails.clone()).unwrap_or_default();
                if !emails.is_empty() {
                    // Load synthesis for email
                    if let Ok(Some(synth)) = db::syntheses::get_by_id(&state.pool, synthesis_id).await {
                        let sections: Vec<crate::models::synthesis::NewsSection> =
                            serde_json::from_value(synth.sections).unwrap_or_default();
                        let week = &synth.week;
                        let date = synth.created_at.format("%d %B %Y").to_string();

                        for email_addr in &emails {
                            match email::send_synthesis_email(
                                &state.http_client,
                                &state.config.resend_api_key,
                                &state.config.email_from,
                                email_addr,
                                week,
                                &date,
                                &sections,
                            )
                            .await
                            {
                                Ok(()) => tracing::info!(to = email_addr, "Scheduled email sent"),
                                Err(e) => tracing::warn!(to = email_addr, error = %e, "Failed to send scheduled email"),
                            }
                        }
                    }
                }

                // Mark as run
                db::schedules::mark_run(&state.pool, schedule.id).await.ok();
            }
            Err(e) => {
                tracing::error!(
                    schedule_id = %schedule.id,
                    error = %e,
                    "Scheduled generation failed"
                );
                // Don't mark as run — will retry next interval
            }
        }
    }
}
```

- [ ] **Step 2: Register module**

`services/mod.rs`: add `pub mod scheduler;`

- [ ] **Step 3: Spawn in main.rs**

In `main.rs`, after the session cleanup spawn and before `let app = router::build_router(...)`, add:

```rust
// Scheduled synthesis generation (check every 60 seconds)
{
    let scheduler_state = state.clone();
    tokio::spawn(async move {
        let mut interval = tokio::time::interval(std::time::Duration::from_secs(60));
        loop {
            interval.tick().await;
            crate::services::scheduler::run_scheduled_jobs(&scheduler_state).await;
        }
    });
}
```

- [ ] **Step 4: Build, test, commit**

```bash
cd backend && cargo build && cargo test --lib
git add -A && git commit -m "feat: add background scheduler for automated synthesis generation"
```

---

### Task 4: Frontend — schedule API + types + i18n

**Files:**
- Create: `frontend/src/api/schedules.ts`
- Modify: `frontend/src/types.ts`
- Modify: `frontend/src/i18n/fr.ts`

- [ ] **Step 1: Create API client**

Read existing API modules for the pattern, then create:

```typescript
export interface ScheduleResponse {
  id: string;
  theme_id: string;
  enabled: boolean;
  days: string[];
  time_utc: string;
  emails: string[];
  last_run_at: string | null;
}

export interface UpsertScheduleRequest {
  enabled: boolean;
  days: string[];
  time_utc: string;
  emails: string[];
}

export const schedulesApi = {
  get: (themeId: string) => ...,
  upsert: (themeId: string, data: UpsertScheduleRequest) => ...,
  remove: (themeId: string) => ...,
};
```

- [ ] **Step 2: Add i18n labels**

```typescript
'schedule.title': 'Planification',
'schedule.enabled': 'Planification activee',
'schedule.days': 'Jours',
'schedule.time': 'Heure (UTC)',
'schedule.emails': 'Destinataires',
'schedule.addEmail': 'Ajouter une adresse',
'schedule.maxEmails': '3 adresses maximum',
'schedule.saved': 'Planification enregistree',
'schedule.deleted': 'Planification supprimee',
'schedule.dayMon': 'L',
'schedule.dayTue': 'M',
'schedule.dayWed': 'M',
'schedule.dayThu': 'J',
'schedule.dayFri': 'V',
'schedule.daySat': 'S',
'schedule.daySun': 'D',
```

- [ ] **Step 3: TypeScript check + commit**

```bash
cd frontend && npx tsc --noEmit
git add -A && git commit -m "feat: add schedule API client and i18n labels"
```

---

### Task 5: Frontend — Schedule component in ThemeManager

**Files:**
- Create: `frontend/src/components/settings/SettingsSchedule.tsx`
- Modify: `frontend/src/pages/ThemeManager.tsx`

- [ ] **Step 1: Create SettingsSchedule component**

Props: `{ themeId: string }`

The component:
1. Loads the schedule on mount via `schedulesApi.get(themeId)`
2. Shows enable toggle, day buttons, time input, email list
3. Auto-saves on any change via `schedulesApi.upsert(themeId, data)`

Day buttons: 7 buttons in a row, each toggles a day code in the `days` array. Use the day letter labels from i18n.

Email list: up to 3 `<input type="email">` with add/remove. Validate on blur.

- [ ] **Step 2: Add to ThemeManager**

Import `SettingsSchedule` and render it inside the selected theme view, after the sources section:

```tsx
<Show when={selectedThemeId()}>
  {/* ... existing content settings + sources ... */}
  <SettingsSchedule themeId={selectedThemeId()!} />
</Show>
```

- [ ] **Step 3: TypeScript check + commit**

```bash
cd frontend && npx tsc --noEmit
git add -A && git commit -m "feat: add schedule UI to theme management page"
```

---

### Task 6: Integration tests + E2E

**Files:**
- Create: `backend/tests/api_schedules_test.rs`
- Modify: `e2e/tests/themes.spec.ts`

- [ ] **Step 1: Create integration tests**

```rust
// Tests:
// - get_schedule_returns_null_when_none
// - upsert_schedule_creates_schedule
// - upsert_schedule_updates_existing
// - upsert_schedule_invalid_emails_returns_422
// - upsert_schedule_invalid_days_returns_422
// - upsert_schedule_too_many_emails_returns_422
// - delete_schedule_returns_204
// - schedule_requires_auth
// - schedule_requires_theme_ownership
```

Each test creates a user + theme, then operates on the schedule endpoint.

- [ ] **Step 2: Add E2E test**

In `e2e/tests/themes.spec.ts`, add after the existing CRUD test:

```typescript
// Create schedule via API
const schedResp = await page.evaluate(async (tid: string) => {
    const resp = await fetch(`/api/v1/themes/${tid}/schedule`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json', 'X-Requested-With': 'XMLHttpRequest' },
        credentials: 'same-origin',
        body: JSON.stringify({
            enabled: true,
            days: ['mon', 'fri'],
            time_utc: '09:00',
            emails: ['test@example.com'],
        }),
    });
    return { status: resp.status, data: await resp.json() };
}, themeId);
expect(schedResp.status).toBe(200);
expect(schedResp.data.days).toEqual(['mon', 'fri']);
```

- [ ] **Step 3: Build + commit**

```bash
cd backend && cargo build --tests
git add -A && git commit -m "test: add schedule CRUD integration tests and E2E"
```