Tag: system design

JIRA Worklogs Bot: A System Design Document for Simplifying Time Tracking

January 30, 2026

Original version was published in October 2025, updated: January 2026

This is a system design document for a Microsoft Teams bot that replaces JIRA’s clunky worklog UI with a single-view Adaptive Card interface.

JIRA Worklogs Bot: System Design Document

What This Document Covers

This is a complete system design for a Teams bot that solves the weekly pain of JIRA time reporting:

  • Problem analysis and design goals
  • Microsoft Teams Adaptive Card interface design
  • Spring Boot 3 + AWS Lambda backend architecture
  • Data flow and API contracts
  • Load simulation and performance SLOs
  • Production readiness checklist and evolution roadmap

Estimated reading time: 20-25 minutes

Who This Is For

  • Engineers frustrated with JIRA’s worklog UI
  • Teams developers building Adaptive Card integrations
  • Backend engineers designing serverless Java applications
  • System designers evaluating AWS Lambda for low-traffic, bursty workloads
  • Anyone interested in load analysis for realistic traffic patterns

The document includes the actual Adaptive Card JSON structure, sequence diagrams, data models, and a mathematical load simulation proving that a single Lambda function handles the Friday afternoon spike comfortably.

Questions or improvements? Open an issue on the repo or e-mail me.

Exploring UX Tradeoffs

June 20, 2025

A bug fix this week opened up bigger conversations about UX tradeoffs, first principles, and system design.

What started as a fix turned into 3 key milestones — each one clarifying what matters most in the product.

The bug was around state being lost in our front-end app. The fix was straightforward – re-fetch the data from the API.

1. Data may not be available anymore.
The API is returning JSON blobs from a model, being produced every minute. Refetching might mean that the data is gone.

– If we cache it, the data may be stale.
– One first principle: data must be real-time and useful.

We considered redirecting the user back to the landing page to restart the flow.

2. Not great UX?
– Redirecting users without explanation isn’t ideal.
UX and I talked about adding more copy about what happened and giving context.
– We settled on clear, simple copy to keep the UI clear.

3. Could users miss out on data?
UX was front-of-mind at this point, I wondered if a user was missing out on data?

– We debated changing the model or storing the data differently.
– We could flatten the data and store it sequentially.
– But that would impact internal calculations and they were vital.

We decided to keep the existing data architecture.

Lessons learned:
– Tradeoffs deserve time. Rushing decisions often means missing hidden costs.
– Technical choices ripple into UX and product – talk early, not under pressure.
– First principles matter. They keep decisions honest.

If you’re designing flows like this, I’d love to hear what worked for you.

Verified by ExactMetrics