Latest / The CTO Podcast with Fexingo: Technical Leadership, Architecture, and Engineering Org / How Atlassian Tamed Technical Debt With Architecture Contracts
Transcript
- Lucas: When you run a platform for thousands of developers, the hardest problem isn't building the infrastructure — it's getting everyone to use it consistently without turning into a bureaucratic nightmare. Atlassian figured this out by creating something they call architecture contracts, which are basically binding but lightweight agreements between product teams and the central platform group. Luna: That sounds like a middle ground between total chaos and a rigid mandate. How do they actually enforce those contracts without slowing everyone down? Lucas: The key is that they aren't enforced by a committee review board. Instead, they're baked directly into the developer toolchain. If a product team tries to spin up a new service that violates the contract — say, using an unsupported database or bypassing the central authentication layer — the deployment pipeline just blocks it automatically. No human approval needed, no waiting around. Luna: So the constraints are technical, not political. That’s a huge difference in adoption rates. Lucas: Exactly. And the results have been pretty striking. Over an eighteen-month period starting in late twenty twenty four, Atlassian reported that cross-team integration errors dropped by roughly fifty percent because everyone was speaking the same language on APIs and data formats. It also cut the average time to onboard a new service from two weeks down to about three days. Luna: Three days is massive. But does that mean product teams lost flexibility? Did they complain about being boxed in? Lucas: Initially, yes. There was pushback from some of the larger product groups who felt the contracts were too restrictive on custom implementations. But the turning point came when the platform team started treating the contracts as living documents rather than stone tablets. They set up a monthly review cycle where any team could propose a change to a contract clause if they had a legitimate business reason. Luna: So it became a negotiation process instead of a top-down order. That feels much more sustainable. Lucas: It did. And here is the thing most people miss about this model: the platform engineers at Atlassian don't just write the rules. They share the blame when things break. If a contract clause causes a production outage, the platform team takes responsibility for updating it. That accountability built trust really quickly. Luna: I love that. Usually, the platform team just says we told you so. Taking ownership changes the dynamic completely. Lucas: Right. So before we dive deeper into the specific mechanics of how they structured these contracts, I want to pause for a second. If today was actually useful to you, the way these stay ad-free is listener support — buy me a coffee dot com slash fexingo. It helps keep the research sharp and the conversations honest. Luna: Yeah, and honestly, that kind of deep-dive into real engineering structures is exactly why I tune in every day. Lucas: Thanks. Anyway, let's get back to the meat of it. The first pillar of the Atlassian architecture contract is what they call boundary definition. Every service has to declare exactly what inputs it accepts and what outputs it produces. No vague interfaces, no hidden side effects. Luna: Is that enforced through code generation or manual documentation checks? Lucas: Code generation. They use a schema registry that all teams must reference. When you define your API, you submit the schema to the registry. The build system then generates client libraries for other teams based on that schema. If you try to change the schema later, the system flags it as a breaking change and requires a version bump. It forces discipline without requiring meetings. Luna: That’s clever. It turns governance into a compile-time error instead of a post-mortem discussion. Lucas: Precisely. The second pillar is data residency. Atlassian realized that half their integration headaches came from teams storing sensitive user data in places that didn't meet compliance standards. The contract now mandates that any personally identifiable information stays within specific encrypted buckets managed by the platform team. Product teams can't just spin up their own S3 buckets or databases for user data anymore. Luna: Did that slow down development initially? Moving data around usually adds latency. Lucas: It added a few hours of setup time per project, but it eliminated the security audit delays that used to stall releases for weeks. So net positive. The third pillar is observability. You can't manage what you can't measure, and the contract requires every service to emit metrics in a standardized format. If a service doesn't send logs to the central logging pipeline, it gets flagged in the weekly health report. Luna: And what happens if a team ignores the flag? Lucas: They lose access to certain high-value features of the platform. Like, they can't use the advanced caching layer or the global load balancer until they fix their observability stack. It’s a carrot and stick approach, but the stick is functional, not financial. Luna: That’s smart. It aligns incentives. Teams want those features, so they comply. Lucas: Exactly. Now, one of the most interesting parts of this whole initiative is how they handled legacy systems. You can't just rewrite everything overnight. Atlassian created a grandfather clause where existing services could operate under old rules for a fixed transition period, usually twelve months. Luna: But during that period, were they still subject to the new security standards? Lucas: Yes. Security never got grandfathered. Only the architectural style and tooling choices were allowed to lag. Once the transition period ended, those legacy services either had to be refactored to meet the new contracts or decommissioned. It forced a natural cull of outdated tech stacks. Luna: I imagine there was a lot of resistance to decommissioning stuff people had spent years building. Lucas: There was. But the platform team offered migration assistance. They provided automated tools to help teams convert their old APIs to the new schema. It wasn't free labor, but it reduced the burden significantly. The message was clear: we will help you move, but you have to move. Luna: That’s a very mature engineering culture. Most companies just tell people to fix it and hope for the best. Lucas: It really is. Another critical component is the feedback loop. Atlassian runs quarterly surveys to gauge developer satisfaction with the platform. If a specific contract rule is causing widespread pain, they prioritize fixing it. Last year, they relaxed the rate-limiting rules for internal services after teams complained it was throttling legitimate batch jobs. Luna: So the contracts evolve based on real usage data. That prevents them from becoming stale. Lucas: Correct. They treat the contracts as a product themselves, with their own roadmap and user base. The platform team has dedicated customer success engineers whose only job is to help product teams navigate the contracts effectively. Luna: Customer success engineers for internal tools. That’s a bold move. Does it scale well? Lucas: Surprisingly, yes. Because the automation handles ninety percent of the enforcement, the humans only need to step in for edge cases and complex negotiations. It keeps the ratio of platform staff to product teams manageable. Luna: What about smaller startups trying to replicate this? Do they need the same level of infrastructure? Lucas: Not necessarily. The principle is scalable. Even a small team can benefit from defining clear API boundaries and enforcing them through CI/CD checks. You don't need a schema registry or customer success engineers. You just need discipline and good tooling. Luna: So the lesson is less about the specific tools and more about the mindset shift toward proactive governance. Lucas: Spot on. It’s about moving from reactive fire-fighting to proactive design. When you bake quality and consistency into the development process, you save enormous amounts of time downstream. Luna: Do you think this model works for open source projects too? Or is it too corporate? Lucas: Open source projects often suffer from the exact problems Atlassian solved. Inconsistent APIs, broken integrations, poor documentation. A lighter version of architecture contracts could definitely help maintainers reduce burnout. Luna: I’d love to see a case study on that. Maybe a future episode? Lucas: Definitely. It’s an area worth exploring further. For now, the Atlassian example shows that you can have both speed and stability if you structure the right guardrails. Luna: And if those guardrails are designed with the developers, not against them. Lucas: Always. The moment you design for conflict, you lose. The moment you design for alignment, you win. Luna: That’s a good place to leave it. What do you think is the biggest hurdle for teams trying to start this journey? Lucas: Probably convincing leadership that investing in platform engineering yields returns. It’s easier to sell new features than new infrastructure. Luna: True. But as Atlassian showed, the infrastructure the feature enabler. Lucas: Exactly. Without the foundation, the house falls down. Thanks for listening.