DEV Community: Basalt

From BASALT to CLAUDE, CHATgpt, Gemini

Basalt — Sun, 11 Oct 2026 08:23:05 +0000

From System Architecture to Working Code: Introducing Doc View in Basalt

One thing I realised while building Basalt is that generating a system architecture is only half the problem.

The other half is getting your coding agent to understand it.

You might create a detailed architecture in Basalt, but when you move to Claude, ChatGPT, Google Antigravity, or another AI coding agent, you still have to explain what you built, how the components interact, what the intended workflows are, and what needs to be implemented.

That creates unnecessary friction between designing a system and actually building it.

So, we decided to make that transition simpler.

Introducing Doc View

Doc View turns your Basalt architecture into a structured, ready-to-use prompt for your AI coding agent.

Here's how it works:

Design your architecture in Basalt, just as you normally would.
Switch to Doc View to get a prompt generated from your architecture.
Copy the prompt and add any project-specific requirements, constraints, or instructions.
Paste it into your coding agent and start building.

That's it.

No need to manually translate every component, connection, and architectural decision into a lengthy prompt from scratch.

Why does this matter?

AI coding agents are becoming increasingly capable, but the quality of their output still depends heavily on the context we provide.

A well-defined architecture gives the agent a clearer picture of the intended system before implementation begins.

Instead of starting with a vague description of what you want to build, you can start with an architecture you have already designed and use it as the foundation for implementation.

The goal is simple: reduce the gap between system design and code generation.

What's next?

Doc View is another step towards making Basalt more than an architecture design tool. We want it to become part of the workflow that takes an idea from system design to implementation.

Design the system. Give your coding agent the context. Start building.

Your architecture just became a working system.

Try Basalt: https://basaltarch.io

I'd love to hear how you're currently moving from system architecture diagrams to AI-assisted implementation. What does your workflow look like?

See Basalt's new DEMO video

Basalt — Wed, 23 Sep 2026 10:04:14 +0000

Basalt Is Becoming More Than an Architecture Generator

When we started building Basalt, the idea was relatively simple:

make system architecture easier to create.

A few iterations later, that idea has grown into something much bigger.

Basalt is becoming a place where architecture can be generated, explored, validated, refined, and eventually governed.

And that's the direction we're taking.

From a blank canvas to an intelligent workspace

Architecture traditionally starts with a blank screen.

Boxes.

Arrows.

A lot of thinking.

A lot of documentation.

A lot of time.

We're trying to change that workflow.

With Basalt, you can start from a requirement, an idea, an existing system, or one of our architecture templates and move directly into a structured environment for designing the system.

The canvas isn't supposed to be the end result.

It's supposed to be the workspace where the system evolves.

We've been building the layers around the architecture

The architecture itself is only one piece.

We've been adding the surrounding layers that make it useful in actual engineering workflows:

Architecture generation

Create structured architectures from requirements and engineering context.

Templates

Start from predefined architectural patterns instead of rebuilding common systems from scratch.

SDE Lens

Look at architecture from the perspective of the developer who has to build, modify, debug, and maintain the system.

Architecture Validator

Evaluate diagrams against structural and architectural rules rather than simply generating them.

Custom rulesets

Allow organizations and teams to define their own architectural constraints.

GRC direction

Move architectural governance closer to the design process instead of treating compliance as something checked at the very end.

And we're continuing to build on top of these layers.

The validator changed the way we think about Basalt

One of the biggest shifts has been realizing that generating an architecture isn't enough.

An AI can generate a diagram.

But then comes the more important question:

Does the architecture actually satisfy the requirements?

That's why validation has become a core part of Basalt.

The workflow starts looking more like:

Design
   ↓
Generate
   ↓
Validate
   ↓
Identify Issues
   ↓
Refine
   ↓
Validate Again

That feedback loop is much more interesting to us than simply producing another pretty diagram.

Architecture should have rules

Different systems have different constraints.

A financial platform isn't designed exactly like an industrial control system.

A cloud-native SaaS product isn't designed exactly like an enterprise ERP environment.

And an Industry 4.0 system introduces another completely different set of considerations.

So we're moving toward architecture that can be evaluated against explicit rules and standards, rather than relying entirely on manual review.

That opens the door to something much larger:

Automated architectural governance.

And then there's Industry 4.0

This is one of the areas we're particularly excited about.

Modern industrial systems increasingly sit across multiple layers:

Physical Systems
      ↓
Sensors / PLCs
      ↓
Edge
      ↓
Industrial Network
      ↓
Cloud / Data
      ↓
Analytics / AI
      ↓
Enterprise Systems

Designing these systems isn't simply about putting components on a canvas.

There are interfaces, dependencies, security boundaries, communication patterns, standards, and operational constraints to consider.

That's exactly the kind of environment where structured architecture and automated validation become increasingly valuable.

Basalt is becoming an architecture operating layer

That's probably the simplest way to describe where we're heading.

Not just:

"Generate me a diagram."

But:

"Help me design, understand, validate and evolve this system."

The architecture becomes a living artifact.

Something engineers can work with.

Something architects can review.

Something organizations can apply rules to.

Something that can evolve as the underlying system evolves.

We're still early

Basalt has gone through multiple iterations already.

Each one has changed something:

The UI.

The architecture engine.

The validation layer.

The developer experience.

The templates.

The governance direction.

And the way we think about what an architecture platform should actually be.

We're still experimenting.

We're still breaking things.

We're still rebuilding parts that looked perfectly fine a week earlier. 😅

But the direction is becoming clearer.

Basalt isn't just about drawing architecture anymore.

It's about making architecture computable.

And that's the part we're excited about.

More soon. 🌋

Basalt #SoftwareArchitecture #SystemDesign #DevTools #Engineering #CloudArchitecture #AI #GenerativeAI #Architecture #Industry40 #GRC #SoftwareEngineering #DeveloperTools

I Built Basalt to Turn Any GitHub Repository Into an Architecture Diagram in Seconds

Basalt — Sat, 12 Sep 2026 06:29:13 +0000

There is a strange ritual that almost every software engineer eventually becomes familiar with.

You get handed a new repository.

Someone says:

“It’s pretty straightforward. Just take a look at the code.”

So you open the repository.

Then the README.

Then package.json.

Then src/.

Then some random utils folder.

Then you find a service calling another service.

Then you discover an API.

Then you find a database layer.

Then there is a Docker file.

Then some environment variables.

Then another service.

And somewhere around the 45-minute mark, you realize you are still trying to answer the most basic question:

“What does this system actually look like?”

I wanted to eliminate that entire first phase.

So I built Basalt.

The Problem Isn't Reading Code. It's Building the Mental Model.

Modern repositories aren't small.

A production application can contain:

Frontend applications
Backend services
APIs
Databases
Queues
Workers
Authentication systems
External integrations
Infrastructure
CI/CD pipelines
Configuration layers
Shared libraries
Internal services
Cloud resources

And the README rarely tells you how all of those pieces actually interact.

Even when documentation exists, it can quickly become outdated.

The source code, meanwhile, contains the real relationships.

But understanding those relationships manually takes time.

You have to explore the repository and construct a mental graph:

Component A → calls Component B → which uses Service C → which writes to Database D → while Worker E consumes Queue F.

That mental graph is essentially the architecture.

The problem is that engineers are often forced to build that graph manually.

Basalt automates the first pass.

Give Basalt a Repository

The idea is intentionally simple.

Give Basalt a GitHub repository.

It analyzes the repository and tries to understand what is actually there.

Instead of asking:

“What files exist?”

the system tries to answer:

“How does this system work?”

It looks at the structure of the codebase, identifies important components, analyzes relationships, and turns that understanding into an architectural representation.

The result is something you can use as a starting point for understanding the system.

In seconds.

From Repository → Architecture

The workflow is basically:

GitHub Repository
       ↓
Repository Analysis
       ↓
Codebase Understanding
       ↓
Component Detection
       ↓
Relationship Analysis
       ↓
Architecture Generation

The important part is the middle.

A repository isn't just a collection of files.

It is a system of relationships.

Files depend on other files.

Services communicate with other services.

Applications interact with databases.

Workers consume queues.

APIs expose functionality.

Infrastructure defines how everything runs.

Basalt is designed around understanding those relationships rather than simply generating a pretty diagram from folder names.

Why Not Just Read the README?

Because the README isn't always the source of truth.

A README might say:

This application consists of a frontend,
backend and database.

Great.

But what happens when you actually start working on the repository?

You discover:

Frontend
   ↓
API Gateway
   ↓
Auth Service
   ↓
User Service
   ↓
PostgreSQL

Order Service
   ↓
Message Queue
   ↓
Background Worker
   ↓
Payment Provider

And perhaps there are three additional internal services that aren't mentioned anywhere in the documentation.

This is common.

Documentation describes what developers intended to communicate.

Code reveals what the system actually does.

That distinction matters.

The First Five Minutes of a New Codebase

I think there is a larger problem here.

When engineers join a project, switch teams, contribute to open source, review an unfamiliar repository, or inherit an existing system, a significant amount of time is spent on codebase archaeology.

You aren't implementing anything yet.

You aren't fixing anything yet.

You are just trying to understand.

And that understanding is expensive.

You might spend an hour figuring out something that could have been communicated visually in a few minutes.

Architecture diagrams are extremely effective for this because humans are good at understanding systems spatially.

Seeing:

Client
  ↓
API
  ↓
Service
  ↓
Database

is fundamentally different from reading:

src/
 ├── api/
 ├── services/
 ├── models/
 ├── workers/
 ├── database/
 └── utils/

The second tells you where things are.

The first tells you how they relate.

Basalt is focused on the second problem.

Architecture Before You Start Coding

There is another use case I'm particularly interested in.

What if architecture wasn't something you created after understanding the repository?

What if it was the first thing you generated?

Imagine onboarding to a new project.

Instead of:

Clone repo
↓
Read README
↓
Explore folders
↓
Read files
↓
Trace dependencies
↓
Understand services
↓
Finally understand architecture

you could start with:

Clone repo
↓
Generate architecture
↓
Understand system
↓
Start working

That changes the starting point.

You begin with a map.

Then you use the code to explore the map.

It's Not Just About Diagrams

One thing I don't want Basalt to become is another tool that takes a repository and produces a beautiful box-and-arrow diagram that doesn't actually help anyone.

The diagram is only the output.

The real problem is system understanding.

A useful architecture representation should help answer questions like:

What are the major components?
Where does the application start?
Which services communicate with each other?
What are the external dependencies?
Which databases are being used?
Where are the likely boundaries?
What infrastructure is involved?
Which components appear tightly coupled?
What does the request/data flow look like?

That's much more valuable than simply drawing boxes around folders.

The Bigger Idea

The feature started with architecture.

But the larger idea is making repositories understandable to humans faster.

Repositories contain an enormous amount of information.

The problem isn't that the information isn't there.

The problem is that the information is distributed across:

Code
Configuration
Dependencies
Infrastructure
Documentation
File structure
APIs
Deployment definitions
Database models
Service relationships

An engineer has to mentally combine all of that.

That's a lot of cognitive work.

What if software could do the first synthesis for you?

That's what I'm exploring with Basalt.

Architecture as the Interface to a Codebase

I increasingly think architecture could become an interface layer between humans and large codebases.

Instead of immediately navigating thousands of files, you first understand the system at a higher level.

For example:

                    ┌──────────────┐
                    │   Frontend   │
                    └──────┬───────┘
                           │
                           ▼
                    ┌──────────────┐
                    │   API Layer  │
                    └──────┬───────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │  Auth    │ │  Users   │ │  Orders  │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │            │            │
             └────────────┼────────────┘
                          ▼
                   ┌──────────────┐
                   │   Database   │
                   └──────────────┘

Then you can zoom into the part you actually care about.

Architecture becomes a navigation system for the repository.

Why I Built It

I've spent enough time opening unfamiliar repositories and thinking:

“Where the hell do I even start?”

That feeling is particularly painful when the repository is large, poorly documented, or inherited from another team.

You shouldn't need to spend your first day reconstructing the architecture manually.

You should be able to get an initial understanding almost immediately.

That's the problem Basalt is trying to solve.

And This Is Only the Beginning

Generating an architecture diagram is useful.

But I don't think that's where this should stop.

Once a system can understand a repository's architecture, you can start asking much more interesting questions.

For example:

“Where are the major dependencies?”

“What happens if I change this service?”

“Which components are tightly coupled?”

“Where are the architectural bottlenecks?”

“Which services communicate with this database?”

“What would break if this API changed?”

“Does the implementation actually match the architecture?”

That moves the idea from:

architecture generation

toward:

architecture intelligence.

And that's the direction I'm interested in taking Basalt.

Try It

If you have a GitHub repository you've been putting off understanding, throw it into Basalt.

Repository in. Architecture out.

No spending an afternoon excavating a README.

No manually tracing the entire codebase before you know where the important pieces are.

Just a starting map of the system in seconds.

🔗 Basalt: basaltarch.io

I'd genuinely love feedback from engineers who work with large codebases:

What is the first thing you want to know when you open an unfamiliar repository?

That answer might shape what Basalt builds next.