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.
Top comments (0)