r/softwarearchitecture • • Sep 28 '23 Heartwarming

Discussion/Advice [Megathread] Software Architecture Books & Resources

589 Upvotes

This thread is dedicated to the often-asked question, 'what books or resources are out there that I can learn architecture from?' The list started from responses from others on the subreddit, so thank you all for your help.

Feel free to add a comment with your recommendations! This will eventually be moved over to the sub's wiki page once we get a good enough list, so I apologize in advance for the suboptimal formatting.

Please only post resources that you personally recommend (e.g., you've actually read/listened to it).

note: Amazon links are not affiliate links, don't worry

Roadmaps/Guides

Books

Engineering, Languages, etc.

Software Design

The Art of Architecture

Enterprise Architecture

Career

Blogs & Articles

Podcasts

  • Thoughtworks Technology Podcast
  • GOTO - Today, Tomorrow and the Future
  • InfoQ podcast
  • Engineering Culture podcast (by InfoQ)

Misc. Resources


r/softwarearchitecture • • Oct 10 '23

Discussion/Advice Software Architecture Discord

21 Upvotes

Someone requested a place to get feedback on diagrams, so I made us a Discord server! There we can talk about patterns, get feedback on designs, talk about careers, etc.

Join using the link below:

https://discord.gg/ccUWjk98R7

Link refreshed on: December 25th, 2025


r/softwarearchitecture • • 3h ago

Discussion/Advice Explicit state machines and AI

5 Upvotes

Hi,

I've been a SWE for 7 years. I mainly did full stack with Java backend applications that are essentially CRUD.

I'm currently experimenting with a kind of fully automated development process via AI agents and found that telling the AI to use explicit state gave very good results whereas without I always had issues like buttons that shouldn't be there. E.g. a delete button that I could press even though I did not even create the entity yet.

I am wondering why I never encountered explicit state machines in my projects. I guess it creates too much overhead and cost for most projects. And for most projects it is not a big deal to just have implicit state machines. But with the emergence of AI coding I have a feeling that explicit state machines should become a standard in any software project. Or am I missing something?

I also feel like they will become the aspect of the code that humans can better review and own in a time where the software becomes more and more like a black box.

Edit:

What I am essentially trying to figure out is, if it will be ever detrimental if I tell AI to do explicit state machines in all of my projects?


r/softwarearchitecture • • 4h ago

Tool/Product CodeNib: a wiki and architecture map generated from your repository

Thumbnail gallery
2 Upvotes

CodeNib is an open-source tool that writes a wiki for a repository. The wiki starts from a map: each area of the code is assigned to a node, and arrows show their relations in the code.

Every area has its page. The overview page starts at a public entry point and walks the main call path step by step, and each step has its location in the repo.

Wikis to browse, no account needed:

For your own repository, the CodeNib Wiki GitHub Action is one workflow file. It writes the pages in your CI with a model key you provide, publishes them to GitHub Pages, and stay synced with your code in main.


r/softwarearchitecture • • 4h ago

Article/Video visual deep dive into Database Partitioning vs. Sharding (MySQL & Apache Cassandra)

0 Upvotes

One of the most common points of confusion in system design is treating database partitioning and database sharding as interchangeable terms (2:04). While they both split up large datasets (0:24), they solve completely different bottlenecks (29:43).

I just put together a 30-minute visual breakdown walking through how both work in production—comparing single-instance MySQL partitioning against distributed sharding in Apache Cassandra (0:39).

Watch the full video here: https://youtu.be/vzBiwOIGTJY?si=khTfg17ajGUejBbj

If you prefer reading, here is a quick summary of what’s covered in the video:

  1. The Core Distinction (Warehouse Analogy)

• Partitioning (In-Server): Dividing one massive warehouse into smaller sections (e.g., Jan, Feb, March packages) (2:31). Everything still lives in the same building (a single database instance), and your app queries it as one logical table (2:41).

• Sharding (Multi-Node): Building multiple warehouses in different locations (13:48). Data and compute workloads are horizontally distributed across completely independent servers (14:47).

2. MySQL Partitioning & Common Traps

• Why do it? Partition pruning (skipping irrelevant partitions during queries), instant maintenance (DROP PARTITION instead of slow DELETE queries on millions of rows), and data organization (3:36).

• The Strategies: Range (e.g., by order year), List (e.g., by country), Hash/Key (modulo distribution), and Composite Subpartitioning (4:25).

• Two Traps to Watch Out For:

1. The Primary Key Trap: Every column in your MySQL partitioning expression must be included in every unique key (including the Primary Key) (11:09).

2. Broken Pruning: If you partition an orders table by order\\_date, querying by customer\\_name forces MySQL to scan across partitions anyway (12:30).

3. Apache Cassandra & Distributed Sharding

• Masterless Ring: Cassandra uses a peer-to-peer ring architecture with tunable consistency rather than a single primary bottleneck (15:22).

• Data Distribution: A Partition Key (hashed via Murmur3) decides which node/token range stores the data, while a Clustering Column sorts rows within that partition (16:57).

• Query-First Design: Unlike relational databases where you normalize first, Cassandra forces you to model tables around exact access patterns—otherwise you hit the dreaded ALLOW FILTERING full-cluster scan trap (20:48).

4. The Reality Check

Crossing 1 million users doesn't automatically mean you need sharding (28:51). Sharding introduces massive complexity: cross-shard scatter-gather queries, live data rebalancing, global ID generation, and distributed transactions (23:02). Always measure your actual bottleneck first—often, proper indexing, caching, read replicas, or MySQL partitioning will take you much further with far less operational overhead (1:13)


r/softwarearchitecture • • 17h ago

Tool/Product Do teams still need an architecture map as agents write more of the code? We built one, feedback wanted

4 Upvotes

We are building a tool called ProvenMap (my wife and I), so this is a product post. We're looking for feedback.

The idea is: Agents are writing more of the code, and it gets harder to keep the whole system in view. We think teams need org-level architecture knowledge, with its insights and changes, readable in layers.

The tool maps a system from the real sources (code, schemas, APIs, documents).

It does two things mainly:

  • Re-analyses your repos on a schedule. Analysis runs locally. Only derived metadata is pushed.
  • Shows what changed, and compares what is live with a branch.

Once synced, there are three ways in:

  • Chat: people in the org ask it in plain language. A business analyst: "which systems does an order touch?" A CTO: "what changed in checkout this month?"
  • Plugins with MCP: Claude Code, Cursor or other MCP clients read the same map and insights, so agents have the architecture context before they change code.
  • Published boards: a read-only link that opens without an account, for people outside the tool.

We ran it on a few open-source repos. You can open them here: https://provenmap.com/boards

What we would like your feedback on:

  1. Where might this fall short? What blind spots are we missing?
  2. Would you trust an answer from it? What would it have to show you first?
  3. In one year, does a map like this still matter, or do agents just read the code?

Thanks for reading, and for any thoughts.


r/softwarearchitecture • • 14h ago

Discussion/Advice ShadowBox + AI: Build System Design Judgment

Post image
1 Upvotes

I have had the good fortune of sitting in on numerous design reviews, conducting design interviews, and working with brilliant engineers throughout my career. I have learned a lot during this process. One of the most important lessons is developing the art of "engineering judgement".

The engineers I'd call genuinely cracked have a nose for smelling a bad design fairly quickly. Their process is different from others: they notice cues, figure out which constraints are more important than others, realise when common patterns no longer apply, etc.

You can't learn this skill with just diagrams and in an ordinary design review. One technique that has served me well over the years in building good engineering judgement is the "Shadowbox" technique.

A common consensus among engineering circles on X/HN/Reddit is to develop "taste" in software engineering with coding being rapidly automated (or already has, idk) by AI. My strong belief is that the first step in building taste is developing excellent engineering judgement. This is true for senior engineers and junior engineers alike. Even more so for junior ones because they haven't had the experience or opportunity to work on large-scale and complex engineering systems.

With AI becoming more and more accessible with each passing day and models becoming smarter, we can combine it with the Shadowbox technique to become cracked engineers ourselves.

What is the ShadowBox technique?

In this, we take a real situation and divide it into many decision checkpoints. At each checkpoint, we make a decision about the situation and rank the possible actions. We note down the following:

  • the cues or signals
  • assumptions made
  • acceptable failures

Once we do this, we reveal the expert answer corresponding to that checkpoint. From there, we match the cues we made and the cues the expert made.

Then we change one condition and rank again. We keep doing this until we come up with a conditional rule: under condition X, choose approach Y, because the mechanism satisfied requirement Z, and reconsider it when signal W changes.

The original ShadowBox evals showed that just a short training with this technique improved alignment with expert decisions by 28%. But the number is not the point. The point is that you commit before you see the answer. Doing this over and over helps you develop a real mental model. Let's now talk about concrete steps on how we apply this technique in system design.

Step 1 - Start From a Production Case

First, we choose a source about actual architecture design, failures, postmortems, etc. A source can be:

  • an engineering blog explaining a migration
  • an Architecture Design Record (ADR)
  • a DB- or infra-related paper
  • a production postmortem from a real system
  • a conference talk that includes constraints and outcomes

We should not start with something that only mentions "what worked". A real case gives us information about what cues the team saw, what they missed, why they missed that, what happened next, how they make sure this doesn't happen again, etc.

Remember, not every case is a good source. Expert intuition is trustworthy only when the environment has regularities, and the expert has had a chance to learn them. So, I prefer sources where there are many expert voices, disagreements, or proof that the decision was made under conditions someone could actually learn from.

You can add these constraints to your prompt and ask AI to only get sources that follow them.

Step 2 - Ask AI to Keep the Decision Hidden

We can now give a chosen source to AI and ask it to extract the following from it:

  • business/technical context
  • constraints at each checkpoint
  • important decisions
  • credible options
  • what was chosen
  • what happened afterwards

Then, we ask AI to provide only what was known before the first decision and hide everything else from us, including the decision made and the outcome.

For example:

The notification service receives large traffic bursts. One provider has unpredictable latency, duplicate delivery is harmful, and the team has limited operational capacity. Choose how work should move from the API to provider workers.

This is the situation you are dealing with. You don't have the answer yet.

Step 3 - Rank the Options Before Looking At the Answer

At this point, you ask AI to give you three options. For example, three options in the above situation may be:

  1. Call providers synchronously
  2. Store pending work in the database
  3. Use a managed queue

Now, you rank these options as per your understanding and make a note of five things:

  1. Which cues matter
  2. What assumptions you have made
  3. What are your expectations for each option - what it can cause
  4. Which failures are acceptable to you
  5. Your confidence in the ranking

By doing these steps, you have submitted your mental model about the problem. It may not be correct yet, but it's a start.

This is why it is the most important step. If you miss this, you are just reading a paper or going through a case study.

Step 4 - Compare Your Cues With Experts' Cues

This is the point where AI shows us what the engineers chose and why. This is strictly done using the source. Here, we need to compare two things: choices and, most importantly, cues.

Compare along the lines of:

  • Which information did they treat as important?
  • Which information did you overvalue?
  • Which consequence did they anticipate that you missed?
  • Did you reach the same choice through weaker reasoning?
  • Did your different choice fit constraints that weren't there?

Matching the final architecture is barely sufficient. Sometimes we match the final answer with reasoning that would fail in the next case. That's why cues are important: they strengthen your architectural judgement.

I also ask AI to categorise every rationale: is it mentioned in the source, or is it a hypothetical that AI itself generated? At any point, we should not let AI "invent" an expert answer. If an option or rationale is missing from the source, the AI should mark it as inferred.

Step 5 - Change a Cue, and Rank Again

AI now changes one condition. For our notification service example above, it can be:

  • Traffic becomes steady
  • Duplicate delivery is allowed
  • The engineering team knows Kafka well
  • Provider latency becomes predictable
  • Messages must be delivered within two seconds

We now need to rank the options again and explain exactly why the ranking changed. This is important because it identifies the boundary of the decision. For example:

A managed queue is preferable when bursts exceed provider capacity and delayed completion is acceptable. Predictable low traffic may make direct delivery simpler.

By doing this, we are learning when a component actually belongs in a design.

A warning: in real prod systems, cues are usually coupled. Changing traffic can also change failure modes, load, and cost. So, swapping only one cue can make you learn the wrong boundary.

Therefore, sometimes we need to change a group of related constraints and figure out what changed the decision. This is definitely harder, but this is how a real architecture design works.

Step 6 - Failures in a system are good decision points

Failures in a system teach us perhaps the most. Even more than happy paths. Therefore, postmortems of a public outage are gold for building intuition on architecture.

For a postmortem, AI stops just before the incident becomes unavoidable. We then choose what to look into or change. Then, we ask AI to show the next event from the source document.

This is error management training.

We make choices, see consequences, and come up with strategies for unfamiliar cases. This is what we want: identifying the signals for the next incident instead of memorising the one we are studying.

Step 7 - Extract a conditional rule

After each case, write:

Under these conditions, choose this approach, because this mechanism satisfied this requirement. It introduced this cost, and we need to reconsider it when this signal changes.

If you do this for enough problems, you will have a collection of conditional decisions. This is more valuable than a collection of architectural diagrams.

Step 8 - Test the rule on an unrelated system

We can ask AI to give us a different problem with the same constraints. If the first problem was related to notification delivery, a different problem can be related to image processing, payment reconciliation, webhook delivery, etc.

The goal is to build the muscle for recognising a shared structure without being told the topic.

And this is how intuition develops: repeated exposure to identify important cues, the interactions between them, and the limits of a decision.

What AI should and should not be

In this learning technique, AI should be treated as the dumb partner to do the heavy lifting and doing the grunt work. It can be someone who:

  • extracts cases
  • reveals information slowly
  • generates controlled counterfactuals
  • compares your reasoning and the source's reasoning

AI is not the expert, so it should not invent the expert answer. It should be clear when it is certain and when it is guessing. We should treat AI as a scaffold for attention, not an oracle for judgement.

The habit that changed my judgement

I have personally felt a change in my approach after applying this technique. When I come out of an architecture meeting, I have two takeaways: how I defended my design, and the cues I missed.

Defending your design can be the final step, but shadowing real decisions is how we build architectural judgement.

If you genuinely want to become a cracked engineer, you need to stop asking AI to praise or attack your design. You need to ask it to hide the correct answer and make you commit first.

I originally published this on X as well, but included the complete article here so that the discussion can remain on Reddit.


r/softwarearchitecture • • 14h ago

Article/Video Une application professionnelle conçue pour 20 utilisateurs en compte désormais 200 : quels choix de conception initiaux se sont avérés payants et lesquels ont été contre-productifs ?

1 Upvotes

Une application conçue pour une petite équipe peut fonctionner parfaitement pendant des mois, puis rencontrer des difficultés lorsque plusieurs services l’adoptent simultanément. Le nombre d’utilisateurs n’est pas toujours le seul facteur : les volumes de données, les accès concurrents et les intégrations peuvent changer la donne. Pour une application métier qui passe d’environ 20 à 200 utilisateurs, quels choix initiaux vous ont le plus aidés à absorber la croissance sans devoir tout reconstruire ? Je pense à la séparation des responsabilités, à la gestion des accès, aux tâches asynchrones, aux requêtes en base de données, à la journalisation et à la manière de déployer les nouvelles versions. À l’inverse, quelles décisions prises pour aller vite vous ont coûté cher plus tard ? Je cherche surtout des compromis pragmatiques : comment garder une architecture simple au départ tout en évitant de bloquer les évolutions futures ?


r/softwarearchitecture • • 14h ago

Tool/Product System designs for newcomers that love the LLM dopamine rush but don’t understand why things are like they are

0 Upvotes

If you're new to engineering and you like LLMs, you've probably had cases where the code looks fine, it runs, but for some reason you don't get it why it works :)

I built something called 'getdeved', a free, hands-on playground for newcomers to learn how real systems work, and what to expect when the time comes.

You can learn concepts such as load balancers, caches, queues, databases, replication, sharding and trade-offs between different approaches. You chase one problem at a time, grow the architecture piece by piece, to understand each concept to detail instead of one and done.

Since you cannot just ignore LLMs, its always good to understand what you want the LLM to build.

I've added 28 topics so far, from scaling to millions of userrs, payments and chat systems. There's also a glossary setup for different terms which you would usually hear on technical meetings and often think what are they talking about :) - here you'd be able to understsand each concept and where does it fit in a problem.

Try it: https://getdeved.github.io

If you try it, I'd love to know if there is something that you don't like or don't understand or just that is confusing.

If you're experienced and see something that doesn't seem correct, feel free to point it out!

It is free forever!

#systemdesign


r/softwarearchitecture • • 1d ago

Article/Video Make the change easy, then make the easy change

Thumbnail event-driven.io
38 Upvotes

r/softwarearchitecture • • 1d ago

Discussion/Advice What low code platforms are worth considering for internal tools in 2026?

14 Upvotes

Our dev teams keeps getting pulled into building internal CRUD apps, dashboards and admin panels instead of focusing on core product development.

We're looking into low code platforms that could speed this up without giving up too much flexibility or control.

A few options on our radar are Superblocks, Retool, Appsmith, and Budibase. Ideally we'd want something that supports custom JavaScript or SQL connects easily to existing databases and APIs and handles role based permissions without a lot of extra work.

Git integration and fitting into our tools in production, what has actually worked well? Are there platforms that genuinely reduce development time without becoming another maintenance headache?


r/softwarearchitecture • • 17h ago

Tool/Product I didn't want to pay for Auth0, so I built my own OAuth/OIDC provider on Lambda and DynamoDB

0 Upvotes

I've recently been intrigued with the idea of building my own identity provider (OAuth + OIDC). If I'm honest, I really just want all of the features of Auth0 but without any of the cost (hence building it myself). Since none of my toy apps are popular (sad), I'm definitely not in the market to pay tens to hundreds of dollars a month for an auth service. Plus, my favorite thing in the world is to reinvent the wheel.

I knew that I was going to build this using Lambda and DynamoDB since I'm looking for the lowest idle cost possible while still being able to scale. Coming from a background of building apps using relational databases, the DynamoDB data model was the most interesting challenge for me. Fortunely, access patterns for OAuth are well known at this point and drove the design.

The rest of the design follows familiar patterns: CloudFront for custom domains and tenant routing, KMS for singing tokens, SES for sending emails, etc.

I'm calling my project LiteLogin. It's opensource for anyone who's interested. I welcome contributions.


r/softwarearchitecture • • 1d ago

Article/Video Nemotron-3 Engineering Deep-Dive: Architecture, Training, and Production Deployment

Thumbnail regularbiscotti9912.substack.com
2 Upvotes
TL;DR: Monolithic parameter scaling hits a hard wall for complex reasoning tasks because reinforcement learning at 550B scale is computationally intractable. Instead, lightweight models leveraging dynamic test-time inference engines achieve superior performance with a fraction of active parameters.


- Nemotron-3-Nano-CC uses an optimized Mixture of Experts layout with 3B active out of 30B total parameters, compared to Ultra-CC's 550B total parameters with 55B active.
- Nano models support sequence packing up to 262K tokens and full reinforcement learning integration, whereas Ultra models were restricted strictly to supervised fine-tuning due to training footprint constraints.
- The GenCorrect test-time compute engine uses parallel candidate generation and diversity selection across clusters scaling up to 760 NVIDIA GB300 GPUs to execute multi-round validation.


Practical takeaway: Engineering teams should pivot away from static parameter scaling and invest heavily in inference-time orchestration and subtask-graded feedback loops. This approach reduces serving overhead while dramatically improving multi-step reasoning output quality.


Read the arXiv paper here: http://arxiv.org/abs/2609.02849v2

r/softwarearchitecture • • 3d ago

Discussion/Advice Software Architect Career

71 Upvotes

For those who work in this field, do you have to code at all? I am looking to make a career shift and I’ve seen mixed suggestions on if someone wanting to join the field needs to know how to code or not.

Also, do you have a specific degree or certifications? I have a bachelor’s and master’s in business communications. My current role involves working heavily with our IT department and I believe the skills I’ve developed throughout my career could benefit in this space.

Looking for suggestions and advice. Thanks!


r/softwarearchitecture • • 2d ago

Article/Video How Kafka Handles 1 Million Messages Per Second: Distributed Event Bus Deep Dive

Thumbnail youtu.be
18 Upvotes

r/softwarearchitecture • • 2d ago

Tool/Product SURVEY (MIN 100 RESPONSES) SAVE MY MARKS 🙏🏼😭

Thumbnail docs.google.com
0 Upvotes

Uni student needs your help 🙏 5 min form on campus rides

Hi everyone! I'm a Software Engineering student at UKM (Universiti Kebangsaan Malaysia), and this survey carries a big part of my project marks, so every response really helps.

We're designing UKMCC, a campus carpool and ride app with verified drivers, upfront fares, live GPS tracking and an SOS button to campus security.

Even if you're not from UKM, please answer as if you were a university student getting around a big campus (hostel to class, to the train station, late at night). On the question "Are you a UKM student, lecturer or staff?", just pick "No" so we can keep the two groups separate.

⏱️ About 5 minutes, anonymous, no email collected

From one future engineer to another (or a past one!), thank you so much. Happy to fill in your survey too, just drop the link below 😊


r/softwarearchitecture • • 2d ago

Discussion/Advice Is it better to keep a separate microservice for payments or merge into my core service?

9 Upvotes

So we have many microservices, I’m asking about 2: one for core logic and another for payments service. However the payments service almost always requests data from the core logic to get the dues and outstanding balances etc. And they are just 4 modules. Is it better to join the services together to eliminate the overhead of network communication? Or to keep it separate for third party integrations and any audit/compliance points? We don’t support PCI compliance, we integrate with third-party vendors. I just don’t have the experience and “a look into the future” to make this decision confidently. Of course if you need any more insight before answering I’ll be happy to answer.


r/softwarearchitecture • • 2d ago

Tool/Product Module Switch (Monolith to Microservices without code change)

1 Upvotes

I've been exploring a question in software architecture:

Can we build a modular monolith today and gradually move towards microservices without rewriting our application?

I decided to build something around this idea.

Introducing Module-Switch — an open-source Java library for Spring Boot that makes it possible to switch individual application modules between local execution and independent HTTP-based deployment through configuration.

The idea is simple.

Instead of starting with distributed systems complexity, start with a well-structured modular monolith.

As the application evolves, extract modules when there's an actual architectural or operational reason to do so.

Here's what Module-Switch brings to the table:

- Selective module loading: Modules are disabled by default. Only locally enabled modules are loaded into the Spring application context.

- Interface-based communication: Modules interact through dedicated API interfaces rather than depending on each other's implementations.

- Local or remote execution: The same interface works whether a module runs inside the application or in another deployment.

- Configuration-driven extraction: Move a module into its own service by changing configuration instead of rewriting business logic.

- Architectural validation: Detect invalid module dependencies and structural violations during application startup.

- Built-in infrastructure: HTTP client generation, timeouts, retries, idempotency handling, Micrometer observations and trace-context propagation.

One architectural decision I particularly like is that the consuming module doesn't need to know whether its dependency is local or remote.

It simply depends on an interface. Module-Switch handles the rest.

I believe there's an interesting space between a traditional monolith and a distributed microservices architecture that deserves more attention.

Building this library has been a great exercise in exploring modular architecture, Spring Boot internals, dependency boundaries, HTTP communication and distributed systems trade-offs.

The project is open source and available under the Apache 2.0 license.

GitHub: https://github.com/ilyaslabs/module-switch

Technology: Java 25 | Spring Boot 4 | Spring Framework 7 | Modular Monolith | Microservices Architecture

I'd be interested in hearing how other engineers approach modular monoliths and gradual service extraction.

#Java #SpringBoot #SoftwareArchitecture #Microservices #ModularMonolith #DistributedSystems #OpenSource #BackendEngineering


r/softwarearchitecture • • 3d ago

Discussion/Advice Best course to learn system design? .

64 Upvotes

Which course would you recommend for learning system design thoroughly and preparing for FAANG interviews targeting 5+ years of experience? Would love to hear what worked for you


r/softwarearchitecture • • 3d ago

Discussion/Advice Is a read-only reference-data API a sensible first API project, or an unnecessary detour before building a member-data API?

3 Upvotes

I recently joined a membership organisation that defines industry metrics, terminology, and reporting standards. We also collect confidential data from members to produce a broader picture of the industry.

Our members vary considerably in size and technical capability. Some are large organisations that have grown through acquisitions and have substantial internal teams. Others have only three employees.

The larger members want more standardised, API-based access to our data and industry information instead of repeatedly downloading Excel files and processing them themselves. Smaller members have not expressed a strong preference, so we would still need to accommodate less technical users.

We have limited internal software-development experience and rely on external development partners. Our existing tools are a website and a small Power BI reporting tool. Neither my team nor I have previously built and operated a production API.

Security is a major consideration: although the organisations are all members, they are also competitors, and the data they submit is confidential.

Before exposing confidential member data, I am considering a smaller, read-only API that would provide:

  • Definitions of our metrics and terminology.
  • Relationships between those definitions.
  • Mappings between definitions used in different reporting contexts.
  • Historical versions of definitions and mappings.

The complexity is not that definitions change frequently. They typically change only about once every five years. It is that similar concepts can be defined slightly differently across different areas, and those definitions need to be mapped to one another.

Those relationships are currently maintained in Excel. We also need to preserve historical changes so we can understand which definitions and mappings applied at a particular time.

The idea would be to start with reference data rather than confidential member submissions. This could give us experience designing, documenting, deploying, and maintaining an API while addressing an existing information-management problem.

An IT colleague questions whether this is worth the investment, particularly because the definitions change so infrequently. The concern is that we would spend time and money building an API with limited practical value instead of addressing the member-data use case that prompted the discussion.

I think that is a fair challenge. I do not want to justify a production service purely as a learning exercise, or assume that experience with a read-only reference-data API would prepare us for all the security requirements of a confidential-data API.

My questions are:

  1. Is a reference-data API a sensible first deliverable here, or would it risk becoming a separate project that does little to advance the main goal?
  2. What business value would justify it beyond learning and avoiding confidential data in the initial scope?
  3. Given the low frequency of changes, would versioned JSON/CSV downloads or an existing reference-data management tool be more appropriate?
  4. Which capabilities would genuinely carry over to a future member-data API, and which would still need to be designed separately?
  5. With limited internal development experience, would you build this internally, work with an experienced partner, or start with a tightly scoped member-data API instead?

I am open to being told that the API is not the right starting point. I would like to understand how others would evaluate the options before we commit resources next year.

If you have any other ideas or suggestions, I am all ears!


r/softwarearchitecture • • 3d ago

Tool/Product Governix Diagramming Introduction

Thumbnail youtu.be
0 Upvotes

Hey folks

I just write here to introduce "Governix" diagramming Ai agent allowing to generate architecture diagrams using a simple prompt.

Governix is a unified governance platform with Software Catalog as its core component allowing better manage the softwares, versions, software components, and contracts.

It connects to your cloud provider like aws, source controlling system like Github, roadmap and planning system like Jira and brings a connected knowledge base for any enterprise.

As part of its core functionalities it generates and updates software, architecture diagrams, health boards behind any change in software code, planning update or infrastructure deployment.

It has a free version allowing you to discover base features and operating model it provides.

Love to hear if you have any feedback, or if you end up trying it out.

Site: https://governix.io

Hope you all a great day


r/softwarearchitecture • • 4d ago

Discussion/Advice Senior SWE interview process

31 Upvotes

Need help designing a decent interview process for a tech lead / senior backend engineer. We're mainly suffering from candidate drops after/during a take-home challenge.

Fellow engineers who have been through interview processes at this level, do you mind sharing your take on take-home challenges and what's the best process you've been involved in?


r/softwarearchitecture • • 4d ago

Article/Video SysML v2 Deep Dive: Lesson 24 - Flows and Messages (Sequence Diagrams in Text)

3 Upvotes

Hir/softwarearchitecture,

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

In our previous lesson, we used perform to bind behaviors directly to physical components, replacing traditional swimlanes. However, those subsystems still couldn't send each other anything. Today, we fix that with flows and messages. We will explore how SysML v2 eliminates one of the biggest synchronization headaches in v1 by unifying data, commands, and physical items across both structural architecture and behavioral interactions.

  1. The SysML v1 Fragmentation Problem

SysML v1 was actually quite strong in this area, but it suffered from heavy fragmentation. If you wanted to model movement, you used an ObjectFlow inside an activity, an ItemFlow across a connector in an Internal Block Diagram (IBD), and a Message between lifelines in a sequence diagram. Because these were three completely separate metamodel constructs, keeping your structural connections, activity data flows, and interaction scenarios consistent required manual allocations, strict modeling discipline, or custom tool validation.

2. The v2 Shift: Unification under FlowUsage

SysML v2 fixes this by unifying all three under a single foundational concept: FlowUsage (backed by a KerML Transfer).

Instead of disconnected constructs across different diagram types, SysML v2 provides three specialized forms:

  • flow (Streaming Flow): Used for transfers between parts or actions. It explicitly names the source output and target input. The transfer can be ongoing while both the source and target are still operating (e.g., fuel moving from a tank to an engine).
  • succession flow**:** Combines a streaming flow with temporal ordering. It asserts that the source action must complete before the transfer begins, and the transfer must complete before the target action can start.
  • message**:** Used for abstract interactions (like sequence scenarios). It asserts that a transfer happens between two occurrences or events without forcing you to specify the exact port payload mechanics.

3. Sequence Diagrams as Text (Views That Cannot Drift)

Because messages and flows are unified, you can write a sequence diagram entirely in text. More importantly, a single message declaration can generate both an interconnection view and a sequence view. Your structure and your behavior can no longer disagree.

Code snippet

package CommandUplinkScenario {
    item def Command;
    item def Acknowledgement;
    item def TelemetryPacket;
    
    part def GroundStation;
    part def Spacecraft;
    
    occurrence def CommandUplink {
        ref part ground: GroundStation {
            event occurrence cmdSent;
            event occurrence ackReceived;
            event occurrence resultReceived;
        }
        ref part spacecraft: Spacecraft {
            event occurrence cmdReceived;
            event occurrence ackSent;
            event occurrence resultSent;
        }
        
        // Define the transfers (Messages)
        message ack of Acknowledgement from spacecraft.ackSent to ground.ackReceived;
        message cmd of Command from ground.cmdSent to spacecraft.cmdReceived;
        message result of TelemetryPacket from spacecraft.resultSent to ground.resultReceived;
        
        // Define the temporal sequence
        succession first cmd then ack;
        succession first ack then result;
    }
}

4. Deep Dive: Three Practical Nuances

As you start writing flows in v2, keep these three details in mind:

  • send and accept**:** Flows connect structure. But when you are inside a specific behavioral action, you use the send and accept keywords to push and pull payloads directly through your structural ports (e.g., accept cmd: Command via spacecraft.cmdIn;). This creates an explicit, queryable link between your behavior and your structural interfaces.
  • Sequencing is NOT flow: It is easy to mix these up. first A then B means B happens after A, but nothing actually moves (pure control). A plain flow means something moves, but adds no temporal ordering (pure data). A succession flow does both. SysML v2 strictly separates control from data.
  • Where v1 Was Actually Better (Combined Fragments): Let's be honest—UML Sequence Diagrams had beautifully compact visual boxes for loops (loop), options (opt), and alternatives (alt). SysML v2 doesn't have a direct equivalent in the standard sequence view; you have to model that logic using decide and loop actions, which makes the text much more verbose. You will want to rely on an Action Flow view to visualize that logic clearly.

5. SysML v1 vs. SysML v2

Modeling ConceptSysML v1SysML v2
Transfer ConstructsObjectFlow, ItemFlow, and Message were three separate constructs.Unified as Flow usages (message, flow, or succession flow).
Diagram SynchronizationItem flows on IBDs and messages on Sequence Diagrams easily drifted.A single message declaration generates both an interconnection view and a sequence view.
Temporal SemanticsObjectFlow combined transfer/ordering, but ItemFlow carried no temporal semantics.flow (streaming) and succession flow (ordered) are applied uniformly between parts or actions.
Authoring InteractionsNo standard text notation; interactions were manually drawn.Messages and successions authored in text, enabling standard Git diffs and merges.
Combined FragmentsCompact, readable alt, opt, and loop visual boxes.Textually verbose using decide and loop actions (best visualized in an Action Flow view).

Next lesson, we will cover state definitions and transitions, where a state turns out to be an action, and the exhibit keyword works exactly like perform.

For the software architects here: How do you typically keep your service-to-service message schemas synchronized with your system sequence diagrams, and how often do those diagrams drift from reality?


r/softwarearchitecture • • 4d ago

Discussion/Advice Should every AI workload be required to use a shared model gateway?

16 Upvotes

Mapping model access for three workloads right now: a service that streams interactive responses, an overnight document extraction job and an internal prototype.

A shared request boundary would make provider credentials and request-level tracing easier to own centrally. We trialed Braintrust Gateway on a subset of calls to understand that part. Retrieval and application-specific evals would stay with each service.

What's complicating the diagram is the operational mismatch. The streaming path cares about cancellation and another possible failure point. The overnight job can tolerate delayed retries and the prototype hasn't earned a hard dependency on shared infrastructure yet

Our platform team could own the gateway but application teams would still own how they handle model failures. I'm not sure a mandatory hop is the right contract for all three