# lakshay1509/mykaarma architecture

> Architecture diagram of the GitHub repository lakshay1509/mykaarma, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lakshay1509/mykaarma
- Repository: https://github.com/lakshay1509/mykaarma

## Overview

This is a vehicle-service appointment booking and reminder service. A dealer or booking UI submits an idempotent appointment request; the API validates and books it, persisting the appointment and its 24-hour and 2-hour reminder rows together. Workers claim due rows from PostgreSQL, send notifications, and record outcomes. The README documents cancellation, rescheduling, reminder lookup, retry and deduplication guarantees, and Prometheus monitoring. Source excerpts show the booking, API, claim, and send paths; less-detailed operational capabilities are linked only where documented.

Main entry points: [`src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java`](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java) (Appointment endpoints), [`src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java`](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java) (Booking lifecycle), [`src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java`](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java) (Dispatcher workers), [`src/main/java/com/mykaarma/reminders/reminder/ReminderRepository.java`](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/ReminderRepository.java) (Reminder queue repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_booking["Booking API"]
  node_api["Appointment endpoints"]
  node_booking_request["Booking request"]
  node_appointment_response["Appointment response"]
  node_reminder_response["Reminder response"]
end

subgraph group_appointments["Appointment domain"]
  node_booking_service["Booking lifecycle"]
  node_appointment["Appointment<br/>[Appointment.java]"]
  node_dealership["Dealership<br/>[Dealership.java]"]
end

subgraph group_dispatch["Reminder delivery"]
  node_reminder["Reminder state<br/>[Reminder.java]"]
  node_reminder_type["Reminder timing<br/>[ReminderType.java]"]
  node_dispatcher["Dispatcher workers<br/>[Dispatcher.java]"]
  node_notification_payload["Notification payload"]
  node_notification_sender["Sender interface"]
  node_logging_sender["Logging sender"]
  node_send_result["Send outcome<br/>[SendResult.java]"]
end

subgraph group_persistence["PostgreSQL state"]
  node_appointment_repo["Appointment repository"]
  node_dealership_repo["Dealership lookup"]
  node_reminder_repo["Reminder queue repository"]
  node_postgres[("PostgreSQL")]
end

node_dealer(("Dealer / booking UI"))
node_prometheus["Prometheus"]

node_dealer -->|"submits requests"| node_api
node_api -->|"accepts"| node_booking_request
node_api -->|"delegates booking"| node_booking_service
node_booking_service -->|"looks up dealership"| node_dealership_repo
node_booking_service -->|"reads and saves"| node_appointment_repo
node_booking_service -->|"writes reminders"| node_reminder_repo
node_booking_service -->|"creates and updates"| node_appointment
node_booking_service -->|"creates reminder rows"| node_reminder
node_reminder -->|"gets due time"| node_reminder_type
node_appointment -->|"references"| node_dealership
node_api -->|"returns booking"| node_appointment_response
node_api -->|"loads appointment reminders"| node_reminder_repo
node_api -->|"returns reminder list"| node_reminder_response
node_dispatcher -->|"claims and settles"| node_reminder_repo
node_dispatcher -->|"builds payload"| node_notification_payload
node_dispatcher -->|"sends notification"| node_notification_sender
node_notification_sender -->|"implemented by"| node_logging_sender
node_logging_sender -->|"returns outcome"| node_send_result
node_appointment_repo -->|"persists appointments"| node_postgres
node_dealership_repo -->|"reads dealership data"| node_postgres
node_reminder_repo -->|"claims and stores queue"| node_postgres
node_prometheus -.->|"scrapes metrics"| node_dispatcher

click node_api "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java"
click node_booking_request "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/CreateAppointmentRequest.java"
click node_booking_service "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java"
click node_appointment "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/Appointment.java"
click node_dealership "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/Dealership.java"
click node_appointment_response "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentResponse.java"
click node_appointment_repo "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentRepository.java"
click node_dealership_repo "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/DealershipRepository.java"
click node_reminder "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/Reminder.java"
click node_reminder_type "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/ReminderType.java"
click node_reminder_response "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/ReminderResponse.java"
click node_reminder_repo "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/ReminderRepository.java"
click node_dispatcher "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java"
click node_notification_payload "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/NotificationPayload.java"
click node_notification_sender "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/NotificationSender.java"
click node_logging_sender "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/LoggingNotificationSender.java"
click node_send_result "https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/SendResult.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_booking_request,node_appointment_response,node_reminder_response,node_dealer toneBlue
class node_booking_service,node_appointment,node_dealership toneAmber
class node_reminder,node_reminder_type,node_dispatcher,node_notification_payload,node_notification_sender,node_logging_sender,node_send_result toneMint
class node_appointment_repo,node_dealership_repo,node_reminder_repo,node_postgres toneRose
class node_prometheus toneIndigo
```

## Components

### Booking API

- [Appointment endpoints](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java): `src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java`
- [Booking request](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/CreateAppointmentRequest.java): `src/main/java/com/mykaarma/reminders/appointment/CreateAppointmentRequest.java`
- [Appointment response](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentResponse.java): `src/main/java/com/mykaarma/reminders/appointment/AppointmentResponse.java`
- [Reminder response](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/ReminderResponse.java): `src/main/java/com/mykaarma/reminders/reminder/ReminderResponse.java`

### Appointment domain

- [Booking lifecycle](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java): `src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java`
- [Appointment](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/Appointment.java): `src/main/java/com/mykaarma/reminders/appointment/Appointment.java`
- [Dealership](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/Dealership.java): `src/main/java/com/mykaarma/reminders/appointment/Dealership.java`

### Reminder delivery

- [Reminder state](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/Reminder.java): `src/main/java/com/mykaarma/reminders/reminder/Reminder.java`
- [Reminder timing](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/ReminderType.java): `src/main/java/com/mykaarma/reminders/reminder/ReminderType.java`
- [Dispatcher workers](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java): `src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java`
- [Notification payload](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/NotificationPayload.java): `src/main/java/com/mykaarma/reminders/notification/NotificationPayload.java`
- [Sender interface](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/NotificationSender.java): `src/main/java/com/mykaarma/reminders/notification/NotificationSender.java`
- [Logging sender](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/LoggingNotificationSender.java): `src/main/java/com/mykaarma/reminders/notification/LoggingNotificationSender.java`
- [Send outcome](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/notification/SendResult.java): `src/main/java/com/mykaarma/reminders/notification/SendResult.java`

### PostgreSQL state

- [Appointment repository](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/AppointmentRepository.java): `src/main/java/com/mykaarma/reminders/appointment/AppointmentRepository.java`
- [Dealership lookup](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/appointment/DealershipRepository.java): `src/main/java/com/mykaarma/reminders/appointment/DealershipRepository.java`
- [Reminder queue repository](https://github.com/lakshay1509/mykaarma/blob/main/src/main/java/com/mykaarma/reminders/reminder/ReminderRepository.java): `src/main/java/com/mykaarma/reminders/reminder/ReminderRepository.java`
- **PostgreSQL**

### Other components

- **Dealer / booking UI**
- **Prometheus**

## Connections

- Dealer / booking UI → Appointment endpoints: submits requests (evidence: `README.md`)
- Appointment endpoints → Booking request: accepts (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java`)
- Appointment endpoints → Booking lifecycle: delegates booking (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java`)
- Booking lifecycle → Dealership lookup: looks up dealership (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java`)
- Booking lifecycle → Appointment repository: reads and saves (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java`)
- Booking lifecycle → Reminder queue repository: writes reminders (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java`)
- Booking lifecycle → Appointment: creates and updates (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java`)
- Booking lifecycle → Reminder state: creates reminder rows (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentService.java`)
- Reminder state → Reminder timing: gets due time (evidence: `src/main/java/com/mykaarma/reminders/reminder/Reminder.java`)
- Appointment → Dealership: references (evidence: `src/main/java/com/mykaarma/reminders/appointment/Appointment.java`)
- Appointment endpoints → Appointment response: returns booking (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java`)
- Appointment endpoints → Reminder queue repository: loads appointment reminders (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java`)
- Appointment endpoints → Reminder response: returns reminder list (evidence: `src/main/java/com/mykaarma/reminders/appointment/AppointmentController.java`)
- Dispatcher workers → Reminder queue repository: claims and settles (evidence: `src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java`)
- Dispatcher workers → Notification payload: builds payload (evidence: `src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java`)
- Dispatcher workers → Sender interface: sends notification (evidence: `src/main/java/com/mykaarma/reminders/reminder/Dispatcher.java`)
- Sender interface → Logging sender: implemented by (evidence: `README.md`)
- Logging sender → Send outcome: returns outcome (evidence: `src/main/java/com/mykaarma/reminders/notification/LoggingNotificationSender.java`)
- Appointment repository → PostgreSQL: persists appointments (evidence: `README.md`)
- Dealership lookup → PostgreSQL: reads dealership data (evidence: `README.md`)
- Reminder queue repository → PostgreSQL: claims and stores queue (evidence: `README.md`)
- Prometheus → Dispatcher workers: scrapes metrics
