The build goes well. The project delivers. The consultancy wraps up and moves on.
Six months later, your internal team needs to make a change. Something that should take a day takes two weeks, because nobody can work out how the platform is structured, why certain decisions were made, or what breaks if you touch the wrong thing.
This is more common than it should be. And it’s almost never the result of bad intentions. It’s the result of platforms built to be delivered, not to be owned.
The hidden cost of poor OutSystems architecture isn’t in the build. It’s in what happens after.
The three things that make handover hard
1. Module structure nobody can explain
OutSystems O11 applications are built from modules. How those modules are structured, what lives where, what depends on what, where the boundaries are, determines how understandable and maintainable the platform is long-term.
A well-structured platform has a clear layering model. Foundation modules at the bottom, core entities, shared logic, integration wrappers. End-user modules at the top, screens, workflows, business logic specific to a feature. Dependencies flow one way: upward. No circular references. No business logic buried in foundation layers. No screens sitting in modules that also contain core entities.
A poorly structured platform has none of this. Modules with names like “Utils,” “Common,” “Misc” that contain a random assortment of things added over time. Circular dependencies that make deployment order a puzzle. Business logic scattered across modules with no clear rationale. Screens that reference entities from six different modules.
When a new developer sits down with a well-structured platform, they can orient themselves. They can answer “where does X live?” and “what does Y depend on?” without having to trace execution paths for two hours.
When they sit down with a poorly structured one, they can’t. And every change carries the risk of breaking something they didn’t know was connected.
2. No record of why decisions were made
Every OutSystems platform contains decisions. Some are obvious from the code. Most aren’t.
Why is this entity structured this way and not the more obvious way? Because the obvious way caused a performance problem at scale and this structure was the fix.
Why does this integration have a retry queue built around it? Because this third-party API goes down every few weeks and without the queue, data gets lost.
Why is this Timer set to run every 5 minutes instead of every hour? Because the business requirement changed six months in and the original Timer frequency caused data lag that operations teams complained about.
None of this is in the module. None of it is discoverable from the code. If the person who made the decision has left, it’s gone, unless someone wrote it down.
The absence of decision records doesn’t just make maintenance harder. It makes the platform dangerous to modify. A new developer who doesn’t know why a decision was made will sometimes reverse it, with confidence, and create the exact problem the original decision was solving.
3. Knowledge that lives in people, not documentation
OutSystems platforms accumulate tribal knowledge. The senior developer who knows which integrations are flaky and need manual intervention sometimes. The consultant who knows that the deployment order matters for this specific set of modules. The architect who knows that this Timer interacts with that one and you can’t change the schedule of either without understanding the interaction.
When those people leave, that knowledge leaves with them, unless there’s been a deliberate effort to extract and document it before the engagement ends.
Most handovers don’t do this deliberately enough. There’s a knowledge transfer session, sometimes two. There’s a walkthrough of the main modules. There’s a document that describes what the platform does at a feature level.
What’s usually missing: a runbook for production operations, a map of integration dependencies and their failure modes, a record of non-obvious architectural decisions, and a guide to the things that are easy to break and why.
What good handover actually requires
Architecture documentation that maps the why, not just the what
A module list is not architecture documentation. A diagram showing module dependencies is closer but still not enough.
Good architecture documentation answers: what is the layering model and why? What are the module boundaries and what determines them? What are the non-obvious dependencies, things that depend on each other for reasons that aren’t visible in the dependency graph? What are the patterns used consistently across the platform and why were they chosen?
This documentation doesn’t need to be long. It needs to be honest and specific. A two-page document that accurately describes the platform’s structure and the reasoning behind key decisions is worth more than a twenty-page document that describes features.
A decision log
Every significant architectural or technical decision made during the build should be recorded: what the decision was, what the alternatives were, why this option was chosen, and what the known tradeoffs are.
This doesn’t require a formal process. A simple running document maintained throughout the engagement, updated when a significant decision is made, is enough. The discipline is doing it in the moment, not trying to reconstruct it at the end of the project when half the context has been forgotten.
On the platforms we’ve built, we maintain this as a living document from day one. By the time handover comes, the new team has a record of why the platform is the way it is, not just what it does.
A production runbook
A runbook is the operational guide for the platform: how to deploy, how to monitor, what the common failure modes are and how to handle them, how to roll back a bad deployment, what the SLA expectations are for different components, who to contact for third-party integrations when they go down.
OutSystems platforms that have been in production for more than a few months have accumulated operational knowledge, the things you learn from running it, not from building it. That knowledge needs to be written down before handover.
Hands-on time, not just walkthroughs
A knowledge transfer session where a consultant talks through the platform while the internal team watches is the least effective form of handover.
The internal team needs to make changes under supervision. They need to deploy. They need to handle a simulated incident. They need to build something small, a new screen, a new integration, while the people who built the platform are still available to answer questions.
Active handover takes longer than passive handover. It also actually works.
A defined support period
Handover is not a moment. It’s a transition. The internal team will have questions after the consultancy leaves, questions they couldn’t predict during the handover sessions because they didn’t know enough yet to know what to ask.
A defined post-handover support period, with a clear scope, a response time expectation, and an end date, gives the internal team a safety net during the transition. It also gives the consultancy an opportunity to answer the questions that surface in real operation that never come up in walkthroughs.
What to ask before you sign a contract
If you’re buying OutSystems development work and you intend to own the platform after the engagement ends, these questions belong in your procurement conversation, not your post-project review.
What is your module architecture approach and how will you document it?
You want a specific answer. A layering model, a naming convention, a rationale. Not “we follow OutSystems best practices.”
How do you capture architectural decisions during the build?
Look for evidence of a real process, a decision log, an architecture document that gets updated during the project. Not “we’ll document everything at the end.”
What does your handover process look like in detail?
Sessions, deliverables, timeline. Ask to see an example from a previous engagement. A handover plan that’s been done before looks different from one being invented for your project.
What support is available after handover?
Duration, scope, response time, cost. Not vague reassurances. Specifics.
Can we talk to a team that took over a platform you built?
The most useful reference check for handover quality is someone who was on the receiving end of it.
The broader point
A platform built to be delivered and a platform built to be owned are different things. The difference is usually invisible during the build and very visible six months after.
The best OutSystems platforms we’ve worked on, built by us or inherited by us, have a clear structure that new developers can orient to, a record of why decisions were made, and documentation that makes production operation predictable.
The worst ones have none of that. Not because the people who built them were bad developers. Because nobody treated handover as a deliverable.
It is one. Treat it like one from the start.