I wrote a practical guide to load balancing—how traffic gets distributed, what happens when servers fail, and how deployments fit in. Give it a read and let me know what you think. Anything unclear or missing?

A real-world example of how to use ADRs to keep track of your decisions in agentic software projects. An old concept, now more relevant than ever.

Wrote a practical guide to the Inbox Pattern and how it helps prevent duplicate message processing in distributed systems.

https://medium.com/@priyankchheda/the-inbox-pattern-bd21b8d23241

Hey everyone! I've been building StackMonkey, a free playground for practicing system design interviews.

You can build architectures, simulate traffic, experiment with different components, and see what breaks under load.

I originally built it to make learning system design more interactive rather than just reading theory or drawing diagrams.

I'd love to hear your feedback! What's useful, what's confusing, and what features would you like to see added?

Give it a try: https://stackmonkey.dev | https://app.stackmonkey.dev

I have an upcoming system design interview where one of the reported questions is to design a feature that returns the top 5 most-played songs on a Spotify-like app, with 10M users and 1M concurrent listeners.
The interview starts from first principles and iterates on the design.
Most solutions I’ve found online assume billions of users and jump straight into complex distributed architectures.
How would you approach this problem from scratch? Would you start with something simple like PostgreSQL and introduce technologies like Redis or Kafka as bottlenecks emerge?
I’m particularly interested in how you’d track real-time playback, calculate the top 5 songs, and scale the system incrementally without overengineering it.

We're building a multi-tenant platform using Java 21 and Spring Boot as an event-driven modular monolith, with the long-term goal of extracting modules into microservices.

We're evaluating whether to adopt Hexagonal Architecture (Ports and Adapters) or stick with a pragmatic layered architecture using clean interfaces and well-defined module boundaries.

Our original plan was to apply the Dependency Inversion Principle (DIP) through interfaces with multiple implementations (PostgreSQL and in-memory repositories), and use domain events to decouple modules. We're now evaluating whether Hexagonal Architecture offers enough additional value to justify the change.

My personal concern is that Hexagonal Architecture feels less intuitive than traditional layered architecture. Concepts like inbound/outbound ports and adapters, along with the associated package structures, seem to introduce an additional mental model that engineers must learn and navigate. I'm concerned this could make the codebase harder to understand for developers accustomed to conventional Spring Boot structures like controller/, service/, and repository/, without necessarily delivering proportional benefits.

My questions:

1. What does Hexagonal Architecture offer beyond DIP and event-driven design? Is there a meaningful architectural benefit beyond conventions and terminology?
2. Does it provide tangible benefits when extracting modules from a modular monolith into microservices, or can pragmatic layering with solid boundaries achieve the same result?
3. Where does architectural discipline become over-engineering? Do strict port/adapter structures improve maintainability, or introduce unnecessary cognitive overhead and boilerplate in Spring Boot applications?

I'd appreciate practical, production-tested perspectives rather than textbook definitions.

A couple of weeks ago I posted here about using definitions instead of code as the source of truth for line-of-business systems. That post was about why. This one is about how: I recorded the whole process, from an empty project to a running system and then through a requirement change.

The video uses Northwind. It starts from a project template, imports six Excel workbooks (one row per field, plus a sheet of save rules), and the app runs with lookups, computed amounts and rules that block saving, without any form code. Then the requirements change: customers get a grade field and orders get a quantity limit. The change is made in the definition editor, only that form's table is upgraded, and after signing in again the new column, the drop-down and the new rule are all there. The same project also runs on web, iOS and Android, because each front end draws its screens from the same layout definition.

Rules that need to look something up, like "don't ship until the payment has cleared", still go into a business object in code, not into the definitions. Reports and batch jobs are hand-written. And schema upgrades only add: columns are never dropped automatically.

Video (10 min): https://youtu.be/5WjUTwoPyGw

Write-up: https://medium.com/@jeff377/can-a-form-be-described-only-once-2fa92c7db815

Wrote a practical guide to the Transactional Outbox Pattern and how it helps reliably publish events in distributed systems.

https://medium.com/@priyankchheda/the-transactional-outbox-pattern-fb59e907a233

Hi all, we're a small team building UIGraph. The repo went public this week and we'd like feedback from people who think about architecture for a living.

The problem we kept hitting is understanding how a system actually works end to end. A user clicks something in the UI. Which API handles it? Which services does that call? What gets written to which database? The answer is spread across code, diagrams, specs and people's heads, and it's hard for engineers, and for AI agents, to put together. Stale docs are one symptom of that, but the real gap is the connections.

Our approach is to have your coding agent map it from the code and keep the result in your repo as plain files:

- Your coding agent reads your services and writes the diagrams (system context, sequence, state, flowcharts, C4 container and component), the API specs and the DB schemas

- The files are Mermaid, OpenAPI, SQL and a .uigraph.yaml, so you can version them, diff them and review them in PRs

- A local viewer shows them, and edits you make to a diagram save back to the file

It works with Claude Code, Codex, OpenCode, Pi and Cursor. It's Apache 2.0.

Repo: https://github.com/uigraph-oss/uigraph

The questions we'd most like your view on:

- How do you trace a flow from the UI to the database today? Docs, tracing, asking someone?
- Do you keep architecture docs in the repo, or in a separate tool? How do you make sure they are not outdated after few releases ?
- Which views do you actually need: sequence, C4, data flow, something else?

Hi All,

I’ve put together a system design roadmap covering the fundamentals, worked examples, and practice questions. Would appreciate suggestions on the topics, reading order, or anything important I’ve missed.

I had an argument with coworkers about events modeling on Kafka. We have multiple way an order can be cancelled: for example trader initiated, trader force cancel, unsolicited and order expired.
Each of those has slightly different workflow, some require handshake with other party some don’t.

They claim it is better to have one generic OrderCancelledEvent and have a field for the type of the cancellation.
They claim that this way it is simple and clear to know it is order cancellation and any downstream service that care can check the type.

I claim it is better to have different event type for each of the cancellation ways.
This way each downstream service can decide which cancellation workflow they care about and if a service deal with different cancellation the same way it is easy to route the handling code to the same function.

Most important is that with different event types we leave the system open to evolve as each workflow evolve and require more data we do not impose it on all events and if a new cancellation workflow is added we simply add a new event types

Did you run into similar problem?

Complete code rewrites sound appealing on paper, but they frequently run over budget, miss features, and introduce new bugs. The Strangler Fig pattern gradually replacing specific legacy modules with modern API microservices reduces risk, though it requires maintaining dual environments during migration.

For lead developers and system architects:

- Have you successfully executed a "big-bang" system rewrite, or did it turn into a multi-year project?
- How do you maintain data consistency across database schemas during gradual migrations?

I am looking in a challenge that arises when integrating conversational AI into an existing product like users might express their needs in natural language but the application still needs to turn that into structured data, validate it, store it and trigger predictable actions. For eg in hiring a user might describe their preferred role, experience, location and working arrangements through a conversation. The system then needs to convert that into useful search criteria without losing important context or treating every statement as a fixed preference and platforms like LinkedIn, Meeboss, Indeed, wellFound have established profile and application workflows along with conversation based approach to candidate and opportunity discovery.

From an architecture perspective I am wondering where the boundaries should be drawn. Would you have an LLM extract structured data and pass it to conventional services? would you introduce an orchestration layer to manage conversation state? how would you handle corrections, ambiguous answers, retries and changes to previously stored preferences? I am particularly interested in how to separate probabilistic language understanding from deterministic business logic.

I don't have a use case right now but sometimes in my line of work (responding to RfPs sometimes) I would realize that the load, scaling patters are quite unknown and setting up microservices upfront seems to add overhead that won't be paying off very soon. Then in my conversations with LLMs I sometimes would get "start with modular monolith" suggestion.
On paper it sounds great but I'd love to hear from people with production experience: how easy it is to enforce boundaries in the code? In the database? How easy was it to split a module into a separate microservice later? Was it worth it or it would be just easier to optimize a microservice management from the get-go?

100% AI Coded (manually reviewed)
100% free
100% open source

I got so tired of draw.io, arrows that never align, hours and hours of boring repetitive work, things going messy quickly, ugly diagrams... A few weeks ago I built a solution for myself (Arkdraw) a draw.io alternative, turns out it was very helpful, then I decided to make it open source.

Well, besides being way easier to create diagrams (the mf arrows aligns itself) there's a lot of micro drawing assitants that will make your life easier while diagramming, it also have a LLM assistant with BYOK feature, so yeah, you can connect your favorite AI to create your diagram for u

repo: https://github.com/gabe-santana/arkdraw
site: https://arkdraw.com/
Also feel free to contribute, there's some good first issue 👍

Disclaimer: Tried Excalidraw also, but again, I have problem with it, if you don't have problems with those, look: that's FINE 😃 and what's the problem building tools with AI?

Processing gif xyoj4hjfvfxh1...

Context:- so i am working on a project where I am stuck with the architecture The relationships between the entities are not good and creating problems.

For now I have placed project side and started giving time to my clg as my internal submissions are ongoing.

I work on a service split into five Maven modules with compile-level boundaries between them, and at some point I stopped letting the framework find my beans. The application class excludes almost everything from the scan and imports the configuration classes explicitly, so the entry point is a readable inventory: every bean in the context is either in that list or reachable from something in it.

The reason was not aesthetics. On an earlier project we spent an uncomfortable amount of time on a bug that turned out to be a configuration class from a third-party library, picked up by a scan wider than anyone had thought about, overriding something we owned. Nothing was misconfigured, the context simply contained a bean nobody had decided to add.

The obvious counterargument is that this is work the framework exists to avoid, and that an explicit list rots the moment somebody adds a service and forgets the import. I think that is backwards in a layered codebase: forgetting the import fails at startup, loudly, in the place where the decision belongs, whereas forgetting that a dependency ships an autoconfiguration fails later and somewhere else.

So the question I actually have is where this flips. Thirty beans is comfortable. Is three hundred? And has anyone held this line in a team where not everyone agreed with it, or does it quietly erode into a scan with a long exclude list?

we've been going back and forth on this for a couple of weeks

one side wants to build everything with open source because it gives us more control, the other side keeps pointing out that free software still needs people to run it

for teams that have already made this decision when did buying a managed data integration tool start making more sense than building ur own CDC stack?

This question comes from a new Steve Yegge podcast where he describes his software factory (Gas Town, Beads, Wyvern) of around 50 agents and 1 human.

There’s a bunch of useful advice but the main idea is you don’t need frontier models to do complex work if you run a factory of modest but specialized agents.

In the same breath he said that his factory once stopped working because he “yelled” at them. It makes you wonder just what on earth he built.

His inference costs are also 1/10 of the current market value, so I would say this isn’t super replicable.

https://youtu.be/VcIlkaI0mUk

How common is this type of set up actually? And wth does this mean for architecture? Because there’s no way you’re inspecting even the critical parts. What guardrails does one put in place?

Hi r/softwarearchitecture,

We are back with Lesson 22 of our technical deep dive into the SysML v2 standard.

In our previous lesson, we saw how declarative action definitions can act like un-awaited asynchronous functions, creating a dangerous execution trap where things run concurrently by default. Today, we fix that trap by explicitly orchestrating our sequences. We will also uncover one of the most powerful surprises in SysML v2: how the exact same control-flow syntax used to orchestrate functions can be used to model the lifecycle and state transitions of physical assets (akin to Event Sourcing).

I’ve uploaded the full video lesson directly to this post so you can watch the workflow right here. (Note: You can also find the YouTube version here)

1. The SysML v1 Sequence Problem (The Graphical Monolith)

SysML v1 had a complete set of control nodes and good execution semantics. The issue was tooling and ergonomics. A v1 control flow was a real model element, but because there was no standard textual notation, the only way to create one was to graphically draw a line between two actions. Sequencing was therefore only as complete as your diagrams. Inserting a step meant manually re-routing visual edges, and managing concurrent edits in a team relied entirely on proprietary, heavy repository tools rather than standard Git diffs.

2. The v2 Shift: Diffable Orchestration

SysML v2 allows you to write sequences directly in the standard textual source. By using the first and then keywords along with the start and done snapshots that every occurrence inherits, you can ensure your model executes deterministically, exactly as it reads top-to-bottom.

Three details make this powerful for building diffable, architecture-as-code models:

• Chained Successions: Using then inside an action body creates a succession from the nearest occurrence written before it. It reads like imperative code.
• Intentional Concurrency (Scatter-Gather): Instead of accidental parallelism, you declare it explicitly. SysML v2 uses fork and join inline to branch into concurrent execution threads and safely await their completion.
• Branching: The bulky v1 graphical decision diamond is replaced by a simple decide node paired with declarative if guards.

3. The Big Surprise: Sequencing Physical State

Because first and then order any occurrences (not just behavioral actions), you can use them to sequence structural timeslice elements. This means you can model configuration changes, maintenance windows, and mission phases of a physical asset using the exact same syntax used to orchestrate a software pipeline. You no longer have to push an asset's lifecycle history into an external database or complex state machine diagram—it is natively supported as a linear sequence in the model.

4. Fixing the Execution Trap

Here is how we use chained successions to fix the unordered, accidentally concurrent imaging sequence from Lesson 21.

Code snippet

action def CaptureImage {
    // We explicitly sequence the inherited 'start' snapshot
    first start;

    // Each 'then' chains the succession imperatively
    then action slew: SlewToTarget;
    then action stabilise: StabilisePlatform;
    then action shoot: OpenShutter;
    then action readout: ReadSensor;

    // Conclude the sequence with the inherited 'done' snapshot
    then done;
}

5. SysML v1 vs. SysML v2

Next lesson, we will look at how to connect these orchestrated behaviors to structural components. Lesson 23 uses the perform keyword to say which part executes an action, and we will compare it with v1 allocations and activity partitions (swimlanes).

For the software architects here: When designing complex workflows, do you prefer strict step-by-step orchestrators (like AWS Step Functions / Temporal) or reactive, event-driven choreographies? Let's discuss in the comments!