Methodology

How Archally helps teams tame digital chaos through blueprint-driven architecture — grounded in Domain-Driven Design, Model-Driven Architecture, and practical change governance.

The Problem

What stays unmodeled stays expensive

Teams building complex digital products face a recurring pattern: architecture knowledge fragments across tools, documents, and people's heads. Diagrams go stale. Requirements drift. Integration contracts exist in Slack threads. Decision rationale lives in the memory of whoever was in the room.

The cost is not dramatic — it is cumulative. Late surprises during testing. Rework after misaligned handoffs. Onboarding that takes months instead of weeks. Audits that become archaeology projects.

The root cause is rarely missing effort. It is fragmented truth — no single place where the current state of the system is visible, queryable, and trustworthy.

The Approach

One model, many outputs

Archally introduces a structured blueprint — a typed, versioned YAML model capturing your system's bounded contexts, operations (commands, events, queries), business rules, quality attributes, and architecture decisions. Every element carries a typed ID (CMD001, EVT001, D001) for traceable cross-referencing across the entire model.

This blueprint is not a diagram. It generates diagrams — along with OpenAPI specs, AsyncAPI contracts, and test expectations — all from a single source. When the model changes, every artifact updates. No manual sync. No version conflicts. No "which diagram is current?"

For the composable schema-suite deep-dive — how the loader merges bounded contexts across verticals, where scoped-ID collisions are caught, and what BCC v5 classification adds — see multi-vertical composition.

Model once, project many

Express bounded contexts, operations, contracts, and rules in one typed YAML model. Generate interactive graphs, Event Storming diagrams, OpenAPI specs, and AsyncAPI contracts as projections — not separate documents that drift.

Documentation as side-effect

Documentation that is separate from design always loses to feature delivery. Archally makes documentation a generated output of the design process, not a competing activity.

Compare before you commit

Express change options as structured blueprint migrations — with diffs, rationale, and point-in-time snapshots. The Blueprint Viewer shows as-is and to-be states side by side, so stakeholders see consequences before committing delivery effort.

Foundations

Built on proven methods

Archally does not invent methodology from scratch. It combines proven practices into a practical workflow — taking the rigor of enterprise architecture and making it usable in real delivery teams.

Domain-Driven Design

Bounded contexts, aggregates, domain events, commands, and queries form the vocabulary of every blueprint. The schema supports 30+ entity types — from business concepts to infrastructure resources — ensuring the model reflects how the business thinks, not just how the code is organized.

Model-Driven Architecture

A formal model generates implementation artifacts — OpenAPI 3.1 specs, AsyncAPI 3.0 contracts, OpenRPC definitions, and JSON Schema components — with semantic consistency guaranteed by the model, not by manual effort. The Contract Generator produces these from blueprint operations automatically.

Event Storming & Collaborative Modeling

Workshop techniques for extracting tacit knowledge from teams. The Event Storming Viewer translates blueprint models into DDD Crew-style diagrams at three levels — Big Picture, Process, and Software Design — so business stakeholders and developers collaborate on the same visual language.

Architecture Decision Records

Every significant decision is captured with context, options considered, and rationale as a typed entity (D001, D002...) stored alongside the blueprint. Decisions link to the goals and risks that motivated them — audits become evidence retrieval, not investigation. See design-time governance for the ADR + BD### entity model, evidence_refs, and time-travel.

The Lifecycle

From workshop to living system

A blueprint is not a one-time deliverable. It evolves with the system it describes. The lifecycle follows a practical progression:

Discover

Extract existing knowledge through collaborative workshops. Map domains, events, dependencies, and contracts. Surface what is tacit and resolve ambiguities.

Model

Encode the discovered reality as a structured YAML blueprint — bounded contexts, operations, rules, quality attributes, user stories, and decisions — stored in Git alongside your code. The model becomes the single source of truth for the system's architecture.

Generate

Produce interactive diagrams (Blueprint Viewer, Event Storming Viewer), OpenAPI 3.1 specs, AsyncAPI 3.0 contracts, OpenRPC definitions, and JSON Schema components directly from the model. One source, many consistent outputs.

Evolve

When the system changes, express the change as a structured migration — add, modify, or delete operations on any entity, with diffs, rationale, and point-in-time snapshots. Regenerated artifacts carry changelogs. The blueprint stays current because it is how changes are planned.

Honest Positioning

How this differs from what you have

Most teams already have some form of architecture documentation. The question is whether it is trustworthy, current, and actionable.

Wikis & Confluence

Good for prose. Bad for structured architecture knowledge. Pages go stale because updating them is a separate activity from doing the work. Archally generates documentation as a side-effect of modeling.

Miro / Draw.io / Whiteboards

Great for workshops and brainstorming. Terrible for long-lived documentation. Diagrams are not connected to the system they describe. Archally diagrams are projections of a live model.

Enterprise Architecture Tools

Powerful but heavyweight. Often adopted at the governance layer and ignored by delivery teams. Archally is designed to be used by the people who build the system, not just the people who govern it.

Structurizr / C4 Model

Good for visualization of software architecture. Archally goes further — it models business domains with 30+ entity types, generates executable specifications (OpenAPI, AsyncAPI), and tracks change as structured migrations with impact analysis and point-in-time snapshots.

Explore the Approach

See how blueprint-driven practices work on real systems, or discuss how they could apply to your team's challenges.

See demos Discuss your scenario