Hephaestus

Good evening! Yes, I'm here — Hephaestus, at your service.

I'm your Backend Jobs/ETL/Automation Advisor. I help you build data pipelines, scheduled jobs, Spring Integration flows, and any backend automation you need.

What's on your mind tonight?

I can see Athena's PRD — billing-portal-prd.org in her artifacts folder — solid work. She defined the data model (Customer, User, Bill), the user stories, and the ReportBurster integration.

You're right — the PRD covers bill generation and initial delivery, but there's no automated follow-up when a bill goes unpaid. That's classic backend scheduling territory, and exactly what I do.

Let's design the reminder flow together. Where would you like to start?

Great instinct — framing the problem before coding saves time. Here's what businesses typically do in the wild:

Timing

• First reminder: 1 day after due date
• Second reminder: 7 days overdue
• Third/final reminder: 14 days overdue

Why 3 reminders?

Industry standard. Enough to prompt action without spamming. After 3 unanswered reminders, most businesses escalate to a different process (collections, account suspension, phone call).

Escalation

The tone should progress:

1. 1. Friendly — "just in case you missed it"
2. 2. Firm — "this is now overdue, please prioritize"
3. 3. Final notice — "action required within 48 hours"

Optional: Pre-due reminder

Some businesses send a courtesy reminder 3 days before the due date. Good UX, reduces overdue bills by 15-20%. Worth considering for v2.

Late fees

Common but not required for v1. If you add them later, the reminder emails just include an extra line.

Want me to draft the actual email wording for each level?

Here's a three-level approach. Every email includes: bill number, amount, due date, and a direct payment link.

Reminder 1 — Friendly (Day 1)

Subject: Friendly reminder — Bill #[number] is due

Body: "Hi [customer name], just a quick reminder that your bill #[number] for $[amount] was due on [date]. If you've already paid, please disregard this email. Otherwise, you can pay securely here: [payment link]"

Reminder 2 — Firm (Day 7)

Subject: Action needed — Bill #[number] is 7 days overdue

Body: "Dear [customer name], your bill #[number] for $[amount] is now 7 days past due (original due date: [date]). Please prioritize payment to keep your account in good standing. Pay now: [payment link]"

Reminder 3 — Final Notice (Day 14)

Subject: Final notice — Bill #[number] requires immediate attention

Body: "Dear [customer name], this is a final reminder that bill #[number] for $[amount] is 14 days overdue. Please settle this within 48 hours to avoid service disruption. Pay now: [payment link]. If you're experiencing difficulties, please contact us."

Key principles:

• Professional, never threatening
• Always include the payment link — make it easy to act
• The goal is to get paid, not to alienate customers
• Final notice mentions consequences but offers a way out ("contact us")

For this use case? @Scheduled is the right call. Here's my reasoning:

What we need:

• One daily job at 9:00 AM
• Find overdue bills with reminderCount < 3
• Send the right email template based on days overdue
• Update the bill record

@Scheduled gives us:

• Zero additional dependencies (already in Spring Boot)
• Simple cron expression: @Scheduled(cron = '0 0 9 * * *')
• Runs in the application process — no external scheduler to manage

Quartz would give us:

• Persistent job store (survives restarts — but @Scheduled reruns on startup anyway)
• Distributed execution (not needed — we run one instance)
• Dynamic job creation (not needed — we have one fixed job)
• Complexity: JobDetail, Trigger, Scheduler, database tables

My recommendation:

Start with @Scheduled. It's 15 lines of code vs. 150+ for Quartz. If you ever need dynamic scheduling or clustering, we upgrade then. Don't over-engineer.

The architecture is simple:

1. 1. ReminderScheduler (@Scheduled, daily 9 AM) →
2. 2. OverdueBillDetector (finds overdue bills) →
3. 3. ReminderService (picks template, sends email, updates bill)

Three small classes. Shall we create the task file?

Here's the task file — I'll save it as billing-portal-due-bills-reminders-tasks.org in my artifacts folder. Tasks are ordered by dependency — each one builds on the previous and delivers real value:

8 tasks. Pragmatic, ordered, each one moves us forward. Ready to start?

That's exactly how I operate — mentored pair-development. You're in the driver's seat, I navigate.

Here's the rhythm:

1. 1. I give you the task + code snippet + exact file path
2. 2. You paste it in
3. 3. You tell me "done" or "I have a question"
4. 4. We move to the next task

No detours, no over-engineering. We ship a working reminder system today.

One thing before we touch any code. Let's make a backup:

That gives us a clean reference of the original code in case we break something. We keep working inside the original — it's already wired into Docker Compose, the UI can build and start/stop it, everything's connected.

Also — my approach while we develop: we only add new code. Don't touch or delete existing classes, even if they look like stuff we don't need. They're useful as working examples while we build — you might need to reference how they handle services, injection, or configuration.

Once everything works and we've tested it, we spend 5 minutes at the end to clean up inherited code we don't need. Sound good?

Task 1 — Create the domain entities.

Two classes. First, Customer — it maps to the existing Northwind Customers table so the reminder system knows where to send emails. Create src/main/groovy/com/flowkraft/bkend/domain/Customer.groovy:

Now the Bill entity — based on Athena's PRD, plus the reminder tracking fields we discussed. Create src/main/groovy/com/flowkraft/bkend/domain/Bill.groovy:

Task 2 — Email templates. Create this folder: src/main/resources/templates/reminders/

File 1 — friendly.html:

File 2 — firm.html:

File 3 — final-notice.html:

Good catch. Since we're using GStringTemplateEngine, ${paymentUrl} works directly — it binds from the model map you pass in. No escaping needed. The key is that you'll pass a Map like [customerName: bill.customer.name, billNumber: bill.billNumber, ...] when rendering the template.

Task 3 — Config properties class + application.yml.

Create src/main/groovy/com/flowkraft/bkend/reminders/ReminderConfigProperties.groovy:

Now add this to application.yml:

Tasks 4 and 5 together — they're tightly coupled and both small.

First, create src/main/groovy/com/flowkraft/bkend/reminders/OverdueBillDetector.groovy:

Now the core logic — src/main/groovy/com/flowkraft/bkend/reminders/ReminderService.groovy:

Check if there's an existing service — grep for "JavaMailSender" or "MailService" in the project. If one exists, reuse it. If not, inject JavaMailSender directly — it's already auto-configured by Spring Boot when you have spring-boot-starter-mail on the classpath.

Task 6 — the scheduler. This ties everything together.

Create src/main/groovy/com/flowkraft/bkend/reminders/ReminderScheduler.groovy:

Also — make sure your main application class has @EnableScheduling:

That's the beauty of @Scheduled. All the logic lives in the services, the scheduler just orchestrates. Clean separation.

Task 7 — config is already done (we did it in Task 3). So straight to Task 8 — smoke test.

Open your database console or create a quick script. Insert a test bill with a due date 2 days ago:

Now either wait for the 9 AM cron or trigger it manually. For testing, temporarily change the cron to run every minute:

Start the app and watch the logs.

Ship it first, polish later. The templates are just HTML files — you or a designer can refine them anytime without touching any Java/Groovy code.

Check the database — bill.reminderCount should be 1 now, and lastReminderDate should be today.

Change the cron back to '0 0 9 * * *' before you forget.

All tasks complete. The whole reminder system is maybe 200 lines of new code across 6 files. Here's what you built today:

Daily at 9:00 AM:

ReminderScheduler → OverdueBillDetector (finds unpaid bills past due) → ReminderService (picks template by escalation level, sends email, updates tracking)

3-level escalation: friendly (day 1) → firm (day 7) → final notice (day 14)

Everything configurable: change thresholds, timing, max reminders, or from-address in application.yml — zero code changes.

Next time you need a 4th reminder level or want to add the pre-due courtesy email, it's just a new template + a config change.

Good call — that's Hermes' domain. He can query reminderCount and lastReminderDate directly from the Bill entity you just updated. Have a good evening!

Right. The project has sample classes we're not using now that our own code is in place:

• SampleJob.groovy (we have our own ReminderScheduler)
• SampleService.groovy (we have our own services)
• SampleController.groovy (no web endpoints needed for this flow)

Keep anything related to Spring Boot configuration, mail setup, or database — that's infrastructure we're using.

Good instinct. Let's audit the project. Here's every file outside our new billing code, categorized:

DELETE — not needed:

• HELP.md — auto-generated Spring Boot docs, not part of our app

REVIEW & UPDATE:

• application.properties — has the original SQLite + Liquibase config. Our new application.yml adds the reminder settings. Spring Boot loads both — verify the datasource URL, Liquibase enabled/disabled, and server port are consistent between the two files.
• application-prod.properties — production overrides. Update for the billing reminder deployment: SMTP server, from-address, cron schedule for production.
• db/migration/changelog.groovy — Liquibase migration. If you're using JPA auto-DDL for development (spring.jpa.hibernate.ddl-auto=update), this file isn't active. Either update it with the Customer/Bill table definitions for production, or remove it if you're managing schema through JPA.
• BkendApplication.groovy — verify it has @EnableScheduling. Without it, the @Scheduled cron won't fire.
• BkendApplicationTests.groovy — basic context load test. Make sure it still passes with the new beans. Run ./mvnw test.

KEEP — all good:

• pom.xml, Dockerfile, docker-compose.yml — infrastructure
• .gitignore, .gitattributes, .mvn/, mvnw, mvnw.cmd — tooling
• All files under domain/, reminders/, templates/ — our billing code

That's a production-ready project. Here's the final file tree:

Slim, focused, no dead code. Every file has a purpose.