Part 2 of 3: Architectural Integrity

In Part 1, we explored Engineering Rigor—the discipline of writing clean, secure, compliant, and well-tested code. But great software isn’t just well-formed lines of code; it’s code that fits together into a complete system. That’s where Architectural Integrity comes in.

Architectural Integrity is about designing systems and APIs that are adaptable, robust, and follow established architecture design patterns. It’s about making architectural decisions that outlive any individual engineer or project phase. It’s about documenting those decisions so future engineers understand the “why” behind the “what.” And it’s about knowledge-sharing and collaborating across teams to ensure we’re all building toward a common vision.

Service-Based Architecture

One of the core principles of Architectural Integrity at BTI360 is service-based architecture. Rather than building monolithic applications where everything is tightly coupled, we distribute capabilities across independent, separately deployable services that handle specific responsibilities.

Service-based architecture offers several benefits:

• Agility: Services can be planned and developed independently, allowing teams to move faster
• Maintainability: Small, standalone services are easier to understand, test, and maintain
• Reusability: Services can be reused across different applications
• Scalability: Services can have their own scaling configurations based on their needs
• Interoperability: Services can use different languages or tech stacks

Of course, services introduce complexity. Managing a new service adds overhead, so we’re thoughtful about when to create them. The key is finding the right balance—not too monolithic, not too fragmented. Service decoupling should make sense in the context and scope of each system.

REST API Design

When services need to communicate, they often do so through APIs. At BTI360, our teams design REST APIs to be intuitive, consistent, and maintainable. Services are integrated together via standardized, self-describing interfaces built using API best practices, including logically named endpoints, proper authentication and input validation mechanisms, machine-readable HATEOAS links, and versioning to support backwards compatibility. Data retrieval endpoints are paginated, filterable, sortable, and include links to the next and previous pages. Furthermore, in this modern age of AI, we’ve extended our API design principles to MCP services, providing agentic tooling in the context of the appropriate system.

Event-Driven Architecture

Not all communication between services should be synchronous. For asynchronous cross-service communication and real-time data processing, we typically use event-driven architecture.

In event-driven systems, services communicate by publishing and subscribing to events rather than making direct API calls. When something significant happens in one service (like a user completing a purchase), it publishes an event. Other services that care about that event can subscribe and react accordingly—without the original service needing to know who should be listening.

Event-driven architecture is particularly powerful for systems that need to scale, handle high data volumes, or maintain loose coupling between services.

Data Storage

We choose the right data storage technology for the scale and application needed. For example: blob storage (e.g., S3) for cheap, durable raw content; DynamoDB for extremely fast NoSQL retrieval; Elasticsearch for semantic and lexical search; PostgreSQL for relational data. When you have a data retrieval problem, we find the right solution to maximize effectiveness while right-sizing performance, cost, and availability.

Best-of-Breed Systems

Technology evolves rapidly, and what’s best today might be replaced by something better tomorrow. That’s especially true in newer areas like Generative Artificial Intelligence (GAI), embedding models, and commercial AI/ML capabilities, where the landscape changes monthly.

At BTI360, we design systems to support best-of-breed workflows when appropriate. This means creating abstraction layers in front of third-party integrations so we can support multiple integrations simultaneously. We can then control what integrations are used based on software configurations, or we can have our software automatically choose based on pre-defined criteria.

For example, a best-of-breed translation service may automatically choose from a variety of translation providers based on the language of the input. A best-of-breed GAI service may facilitate interactions with different large language models (LLMs) for different clients or use cases.

This approach gives us greater flexibility, allowing us to take advantage of cheaper or more advanced models.

Documentation

Great architecture is only valuable if the team building the software can understand it. That’s why documentation is a crucial part of Architectural Integrity at BTI360.

Some of the kinds of documentation we find essential include:

Developer Guides: Engineers should have all the information they need to be productive on Day 1. Therefore, it’s vital to have clear, up-to-date documentation that explains how to build, run, test, deploy, monitor, and debug your team’s applications.

Architecture Decision Records (ADRs): Understanding why technical decisions are made—and documenting these decisions—provides the foundation for better decision-making in the future. ADRs are critical to helping teams remember historical decisions and learn from decisions made by others. To this end, for each significant technical decision, we document the context and requirements, the options we considered, the decision that was made, the why behind the decision, and the consequences of that decision (i.e. the trade-offs).

Architecture Diagrams: High-level architecture diagrams like System diagrams, Component diagrams, Cloud Infrastructure diagrams, and Data Flow diagrams help development teams visualize how systems work (and are also great to have handy for a presentation or report).

The key to good documentation is writing it and maintaining it. As part of each major development effort, we create tickets to write, review, and update relevant documentation.

Knowledge Sharing and Cross-Team Collaboration

Documentation is important, but it’s not enough on its own. Fostering a culture of knowledge sharing and cross-team collaboration allows us to share insights, coordinate efforts, learn about other teams and their capabilities, and ensure critical knowledge isn’t siloed within individuals. Here’s what we recommend:

• Scheduling periodic knowledge sharing sessions—things like brown bags, tech talks, live demos, and cross-team meetings—to help everyone learn more about the applications, user workflows, challenges, and solutions faced across our company
• Encouraging teammates to work on unfamiliar parts of their project so knowledge spreads naturally
• Discussing architecture decisions together as a team and documenting the outcomes of those conversations
• Sharing technical decisions and thought process with other teams

This cross-pollination of ideas makes everyone better and helps us avoid duplicating work across teams.

Architectural Reviews

Before implementing any big technical decision, we conduct architectural reviews with our project’s technical leadership and other relevant teams. These reviews—often informal meetings like Sprint 0s—are opportunities to present requirements, discuss options and trade-offs, and get feedback from senior architects before committing to an approach. Architectural reviews help us:

• Evaluate design decisions against requirements and architectural patterns
• Promote consistency in design and implementation across teams
• Leverage the shared expertise of senior architects and technical leaders
• Catch potential issues early
• Teach more junior engineers how to make good technical decisions confidently
• Spread awareness of the big things that are happening on our projects

Building Systems That Last

Architectural Integrity is about building systems that last. In Part 3 of this series, we’ll discuss Operational Maturity—how we deploy, monitor, and operate these well-architected systems to give our customers the confidence that our software is available, resilient, and capable.

Career Opportunities
Are you looking to join a software company that invests in its teammates and promotes a strong engineering culture? Check out our current Career Opportunities. We’re always looking for like-minded engineers to join the BTI360 team.