Schedule reports without duplicate logical runs

Application background

A customer wants a sales report every weekday at 09:00 in their local time zone. They save that preference once. Each morning, the application must turn it into one specific report run with its own progress and result.

The saved preference is the schedule. Tuesday's report is an occurrence of that schedule. Restarting the scheduler or receiving the same queue message twice must not accidentally create two Tuesday reports.

Example walkthrough

Keep schedule identity separate from run identity. Retries are attempts to finish the same run, not new scheduled occurrences.

Your assignment

Deliver: Build saved schedules, records for their individual runs and a process that starts due work. Show that a restart does not create two runs for the same occurrence.

Required behavior: POST /schedules stores a timezone-aware schedule and version. Each due occurrence has identity (schedule_id, version, scheduled_at). Pausing a schedule stops new admissions. It does not undo an external action, such as an email, that already occurred.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/job_scheduler.py

Supplied file: examples/architecture-starts/job_scheduler.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for job-scheduler. No AWS resources are created."""
import sqlite3
c=sqlite3.connect(':memory:')
c.execute('CREATE TABLE runs(schedule TEXT,version INT,due TEXT,state TEXT,PRIMARY KEY(schedule,version,due))')
for dispatcher in ('old-dispatcher','new-dispatcher'):
    changed=c.execute('INSERT OR IGNORE INTO runs VALUES (?,?,?,?)',('report-7',2,'2026-01-10T09:00:00Z','accepted')).rowcount
    print(dispatcher,'created run' if changed else 'existing run')
print(c.execute('SELECT * FROM runs').fetchall())

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

old-dispatcher created run
new-dispatcher existing run
[('report-7', 2, '2026-01-10T09:00:00Z', 'accepted')]

Set up your implementation workspace

Create work/job-scheduler/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Implement one-time scheduling

Store UTC instants and an indexed next_due field. Query bounded due ranges and atomically create the unique occurrence plus delivery intent. Advance next_due only in the same transactional decision. A missed scan must be recoverable from durable state.

2. Handle recurrence explicitly

Store IANA timezone and local recurrence separately from computed UTC occurrences. Decide how a nonexistent daylight-saving time is skipped and which ambiguous occurrence is chosen. Editing a schedule creates a version so old messages cannot silently use new parameters.

3. Partition dispatch

Bucket near-term due times and shard each bucket by stable schedule hash. Lease partitions with incrementing epochs. Workers condition checkpoint updates on that epoch. Size buckets so an hour boundary does not send all work to one hot key.

4. Define overdue policy

Choose catch-up-all, latest-only or expire for each job type. Display scheduled time, admitted time and started time. A report may tolerate delay. A reservation-expiry action must check current state even if its timer fires late.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

This design builds the scheduling index explicitly to expose dispatch ownership and occurrence identity. EventBridge Scheduler can remove substantial control-plane work for suitable workloads. It does not remove downstream idempotency or product decisions about late runs.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Change a recurring schedule without sending twice

A customer moves a daily report from New York time to London time. Two scheduler processes may still hold the old and new definitions. Without a version boundary they can each create a report for the same intended occurrence.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Choose this exercise policy: already materialized occurrences keep their UTC instant, and the edit applies only to future unmaterialized occurrences. Store timezone identifier, schedule generation and effective boundary. Serialize edits with occurrence creation. Give each occurrence a stable ID and unique business key, then dispatch it through the existing durable job path. A timezone rule change is another explicit schedule revision. EventBridge or another trigger wakes the scheduler, but the application store owns the occurrence identity.

Walk through the result. Create tomorrow's occurrence under generation 4, change timezone to generation 5, then run both schedulers. Tomorrow's existing occurrence remains unchanged and no second copy is created. Show the next newly calculated occurrence with its local time, UTC instant and generation. Document your daylight-saving gap and repeated-hour policy.

Allow a customer to move a recurring schedule between timezones. Specify whether already materialized occurrences keep their original instant. Show the state and version boundary that prevents both versions from sending the same report.