CodeCharta: turning a codebase into a 3D city you can argue about

The pitch: show the team what you mean

The tagline is see how your code is built, and what it is about. The README puts it in a paragraph: CodeCharta turns any codebase into a 3D city of metrics, a map of its domain language and a graph of its dependencies, and the stated purpose is to find the hotspots in minutes and show your team what you mean instead of explaining it.

That last clause is the actual product decision. Every architecture diagram tool in this space produces a diagram. The difference CodeCharta claims is that the output is explorable by the people in the conversation rather than read by whoever drew it, and the three views exist to make that work in practice.

The repository description is more of a mission statement. It is a visualization tool that transforms complex software architecture and code metrics into interactive, customizable visual maps, so that everyone can communicate and analyze your codebase, with the goal of improving code quality, maintainability and architectural decisions.

The project is maintained by MaibornWolff GmbH, which the package.json confirms with the author field and a contact address, and the licence is BSD-3-Clause with the text in LICENSE.md. The homepage is codecharta.com, and the primary language is Kotlin, with the front end in TypeScript and Angular, which the topic list names alongside the concepts the tool works with: 3d-map, city-map, code-visualization, analyzer, importer, parser, metrics and static-code-analysis.

The releases show the architecture of the project. There is a Visualization release 2.9.0 and an Analysis release 2.2.0, both on 2026-10-20, and a Visualization release 2.8.0 from 2026-10-05. The two halves are versioned and shipped independently, and the badges in the README mirror that, with separate version badges and separate release branches for analysis and visualization.

That split is a deliberate architecture rather than a packaging accident, and it shapes everything about how you use the tool. The analysis half produces a map file, and the visualization half is a web application that reads it.

The metric view: a skyline where size, complexity and churn compound

The first of the three views is the one the project leads with, and the mapping is direct. Every file is a building. You pick what area, height and color mean: lines of code, complexity, number of commits, number of authors, function length and dozens more. The files that need your attention stick out of the skyline.

Three dimensions, three questions. The horizontal extent of a building is the metric you call area, its height is a second metric, and its colour a third. Because the three are independent, the interesting cases are the corners of that space, and the README names them.

Hotspots are big and tall and red, which is to say large, complex and changed all the time. That is a compound signal rather than a single one, and it is the reason the view is worth building rather than just colouring files by size. A large file that nobody touches is a different problem from a small file that changes every week, and the map distinguishes them by construction.

Knowledge silos come from colouring by number of authors, to find code only one person understands. That is a metric most tools do not collect, because it needs the full commit history rather than just the current source, and it is one of the more actionable things a team can find.

Temporal coupling connects files that always change together, even without an import. Edges here are not dependency edges, they are co-change edges derived from the git history, so the map shows pairs of files that are logically related but have no import between them. A refactoring that misses one of a coupled pair is a bug waiting to happen, and the coupling graph is how you find those pairs.

There is also a filter and focus layer, with search, flatten or exclude files, and rules such as complexity > 50. The scenarios feature gives built-in and saved presets for complexity, code smells, authors and more, so a common question becomes a saved view rather than a filter you rebuild each time.

And then the one that gets a laugh out of reviewers: 3D print, to export the city as a 3D model and put your codebase on the table. A team that has spent two hours arguing about a refactoring can settle it by handling the thing.

The domain view: the vocabulary of the business rather than the framework

The second view answers a different question, and it is the one the project describes as reading what the code is about.

The domain language parser reads identifiers, comments and strings, filters out keywords and technical noise, and scores every word by frequency and TF-IDF. The result is described as the vocabulary of your business, not of your framework. The TF-IDF part is what makes that claim work, because a word that appears in every file is a word that carries no information about any particular file.

What you get from it is a word cloud per folder, so you can pick any file or folder and see the words it is written in. And the more useful direction, where does a word live, opens a word and gives its breakdown over the file tree. The README's example is that 95% of the occurrences of the word commit are in the analysis folder, where the git log parser is. That is the tool telling you that a term which sounds like business vocabulary is in fact infrastructure vocabulary, and doing it by frequency rather than by anybody's opinion.

Phrases are handled as well as words, with bigrams like commit hash or merge commit, because the compound terms are usually the meaningful ones.

And the two views are joined, so from any node you can show in Metrics or show in Domain. The domain explorer and the metric city are two readings of the same tree rather than two separate tools, which is what makes it possible to say a file is both complex and about a specific business concept.

The filtering that is applied before scoring matters for the quality of the result. Identifiers, comments and strings are all read, which means the vocabulary includes the words that appear in prose as well as in code, and keywords and technical noise are filtered out. Without that filter the word cloud would be dominated by the language's control words, and with a naive frequency count the most common word would simply be the most common one.

The dependency view: which edges point the wrong way

The third view is the most immediately legible, and it is the one that produces the argument you can have in a meeting.

The dependency parser reads the imports of your code, and the graph stacks every folder by level, so what a box depends on lies below it. In a cleanly layered codebase every edge points down, so the ones that do not stand out.

That is the whole design principle, and it is why the graph is laid out by level rather than by force-directed physics. A force-directed graph is prettier and tells you less, because position no longer means anything. A layered graph means the picture is a claim about your architecture, and you can check the claim by looking.

From there the features are about inspection. Cycles and upward dependencies are marked with red edges and badges, so the two ways a layering is broken are visible directly. Double-click a folder to see its contents and a file to see its declarations. Selecting a box lists its dependencies in both directions, under Uses and used by, which is the question you ask when you want to know what a change will ripple into.

The layout can be by folder or by the packages the code declares, and that choice matters more than it sounds. Arranging by package shows you the module boundaries the code believes in, while arranging by folder shows you the directory layout, and for a repository where the two have drifted apart, seeing them side by side is a finding in itself.

Taken with the metric view, the three views answer three questions that a team actually argues about. The metric view says where the risk is concentrated. The dependency view says whether the structure is sound. The domain view says what the thing is for. The README's claim is that showing your team what you mean is faster than explaining it, and the three views are the mechanism for that.

The two halves: an analysis tool and a web app that reads a map file

The project is split into an analysis component and a visualization component, and understanding that split explains how you actually use it.

The analysis side is the Kotlin half. It parses a repository, gathers metrics and dependencies, and writes out a map file in the CodeCharta JSON format, with the schema described in CC_JSON_SCHEMA_CHANGELOG.md. The visualization side is the TypeScript and Angular half, a web application that loads one or more map files and lets you move through them.

The demo link in the README shows the format in practice, loading a codecharta_visualization.cc.json.gz and a codecharta_analysis.cc.json.gz together, with a currentFilesAreSampleFiles parameter. The staging demo shows the same files with area, height, colour and edge parameters spelled out in the URL, using rloc as the area metric, functions as the height metric, sonar_complexity as the colour metric and dependencies as the edge type. That is worth noting for its own sake, because the visualization state lives in the URL, so a particular view of the map is a link you can paste into a ticket.

The repository layout matches the split. There is an analysis/ directory, a visualization/ directory, a docs/ directory in dev_docs/, a sample-projects/ directory, a gh-pages/ directory, an assets/ directory, and a logo/ directory. There is also a plans/ directory and a CODE_QUALITY.md, which is a sign of a project that documents its own standards rather than assuming them.

The tooling is modern and modest. The root package.json is a small workspace-level file whose description calls itself a placeholder, with scripts for format, format:check, prepare and commitlint, and a prettier block that sets no semicolons, double quotes, no trailing comma and arrow parens avoided. The devDependencies are biome, commitlint, badge-maker, husky and lint-staged, and the lint-staged configuration runs the format script on every staged file. A husky directory, a biome.json, a commitlint.config.js and a renovate.json complete the set, with mise.toml for tool versions and an .editorconfig and .gitattributes for line endings.

The engines field requires node >=22.19, which is the only hard toolchain constraint stated in the package file.

Running it locally, and the quality gates in the build

The docker-compose file in the repository root shows the intended local setup, and it is a three-service arrangement.

version: "3"
services:
    sonar:
        image: sonarqube:10.7.0-community
        container_name: sonar
        ports:
            - "9000:9000"

    visualization:
        image: codecharta/codecharta-visualization
        build: visualization/.
        container_name: codecharta-visualization
        ports:
            - "9001:80"

    analysis:
        user: "1000:1000"
        image: codecharta/codecharta-analysis
        container_name: codecharta-analysis
        tty: true
        environment:
            - SONAR_HOST=http://sonar:9000

SonarQube runs on port 9000, the visualization web app on port 9001, and the analysis container is configured to talk to Sonar at the internal address, with a tty enabled because it is an interactive tool and a non-root user id because the analysis container writes files.

That Sonar integration is the part with the most depth, and it is the reason the tool can offer metrics like sonar_complexity as a colour option. CodeCharta's analysis half can gather metrics from SonarQube, and the visualization can colour by them, which is what makes it possible to combine a static analysis view with the commit history view in one picture.

The quality story is visible in the badges at the top of the README. There is a Quality Gate Analysis badge and a Quality Gate Visualization badge, both pointing at SonarCloud dashboards, one for the analysis repository and one for the visualization repository. Two separate quality gates for two separate codebases, each enforced on the main branch, plus separate release branches for analysis and visualization with their own check-run badges.

The separate versioning is the practical detail to plan around. Analysis release 2.2.0 and Visualization release 2.9.0 came out on the same day, 2026-10-20, and the two use different version lines, so pairing them is a decision rather than a default. A map file produced by one analysis version is a thing the matching visualization version understands, and because the schema has its own changelog in CC_JSON_SCHEMA_CHANGELOG.md, the file format does move.

The repository also ships a license_policy.json, which is the kind of file a project needs when it has a policy about which licenses may appear in its dependency tree, and the last push was on 2026-10-20, the same day as the two releases.

Editorial conclusion

Adopt CodeCharta if you need to communicate the shape of a codebase to people who will not read the code, because the pitch is that you show your team what you mean instead of explaining it, and the metric, domain and dependency views answer three different questions about the same repository. Do not adopt it expecting a static analysis report, since the value is in the interactive map rather than in a finding list. Before you generate anything, note that the analysis and visualization halves version separately, with ana-2.2.0 and vis-2.9.0 released on the same day, so pair the two deliberately, and remember the map file is the artefact you share rather than the tool that made it.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. MaibornWolff/codecharta on GitHub
3. Project website
4. README
5. Releases