Background Jobs — Architecture¶

Audience: Architects, tech leads, senior engineers.

Context and Purpose¶

Swisper needs to perform work outside the interactive request-response cycle: fetching emails, syncing calendars, classifying messages, sending notifications, and maintaining system state. The Background Jobs system provides a standardized framework for these tasks.

The architectural goals are:

• Uniform lifecycle — Every job follows the same init → execute → cleanup pattern with automatic correlation tracing
• External scheduling — No internal scheduler; jobs are stateless executables triggered by external orchestration
• Observability — Every job run is traceable via a unique correlation ID that flows through all logs, LLM calls, and database operations
• Isolation — Each job type runs in its own process; failures in one job do not affect others

Architecture Overview¶

graph TD
    subgraph Scheduler["External Scheduler (Cron / K8s CronJob)"]
        CRON["Schedule Trigger"]
    end

    subgraph CLI["CLI Runner (main.py)"]
        PARSE["Parse job name"]
        INIT["Initialize config + LLM providers"]
        EXEC["Execute job"]
    end

    subgraph Framework["Job Framework"]
        REG["Job Registry (JOB_MAP)"]
        BASE["BaseJob ABC"]
    end

    subgraph Jobs["Job Implementations"]
        IE["IngestEmailsJob"]
        IC["IngestCalendarEventsJob"]
        CE["ClassifyEmailsJob"]
        DB["DailyBriefingJob"]
        IEN["SendImportantEmailNotificationsJob"]
        PMP["PreMeetingPrepJob"]
        CR["CommitmentReminderJob"]
        AR["AwaitingResponseNotificationJob"]
        FD["FactDecayBatchJob"]
        RM["RedisExpirationMonitoringJob"]
        TP["ThreemaPollingJob"]
    end

    subgraph Infra["Infrastructure"]
        REDIS["Redis"]
        PG["PostgreSQL"]
        LLM["LLM Providers"]
        SIGNALS["SignalsService"]
    end

    CRON --> PARSE --> REG --> INIT --> EXEC
    EXEC --> BASE
    BASE --> Jobs
    Jobs --> REDIS & PG & LLM & SIGNALS

Component Responsibilities¶

BaseJob Lifecycle¶

class BaseJob(ABC):
    def __init__(self, job_name: str): ...

    @abstractmethod
    async def execute(self) -> dict[str, Any] | None: ...

    async def run(self) -> dict[str, Any] | None:
        # 1. Generate correlation_id = f"job-{uuid4()}"
        # 2. set_correlation_id(correlation_id)
        # 3. Log job start with job_name and correlation_id
        # 4. Record start time
        # 5. await self.execute()
        # 6. Log success with duration
        # 7. Return result
        # finally: clear_correlation_id()

All external callers use run(), never execute() directly. This guarantees that every job run has a correlation ID, timing, and error handling.

Job Registry¶

Per-Job Details¶

Data Ingestion Jobs¶

Notification Jobs¶

Maintenance Jobs¶

Correlation ID Tracing¶

Every job run generates a unique correlation ID of the form job-{uuid4()}. This ID is:

1. Set in a ContextVar at the start of BaseJob.run()
2. Automatically included in all log messages via get_correlated_logger()
3. Passed to initialize_tracking() for token usage attribution
4. Cleared in the finally block of BaseJob.run()

For multi-user jobs (email ingestion, calendar sync), a CorrelationContext is used to scope the correlation ID per user within the job run.

Key Design Decisions¶

Decision: External scheduling, stateless executables

• Chosen: Jobs are CLI executables triggered by external cron/orchestration
• Rejected: Internal scheduler (APScheduler, Celery Beat), event-driven triggers
• Rationale: Stateless executables are simpler to deploy, scale, and monitor in Kubernetes. Each job run is a fresh process with no shared state. External scheduling gives operations full control over frequency without code changes.

Decision: BaseJob ABC with correlation tracing

• Chosen: Abstract base class that handles correlation ID, logging, and timing for all jobs
• Rejected: Decorator-based approach, no base class
• Rationale: The ABC ensures uniform observability across all jobs. Every job run is traceable via its correlation ID. Developers cannot forget to set up tracing because run() handles it automatically.

Decision: LLM-powered notification content

• Chosen: Notification jobs use LLMs to generate personalized message content
• Rejected: Template-based static messages
• Rationale: LLM-generated content adapts to context (calendar events, email subjects, user preferences) and can be personalized in tone and language. Prompt templates are stored as markdown files for easy iteration.

Known Trade-offs and Debt¶