DEV Community: Joao Marcos Costa Salles

Understanding the Core Concepts of an SQS Consumer

Joao Marcos Costa Salles — Wed, 12 Aug 2026 16:38:09 +0000

Introduction

Queues look boring from the outside: push a message in, pop a message out. Almost none of the interesting behavior is in those two calls — it's in the gap between them, in the third
call most tutorials skip: delete. SQS never removes a message just because you received it, and that one design choice is the root of everything a consumer has to get right: retries, duplicates, dead-letter queues, backoff, parallel throughput.
Get the delete contract wrong and every one of those becomes a production incident instead of an expected case you coded for.

Mental Model for Consumer

The flow for a SQS consumer can be categorized into 3 Stage: Receive, Process, and Delete:

Receive: Query a message from the Queue and turn it invisible for other consumes
Process: Work done by the our application
Delete: ACK sent to Queue in order to remove the message from the SQS

This steps show the whole flow, if the process crashes before Delete, the message will be visible again, this give us retries, but introduces the possibility of duplication, so we must have idempotent.

Standard SQS works with the idea of At-least-once delivery, duplication are normal, and with Best-effort ordering.

A brief on FIFO queues, it sets to exactly-once delivery within 5 minutes dedup window. Which decreases the throughput which goes to 300 msg/s or 3k with batching, and the messages needs to carry a MessageGroupId, Standard queues have no effectively unlimited throughput. FIFO matter only when out of order processing is genuinely incorrect, and keep and mind that exactly once is for delivery and not processing, so it still necessary a idempotency. Because the same message outside the 5 minutes window, the same message but with different MessageGroupId, or a redrive can cause the duplication.

1. Visibility timeout — the foundation everything rests on

When a consumer receives a message, SQS starts a visibility timeout: a window during which that message is hidden from every other ReceiveMessage call. The message is "in flight."
Two things can happen:

You delete it before the window expires → gone for good, usually done on actively on success.
The window expires first (you crashed, hung, or were too slow) → the message becomes visible again and is redelivered.

This single mechanic is the engine behind retries, DLQs, and duplicate delivery. Understand it and the rest is bookkeeping.

Sizing the timeout

The visibility timeout must comfortably exceed the worst-case time to process a full batch, because a batch is received under a single shared window, the timeout is set at the SQS itself, through terraform or aws console. Rule of thumb:

visibility_timeout  >  P99(per-message work) × messages_in_flight_per_consumer  +  margin

The default is 30s, and the maximum it can be 12 hours. Too short and you get spurious redeliveries, the message reappears while you're still working on it, a second consumer picks it up, and now you're processing it twice concurrently.
Too long and a genuinely crashed message sits invisible for ages before anyone retries it, inflating latency and hiding failures.

The in-flight ceiling

There is a limit cap on in-flight messages (received but not yet deleted) at ~120,000, if your consumers are slow and your timeout is long, you can hit this ceiling and and ReceiveMessage(call to another batch of messages) starts returning empty even though the queue is backed up. FIFO's ceiling is far lower (~20,000), another reason Standard scales better.

Extending the window mid-flight

For long or variable jobs or backoff strategies, we don't need to set one giant timeout. Start modest and call ChangeMessageVisibility to extend the lease as you make progress, a heartbeat. This keeps a crashed consumer's messages returning quickly while still protecting long-running healthy work.

Kotlin example

private fun extendVisibility(message: Message, timeoutSeconds: Int) {
    try {
        sqsClient.changeMessageVisibility(
            ChangeMessageVisibilityRequest.builder()
                .queueUrl(queueUrl)
                .receiptHandle(message.receiptHandle())
                .visibilityTimeout(timeoutSeconds)
                .build(),
        )
    } catch (e: Exception) {
        log.warn("Failed to extend visibility for message {}", message.messageId(), e)
    }
}

private fun process(message: Message) {
    val heartbeat = CoroutineScope(Dispatchers.IO).launch {
        while (isActive) {
            delay(20_000)  // renew before a 30s timeout expires
            runCatching { extendVisibility(message, 30) }
        }
    }
    try {
        handler.handle(message.body())
        deleteMessage(message)
    } catch (e: JacksonException) {
        deleteMessage(message)
    } catch (e: Exception) {
        log.error(...)
    } finally {
        heartbeat.cancel()
    }
}

Don't worry about all the code, pay attention on the function extendVisibility, the async scope that create a delay and call the extention every 20 seconds, and the finally that cancels the assync scope.

Basic flow on handling messages

When processing a message, map scenarios and decide to delete the message, or ignore it to active the redrive. Usually delete message are triggered on success, but we can add it on some erros, like Malformed messages, it is a conscious call because it will prevent debug of this message, but other exception we may choose to ignore the delete to send the message to the DLQ

Kotlin example

private fun process(message: Message) {
    try {
        handler.handle(message.body())
        deleteMessage(message)          // success → consume
    } catch (e: JacksonException) {
        // poison: can never succeed → drop it (see §3, §7)
        log.error("Malformed message {}; deleting it as unprocessable", message.messageId(), e)
        deleteMessage(message)
    } catch (e: Exception) {
        // transient/unknown → DO NOTHING; let it reappear for redrive
        log.error("Failed to handle message {}; leaving it for redrive", message.messageId(), e)
    }
}

Capping retries: `maxReceiveCount`

Infinite retries are a bug: a message that always fails will loop forever, burning throughput and log volume. The cap is the redrive policy's maxReceiveCount, after a message has been received that many times without being deleted, SQS moves it to a
Dead-Letter Queue. This is the bridge from "retry" to "give up safely."

3. Dead-Letter Queues "where poison goes to be examined"

A Dead-Letter Queue is an ordinary SQS queue that a source queue points at via its redrive policy. Once a message on queue has been received 5 times, default value, without deletion, SQS
delivers it to Dead Letter Queue instead.
The DLQ has no special powers, its value is isolation: failing messages stop clogging the main queue, and you get a quarantined place to inspect, alarm on, and eventually redrive them back once the bug is fixed, it can be done by AWS console, usually it is done manually by console or terminal.

What belongs in a DLQ

Transient failures that exhausted retries: the dependency was down longer than maxReceiveCount × visibility_timeout. These are candidates for redrive-back later.
Genuinely un-processable messages you couldn't detect up front: a schema you didn't anticipate, a referenced entity that never materializes.

DLQ with messages is a incident

It is neccessary to put alarm on the DLQ's
ApproximateNumberOfMessagesVisible > 0 (CloudWatch). A silent DLQ is a DLQ nobody reads, which defeats the point. Also set the DLQ's own retention to the maximum (14 days) so you have time to react before evidence expires.

3. Parallel reading — long polling and batch fan-out

Throughput on a Standard queue comes from two multipliers: reading efficiently and processing concurrently.

Long polling vs. short polling

ReceiveMessage with WaitTimeSeconds = 0 is short polling: it samples a subset of the queue's servers and often returns empty even when messages exist, so you burn API calls spinning. Setting WaitTimeSeconds to 1–20 turns on long polling: the call waits up to that long for a message to appear, queries all servers, and returns as soon as anything's available. It cuts empty receives, reduces cost, and lowers latency. opt for long polling.

Batch receive

One ReceiveMessage call returns up to n messages set on (MaxNumberOfMessages). Batching amortizes the round-trip and is the unit of parallelism,receiving n messages doesn't help if you process them one at a time, you must worker/async/parallel the messages

The shared-visibility-window caveat

Every message in a batch is received under one visibility timeout that started at the same instant. If one confirmation blocks for 25 seconds while the others finish in 200ms, all ten are racing the same clock — but the clock only governs messages still in flight. The fast ones are deleted (permanently, off the
queue) well before it expires, so the clock expiring is a no-op for them — deletion isn't "undone" by a later timeout. Only the still-in-flight straggler is at risk: if its own handle() + deleteMessage() don't complete before the shared clock runs out, it becomes visible again and can be redelivered — possibly duplicating work if it finishes and deletes just after.
If per-message latency is highly variable, either shrink maxMessages, or extend visibility per-message with ChangeMessageVisibility.

Scaling out

Beyond one instance's batch fan-out, horizontal scaling is free: run N worker instances all long-polling the same queue. SQS's visibility mechanic guarantees a given message goes to one
consumer at a time, so instances don't coordinate. Batch size × concurrency × instance count is your throughput dial. (This is precisely where Standard's near-unlimited throughput beats FIFO.)

4. Idempotency, the non-negotiable consequence of at-least-once

Because delivery is at-least-once, your handler will be invoked more than once for the same logical message. Be after a visibility-timeout lapse, a redrive, a producer retry, or a
consumer crash between process and delete. An idempotent handler makes every one of those redeliveries a no-op. This is not optional hardening; it's the price of using a Standard queue correctly.

Usual Strategies, roughly in order of preference

Conditional state transition (best when you have state anyway).: Guard the write so it only fires from the expected prior state,re-delivery finds the state already advanced and does nothing.
Natural idempotency key.: Use a business identifier already in the payload as the dedupkey, no separate bookkeeping.
Dedup table / processed-ID set.: Record each processed message/event ID; skip on repeat. Necessary when the operation has no natural guarding state (e.g. "send an email").

Conclusion

Everything above collapses back into the three-word model from the preface: receive → process → delete. Every mechanism this guide covered — retries, DLQs, backoff, parallel fan-out, idempotency — exists only because delete is explicit and the gap between receive and delete is where the magic happens.

Passwords are not necessary, a Oauth/OIDC approach

Joao Marcos Costa Salles — Tue, 30 Jun 2026 21:19:57 +0000

Intro

It is possible to skip the burden of password management, security, encryption and password rotations.
When using OAuth 2.0 with OIDC (OpenID Connect), the user can log in with third-party accounts like
Google, GitHub, X and others — an easier way to sign in.

In this document, I will explain an approach using OAuth 2.0 with a React frontend and a Kotlin Spring Boot
backend to validate the third-party credentials and generate our own.

The flow at a glance

sequenceDiagram
  Frontend->>Frontend: loads script and initialize with CLIENT_ID
  Frontend->>+Google Identity Services: modal login
  Google Identity Services-->>Frontend: credentials

  Frontend->>+Our API Authentication Service: credentials
  Our API Authentication Service->>+Google Identity Services: validate credentials
  Google Identity Services-->>-Our API Authentication Service: confirmation
  Our API Authentication Service-->>-Frontend: ours generated tokens

OAuth 2.0

OAuth 2.0 is an authorization framework: it lets a user grant an application access to a resource without sharing a password with that application. On its own OAuth 2.0 says nothing about "who the user is", that is OpenID Connect (OIDC), a thin identity layer
on top of OAuth 2.0 that adds the ID token: a signed JWT asserting an authenticated identity (email, subject, issuer, audience, expiry).
Google Identity Services implements OIDC, so the "credential" the browser receives is an OIDC ID token. We use it purely as
proof of identity, then mint our own tokens for authorization inside our API.

OpenID Connect

OpenID Connect (OIDC) is a thin authentication layer standardized on top of OAuth 2.0. Where OAuth 2.0 only answers "is this app allowed to access something?", OIDC answers "who
is this user, and has the provider authenticated them?" It does this by adding the ID token — a JWT, signed by the identity provider, whose standard claims describe the authenticated user: sub (a stable user id), iss (who issued it), aud (which app it was issued for), exp/iat (validity window), and identity claims like email and email_verified.
OIDC also standardizes discovery (a /.well-known/openid-configuration document) and a JWKS endpoint publishing the provider's public signing keys, so any backend can verify an ID token's signature offline without calling the provider on every
login(we calling it on every login).
Google Identity Services is an OIDC provider, so the credential our frontend receives is an OIDC ID token, and our API trusts it only after validating those standard claims (issuer, audience, signature, expiry, email_verified) against Google's published keys.

Key OAuth 2.0 / OIDC concepts used here

ID token (the credential) — a JWT signed by Google. Its trust comes from Google's signature, not from the channel it travelled on.
Issuer (iss) — who minted the token. We trust only a configured allow-list (https://accounts.google.com).
Audience (aud) — who the token was minted for. It must equal our Google CLIENT_ID, otherwise a token issued for some other app could be replayed against us.
JWKS / OIDC discovery — Google publishes its public signing keys at a well-known URL.( it is possible to cache the result to prevent rework)
Signature, expiry, and claim checks — standard JWT validation: the token must be unexpired, correctly signed, and carry a email_verified: true claim.

Why we don't just keep using the Google token

The provider's ID token proves the user is who they say they are, but it is the wrong credential to trust on our APIs. The main reasons are:

It is issued for Google's lifecycle, not ours — we cannot control its TTL, claims, or revocation.
It carries Google's notion of the user, not ours — it knows nothing about the user's authorizations, roles and other controls related to our system.
It is short-lived and not designed to be replayed against our backend on every call.

So we follow the standard pattern: verify the external credential once, then issuefirst-party tokens scoped to our domain. From that point on, our API only ever trusts our own tokens.

Implementation

1. Frontend obtains the Google credential

The SPA loads Google Identity Services, initializes it with our CLIENT_ID, and shows the Google sign-in modal. Google returns an OIDC credential (ID token JWT) to the page.

First, create an account on https://console.cloud.google.com, create a project and an OAuth 2.0 client, and get the Client ID. You will also need to configure the authorized JavaScript origins.
To test locally, I added http://localhost:4200, for example.

Create a component to call the scripts and handle the authentication response.

<Suspense fallback={<p>Loading sign-in…</p>}>
  <AuthApp onAuthenticated={onAuthenticated} />
</Suspense>

Now we add a component to handle future providers; for now we are only use Google.

//auth/src/AuthApp.tsx
import { useCallback, useEffect, useRef, useState } from 'react';
import { providers } from './auth/providers';
import type { AuthHandlers, AuthProvider, AuthResult } from './auth/types';

export interface AuthAppProps {
  /** Called with the provider result (incl. the Google-signed ID token). */
  onAuthenticated?: (result: AuthResult) => void;
}

// Mounts one provider's sign-in UI into a container div. Google renders its
// official button here; the effect runs once per provider, reading the latest
// handlers via a ref so changing callbacks doesn't re-mount the button.
function ProviderSlot({
  provider,
  handlers,
}: {
  provider: AuthProvider;
  handlers: AuthHandlers;
}) {
  const ref = useRef<HTMLDivElement>(null);
  const handlersRef = useRef(handlers);
  handlersRef.current = handlers;

  useEffect(() => {
    const el = ref.current;
    if (!el) return;
    const cleanup = provider.mount(el, {
      onResult: (r) => handlersRef.current.onResult(r),
      onError: (e) => handlersRef.current.onError(e),
    });
    return () => {
      if (typeof cleanup === 'function') cleanup();
      el.replaceChildren();
    };
  }, [provider]);

  return <div ref={ref} />;
}

export function AuthApp({ onAuthenticated }: AuthAppProps) {
  const [error, setError] = useState<string | null>(null);

  const onResult = useCallback(
          (result: AuthResult) => {
            setError(null);
            onAuthenticated?.(result);
          },
          [onAuthenticated],
  );
  const onError = useCallback((e: Error) => setError(e.message), []);

  return (
          <div style={{ display: 'grid', gap: 12, maxWidth: 320 }}>
            <h2 style={{ margin: 0 }}>Sign in</h2>
            {providers.map((provider) => (
                    <ProviderSlot
                            key={provider.id}
                            provider={provider}
                            handlers={{ onResult, onError }}
                    />
            ))}
            {error && <p style={{ color: 'crimson', margin: 0 }}>{error}</p>}
          </div>
  );
}

export default AuthApp;

//auth/src/auth/providers.ts
import { googleProvider } from './google';
import type { AuthProvider } from './types';

// The client-side sign-in providers shown in the auth widget. Google is first.
// Add another provider by implementing its `mount` and appending it here.
export const providers: AuthProvider[] = [googleProvider];

//auth/src/auth/google.ts

const GSI_SRC = 'https://accounts.google.com/gsi/client';
const CLIENT_ID = import.meta.env.VITE_GOOGLE_CLIENT_ID ?? '';

let gsiPromise: Promise<void> | null = null;

// Inject the Google Identity Services script once and resolve when ready.
function loadGsi(): Promise<void> {
  gsiPromise ??= new Promise<void>((resolve, reject) => {
    if (typeof window !== 'undefined' && 'google' in window) {
      resolve();
      return;
    }
    const script = document.createElement('script');
    script.src = GSI_SRC;
    script.async = true;
    script.defer = true;
    script.onload = () => resolve();
    script.onerror = () => reject(new Error('Failed to load Google Identity Services'));
    document.head.appendChild(script);
  });
  return gsiPromise;
}

// Decode the JWT payload for DISPLAY ONLY — the signature is NOT verified here.
// The backend must verify the token before trusting any of these claims.
function decodeIdToken(jwt: string): GoogleIdTokenClaims | undefined {
  try {
    const payload = jwt.split('.')[1];
    const b64 = payload.replace(/-/g, '+').replace(/_/g, '/');
    const json = decodeURIComponent(
            atob(b64)
                    .split('')
                    .map((c) => '%' + c.charCodeAt(0).toString(16).padStart(2, '0'))
                    .join(''),
    );
    return JSON.parse(json) as GoogleIdTokenClaims;
  } catch {
    return undefined;
  }
}

export const googleProvider: AuthProvider = {
  id: 'google',
  label: 'Continue with Google',
  mount(container, { onResult, onError }) {
    if (!CLIENT_ID) {
      onError(new Error('VITE_GOOGLE_CLIENT_ID is not set'));
      return;
    }
    let cancelled = false;
    loadGsi()
            .then(() => {
              if (cancelled) return;
              google.accounts.id.initialize({
                client_id: CLIENT_ID,
                ux_mode: 'popup',
                auto_select: false,
                callback: (resp) => {
                  onResult({
                    provider: 'google',
                    credential: resp.credential,
                    profile: decodeIdToken(resp.credential),
                  });
                },
              });
              google.accounts.id.renderButton(container, {
                type: 'standard',
                theme: 'outline',
                size: 'large',
                text: 'continue_with',
                shape: 'rectangular',
                logo_alignment: 'left',
              });
            })
            .catch((e) => onError(e instanceof Error ? e : new Error(String(e))));

    return () => {
      cancelled = true;
    };
  },
};

2. Credential exchange — `POST /validate/oauth`

The frontend posts the credential to our API:

{ "provider": "google", "credential": "<google-id-token>", "profile": { ... } }

We need an endpoint that is called after the frontend OAuth2 flow. There we validate the credential
the provider generated, then issue our own:

//com/weImpact/auth/controller/AuthController.kt
@PostMapping("/validate/oauth")
fun validateOAuth(@RequestBody req: OAuthLoginRequest, response: HttpServletResponse): TokenResponse {
  val email = try {
    validator.validate(req.credential)
  } catch (e: JwtException) {
    throw unauthorized()
  }

  // validate if the email exists
  val user = users.findByEmail(email) ?: throw unauthorized()
  // issue ours credentials
  return issueFor(user, response)
}

validator.validate performs full OIDC verification:

//com/weImpact/auth/security/OAuthCredentialValidator.kt
class OAuthCredentialValidator(
  trustedIssuers: List<String>,
  private val googleClientId: String,
  decoderForIssuer: (String) -> JwtDecoder = { JwtDecoders.fromIssuerLocation(it) },
) {
  private val decoders: Map<String, JwtDecoder> =
    trustedIssuers.associate { it.trim() to decoderForIssuer(it.trim()) }

  private val log = LoggerFactory.getLogger(OAuthCredentialValidator::class.java)

  fun validate(credential: String): String {
    val issuer = runCatching { SignedJWT.parse(credential).jwtClaimsSet.issuer }
      .getOrNull() ?: throw BadJwtException("missing or malformed iss")
    val decoder = decoders[issuer] ?: throw BadJwtException("untrusted issuer: $issuer")

    val jwt = decoder.decode(credential)
    if (googleClientId !in jwt.audience.orEmpty()) throw BadJwtException("unexpected audience")
    val email = jwt.getClaimAsString("email") ?: throw BadJwtException("missing email claim")
    if (jwt.getClaim<Any>("email_verified") != true) throw BadJwtException("email not verified")
    return email
  }
}

Parse the iss claim and reject it unless it is a trusted issuer.
Require the audience to contain our Google CLIENT_ID.
Require an email claim and email_verified: true.
Return the verified email.

This flow can validate different issuers. JwtDecoders.fromIssuerLocation gets information from the issuer (OIDC discovery);
the result can be cached to improve performance. It fetches <issuer>/.well-known/openid-configuration
(for example, Google's) over the network,
reads the jwks_uri from it, and builds a decoder wired to that provider's public keys (JWKS).
For Google, that's how it learns Google's signing keys.

3. Creating our credentials

A verified Google identity is not enough to get in. The email must map to a known,
ACTIVE user in our database; otherwise the request is rejected with 401.

For an accepted user we build an AppPrincipal (user id, email, role, institution ids) and
issue two HS256-signed JWTs via TokenService:

Access token — short-lived (~15m). Carries email, role, institutionIds, and token_type=access. Sent to the frontend in the JSON response body and attached as a Bearer token on subsequent API calls.
Refresh token — long-lived (~30d). Carries only token_type=refresh and the user id as subject. Never returned in the response body — it is delivered as an HttpOnly, Secure, SameSite cookie so page JavaScript cannot read it (XSS-safe).

{ "accessToken": "<jwt>", "tokenType": "Bearer", "expiresIn": 900 }

private fun issueFor(user: User, response: HttpServletResponse): TokenResponse {
  if (user.status != UserStatus.ACTIVE) throw unauthorized()
  val institutionIds = memberships.findByUserId(user.id).map { it.institutionId }.toSet()
  val principal = AppPrincipal(user.id, user.email, user.role.name, institutionIds)
  val issued = tokens.issue(principal)
  // Refresh token leaves only as an HttpOnly cookie (unreadable by page JS → XSS-safe),
  // scoped to /refresh so it isn't attached to every request.
  response.addHeader(HttpHeaders.SET_COOKIE, refreshCookie(issued.refreshToken).toString())
  return TokenResponse(issued.accessToken, "Bearer", issued.expiresInSeconds)
}

private fun refreshCookie(token: String): ResponseCookie =
  ResponseCookie.from(REFRESH_COOKIE, token)
    .httpOnly(true)
    .secure(refreshCookieSecure)
    .sameSite(refreshCookieSameSite)
    .path("/")
    .maxAge(refreshTtl)
    .build()

With that we have created the credentials we can use on our business endpoints.
The frontend sends the header Authorization: Bearer <access-token>, and the server can verify its signature,
expiry, user information and roles, all without the need for password management.

References:

Designing an ER Diagram with an AI Pair — Why I Reached for Mermaid Instead of a diagram software

Joao Marcos Costa Salles — Wed, 24 Jun 2026 13:46:06 +0000

Introduction

I recently sat down to model the data for a payments + notification-feed
system: customers, projects, a double-entry ledger, PIX payouts, and a
WhatsApp delivery outbox. The kind of domain where one wrong column breaks an
invariant nobody notices until money goes missing.

My usual instinct would be to open draw.io, drag some boxes
around, and connect them with lines. Instead I did the whole thing
in Mermaid — a text-based diagramming language —
while bouncing the design back and forth with an AI assistant (Claude, in my
case), to be clear, I wrote it on my IDE not on the site.

That choice turned out to matter far more than I expected. The diagram stopped
being a picture of the design and became the design itself. Something the
AI could read, critique, and edit with surgical precision, and something I
could commit next to the code as a living spec.

Here's what I learned, in concrete cases.

erDiagram
    CUSTOMER ||--o{ PAYMENT : has
    PROJECT  ||--o{ PAYMENT : receives
    PAYMENT  ||--o| LEDGER_TRANSACTION : "settles via"
    LEDGER_TRANSACTION ||--|{ LEDGER_ENTRY : "has (sum = 0)"
    ACCOUNT  ||--o{ LEDGER_ENTRY : "posts to"

Case 1: Pin-point corrections on a single column

This is the difference that sold me.

In draw.io, a column lives inside a box, inside a shape, inside a canvas. If
I want an AI to fix one field, I have to describe it in prose, "in the
DELIVERY table, the third attribute, change the type", and then I go click
into the right cell and retype it. The AI can suggest, but it can't touch the
artifact.

With Mermaid, every column is just a line of text:

erDiagram
    DELIVERY {
        uuid id PK
        int feed FK
        uuid user_subscription FK
        string status "pending | sending | sent | failed"
        int attempts "default 0"
        string idempotency_key "unique; reserved for z-api dedup"
        string last_error "nullable"
        timestamp next_attempt_at "nullable; backoff gate"
        timestamp sent_at "nullable"
    }

When I described my retry-and-backoff requirements, the AI didn't hand-wave.
It proposed exact additions: attempts, next_attempt_at as a "backoff
gate", idempotency_key to make fan-out retries safe. I could see the precise
diff. A correction became "change int id PK to uuid id PK" and the model
edited that single token, leaving the other 200 lines untouched.

One specific kind of correction got dramatically easier:

Column semantics. The inline comments ("signed; +credit / -debit", "= SUM(entries)") carry intent. The AI used them to check the design against itself — e.g. confirming that a cached balance column is consistent with the ledger entries that derive it.

You simply cannot have that conversation about a PNG.

Case 2: The diagram doubles as a spec — in the repo, in version control

Because the diagram is plain text, it lives in the project:

docs/design/EntityRelation.md

That unlocks everything text gives you for free:

It diffs. A pull request that adds a BANK_ACCOUNT table or a new status enum value shows up as a readable diff in review, right next to the migration that implements it. A draw.io .drawio blob diffs into noise.
It's the source of truth. I treat the Mermaid file as the contract. The Flyway migrations and JPA entities have to match it; when they drift, the diagram is what we reconcile against. The design doc and the schema stop disagreeing.
It encodes invariants, not just shapes. I dropped comments straight into the diagram for rules the boxes can't express:

  %% Invariant: per LEDGER_TRANSACTION, SUM(LEDGER_ENTRY.amount) = 0.
  %% Money is only ever moved between accounts, never created/destroyed.

Those two lines are arguably the most important part of the whole system,
and they live with the diagram — readable by humans and by the AI that
later helps implement the ledger.

A drawing on a website is an artifact you export. A Mermaid file is an
artifact you own, version, and review like code.

Case 3: AI reasons better over "diagram-as-code" than over a picture

This is the part I underestimated.

When you hand an AI a picture of a diagram, it has to do vision — OCR the
labels, guess which line connects to which box, infer cardinality from tiny
crow's-foot glyphs. It's lossy and it's slow, and it quietly gets things wrong.

When you hand it Mermaid, you're handing it structured text it already
understands natively. The relationships are unambiguous tokens:

erDiagram
    INSTITUTION ||--o{ BANK_ACCOUNT : "pays out to"
    INSTITUTION ||--o{ ACCOUNT : "owns (wallet)"
    BANK_ACCOUNT ||--o{ LEDGER_TRANSACTION : "receives withdrawals"

||--o{ is "one-to-many" — the model doesn't have to squint at a graphic to
recover that; it's right there in the syntax. So the conversation moved up a
level. Instead of "I think this line means a one-to-many?", we discussed actual
design questions:

"Should an institution's wallet be its own table, or just an ACCOUNT with owner_type = 'wallet'?" (We chose the latter — fewer tables, one balance model.)
"A WITHDRAW needs a real-world destination — is the ledger ACCOUNT enough, or do we need a separate BANK_ACCOUNT with PIX fields?" (Separate table: pix_key, pix_key_type, soft-deleted via status = archived so old withdrawals still resolve.)

The AI could propose a whole new entity by appending well-formed Mermaid, and
I could paste it straight back into the file and render it. The feedback loop
was: discuss → it emits code → I render → I correct one line → repeat. No
export, no re-import, no redrawing.

With a draw.io picture, every one of those turns would have required me to be
the hands — translating the AI's prose suggestion back into clicks and drags.
The AI becomes an advisor you transcribe for, instead of a pair that edits with
you.

Conclusion

draw.io is great when the diagram is the deliverable, a polished picture for
a slide deck. But when the diagram is part of designing a system, and
especially when you're designing it alongside an AI, the calculus flips
completely:

Corrections are surgical: one column is one line of text the model can edit directly, not a cell you have to find and retype.
The diagram becomes a spec: it lives in the repo, diffs in review, and carries invariants the schema must uphold.
The AI reasons natively — Mermaid is structured text, not pixels, so the conversation rises from "what does this line mean?" to "is this the right model?".

The diagram stopped being a drawing of my intent and became a machine- and
human-readable statement of it. One my AI pair could read, challenge, and
co-edit token by token. For me, that's the whole game.

If you're modeling a domain with an AI assistant, try writing the ER diagram in
Mermaid first. Commit it next to your migrations. Let the model edit the text,
not describe a picture. You'll feel the difference on the very first
correction.

Creating a modular Kotlin project using gradle.

Joao Marcos Costa Salles — Wed, 27 May 2026 22:58:04 +0000

Introduction

The idea of building a system entirely composed of microservices is always tempting for a developer, whether for the challenge itself or to stay ahead of scaling needs. However, analyzing trade-offs and choosing what best fits our context is also part of our profession.
A very common decision today at the beginning of a project is to build modular projects as a way of anticipating a future need to split out a dedicated service. This approach adds less initial complexity than a microservices architecture, while keeping modules sufficiently independent for a potential future separation if needed.

In this article, I will show hot to set up Gradle to enable modules on a monolithic project.

my-inflation/src/main/kotlin/com/salles/scrapping
├── data        # DTO declarations
├── db
│   ├── tables  # Persistence table declarations
├── domain      # Business logic declarations
├── repositories
├── routes
├── services
└── scrapper    # Feature that could move to another project

To a modular monolith:

my-inflation
├── gradle
│   └── libs.versions.toml
├── myInflation  # Module to list prices and products
│   ├── src
│   └── build.gradle.kts
├── root         # Module to link other modules and set up Ktor
│   ├── src
│   └── build.gradle.kts
├── scrapper     # Module for scraping, which may move in the future
│   ├── src
│   └── build.gradle.kts
├── domain       # Module for domain declarations
│   ├── src
│   └── build.gradle.kts
├── data         # Module for the persistence layer
│   ├── src
│   └── build.gradle.kts
├── build.gradle.kts
└── settings.gradle.kts

Module Declaration

It is necessary to declare the modules in settings.gradle.kts. In my case:

include(":myInflation", ":root", ":scrapper", ":data", ":domain")

If you use the same name as the folder, Gradle will find it automatically. If for some reason you need a different name, you can map it explicitly:

project(":myInflation").projectDir = file("core")

Shared Version Catalog

It is very important to create a libs.versions.toml file in the folder structure shown above. In it, we will maintain the versions of all libraries, ensuring consistency across all modules while gaining the benefits of caching and reducing build size. The file will look like this:

[versions]
kotlin = "2.3.20"
kotlinx-serialization = "1.9.0"

[libraries]
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "kotlinx-serialization" }

[plugins]
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }

Module Dependency Configuration

Configuring dependencies between modules is straightforward. I will configure only the root module here, but other modules may also depend on the domain module, for example, and will need their own declarations.
Inside root/build.gradle.kts, add:

dependencies {
    implementation(project(":domain"))
    implementation(project(":data"))
    implementation(project(":myInflation"))
    implementation(project(":scrapper"))
    // ...
}

Only the root module contains the server runner, so add:

application {
    mainClass = "io.ktor.server.netty.EngineMain"
}

Now we need to define which function should run to start the server. In root/src/main/resources/application.yaml:

ktor:
  application:
    modules:
      - com.salles.root.ApplicationKt.module

Removing Unnecessary Dependencies

Finally, we can trim each module's dependencies. To do so, we will use the dependency-analysis-gradle-plugin to analyze module dependencies.

In libs.versions.toml, add the plugin version:

[versions]
# ...
dependency-analysis = "3.13.0"

[plugins]
# ...
dependency-analysis = { id = "com.autonomousapps.dependency-analysis", version.ref = "dependency-analysis" }

In build.gradle.kts, add:
subprojects {
apply(plugin = "com.autonomousapps.dependency-analysis")
}

To run the analysis:

./gradlew <module>:projectHealth

Check {module}/build/reports/dependency-analysis for the report and change it if it makes sense.

With this, the project is configured for a modular structure. However, simply moving files is not enough — inter-module dependencies will still exist. It is necessary to define business logic that is exclusive to each feature module, but that is outside the scope of this article.

The dependency graph ends up looking like this. Note that scrapper and myInflation are now separated, with not direct dependency between the,:

References:

my-inflation: https://github.com/JoaoSalles/my-inflation-api

DEV Community: Joao Marcos Costa Salles

Understanding the Core Concepts of an SQS Consumer

Introduction

Mental Model for Consumer

1. Visibility timeout — the foundation everything rests on

Sizing the timeout

The in-flight ceiling

Extending the window mid-flight

Basic flow on handling messages

Capping retries: maxReceiveCount

3. Dead-Letter Queues "where poison goes to be examined"

What belongs in a DLQ

DLQ with messages is a incident

3. Parallel reading — long polling and batch fan-out

Long polling vs. short polling

Batch receive

The shared-visibility-window caveat

Scaling out

4. Idempotency, the non-negotiable consequence of at-least-once

Usual Strategies, roughly in order of preference

Conclusion

Passwords are not necessary, a Oauth/OIDC approach

Intro

The flow at a glance

OAuth 2.0

OpenID Connect

Key OAuth 2.0 / OIDC concepts used here

Why we don't just keep using the Google token

Implementation

1. Frontend obtains the Google credential

2. Credential exchange — POST /validate/oauth

3. Creating our credentials

Designing an ER Diagram with an AI Pair — Why I Reached for Mermaid Instead of a diagram software

Introduction

Case 1: Pin-point corrections on a single column

Case 2: The diagram doubles as a spec — in the repo, in version control

Case 3: AI reasons better over "diagram-as-code" than over a picture

Conclusion

Creating a modular Kotlin project using gradle.

Introduction

Module Declaration

Shared Version Catalog

Module Dependency Configuration

Removing Unnecessary Dependencies

Capping retries: `maxReceiveCount`

2. Credential exchange — `POST /validate/oauth`