Single Source of Truth: Organization-Level Systems You Define Once and Use Everywhere

Here's a pattern that shows up in every organization past a certain size. Team A documents their architecture. They add a box for the Authentication Service — name, description, technology stack. Team B does the same thing in their project. So does Team C. Three projects, three separate definitions of the same system, each slightly different. One says "Auth Service," another says "Authentication Platform," the third says "Identity Provider." Same system. Three names. Three descriptions that emphasize different things. No connection between them.

Six months later, the authentication team renames the service and updates its technology stack. The change propagates to zero of those three diagrams. Each project's version of reality quietly diverges from the actual system and from each other.

This is the consistency problem. It doesn't come from negligence. It comes from architecture tools that treat every project as an island. If the only way to represent a system is to create it inside a project, then every project that touches that system gets its own copy. Copies drift. That's what copies do.

We built organization-level systems to fix this.

Systems That Belong to the Organization, Not a Project

Archyl now supports two scopes for C4 systems. Project-scoped systems work exactly as before — they belong to a single project and live on that project's diagram. Organization-scoped systems belong to your organization. They exist independently of any project, and any project can link to them.

The distinction matters because it mirrors how real architecture works. Some systems are internal to a project — a microservice that only exists within that bounded context, a database that serves a single application. Those belong to the project. But many systems cut across project boundaries — shared infrastructure, platform services, third-party integrations, core business capabilities that multiple teams depend on. Those belong to the organization.

When you create an organization-level system, you're making a statement: this system is a shared reality. Its name, description, technology, and tags are defined once. Every project that references it sees the same definition.

How It Works

Creating Organization Systems

Organization systems are created from a dedicated section in the platform. You define the system the same way you would in a project — name, description, type (software system, external system, or person), technology, and tags. The difference is that it isn't tied to any project. It lives at the organization level, visible to every team.

Linking Systems to Projects

When you're working on a project diagram and want to reference an organization system, you link it. A modal shows you all available organization systems with search. Toggle the ones you need — they appear on your diagram immediately.

Linked systems behave like native systems on the diagram. You can position them wherever makes sense for that project's layout. You can create relationships to and from them. You can drill down into their containers and components. The only difference is that the system's core identity — its name, description, technology — comes from the organization definition, not from the project.

Each project stores its own position for the linked system, so the same system can sit in different places on different diagrams. The layout is per-project. The definition is shared.

Unlinking

If a project no longer depends on a shared system, unlink it. The system disappears from the project's diagram but continues to exist at the organization level and in every other project that references it. No data is lost. No other team is affected.

Why This Matters

Consistency Without Coordination

The traditional approach to keeping architecture documentation consistent is process. You write naming conventions. You hold review meetings. You ask people to check what other teams called the same system. Process works until it doesn't — which is usually the moment someone is in a hurry, which is most moments.

Organization-level systems make consistency structural. There's one definition. Projects reference it. When someone updates the system's description or technology stack, every project that links to it reflects the change automatically. No Slack messages. No "please update your diagram." The architecture stays consistent because the architecture model enforces it.

Accurate Cross-Project Dependencies

When multiple projects link to the same organization system, the platform knows about those connections. This isn't a visual convention — it's a data relationship. Impact Radar can trace dependencies through organization systems across project boundaries. If you analyze the impact of changing a shared platform service, you see every project that depends on it, because they all link to the same system rather than maintaining independent copies.

Onboarding and Discovery

New team members joining a project see the same system names, descriptions, and technology labels that every other project uses. There's no "which Auth Service is this?" moment. The organization system carries its identity with it, and that identity is the same everywhere.

Reduced Duplication

Beyond the consistency benefit, organization systems simply reduce work. Instead of every project independently documenting the same infrastructure — the message broker, the API gateway, the identity provider, the monitoring stack — you define each one once. Projects link to them in seconds. The time spent recreating the same boxes with slightly different labels goes to zero.

What Changes in the Data Model

Under the hood, the C4 system entity now supports two mutually exclusive scopes. A system belongs to either a project or an organization — never both, never neither. This is enforced at the database level with a constraint.

A separate link table tracks which projects reference which organization systems, along with the per-project position on the diagram. This means the same system can appear on ten different project diagrams, each positioned differently, each with its own set of relationships to project-local elements.

When you load a project's C4 model, the platform fetches both the project's own systems and any organization systems linked to it. They merge seamlessly on the diagram. The distinction is visible in the UI — organization systems carry a subtle indicator showing they're shared — but functionally, they participate in the architecture model the same way as project systems.

The Bigger Picture

This feature is part of a broader direction: making Archyl work the way organizations actually work. Architecture isn't a collection of independent projects. It's a network of shared systems, platform capabilities, and cross-cutting concerns. The tools should reflect that.

Organization-level systems are the first step toward a model where shared infrastructure is documented once and referenced everywhere. Combined with the Global Architecture view for cross-project visualization and Impact Radar for cross-project dependency analysis, you now have a platform that understands your architecture as a connected whole — not as a set of disconnected diagrams.

Getting Started

Organization-level systems are available now. Head to the organization section, create your shared systems, then link them into any project from the diagram view. If you've already documented the same system across multiple projects, this is your chance to consolidate — define it once, link it everywhere, and let the copies retire.

Your architecture has a single source of truth. Your documentation should too.

For more on cross-project architecture, see Global Architecture and Real-Time Collaboration. To understand how changes to shared systems propagate, try Impact Radar. For governed changes to shared systems, explore Architecture Change Requests.