Code2UML AI: The Code Determines the Architecture, Not the AI

Shraddha Khetmalis — Mon, 05 Oct 2026 06:05:41 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

🚀 What I Built

I built an AI code explainer that doesn't let the AI decide what the architecture is.

Rahul is a friend and a regular collaborator on my projects. While working through an unfamiliar Spring Boot codebase, he ran into a problem that has nothing to do with syntax or writing code.

He couldn't easily see the bigger picture.

Which controller talks to which service?
Which repository sits behind that service?
Which entity is being used?
What endpoints does the application expose?
Where does a particular class fit in the overall structure?

In a small project, you can trace those relationships manually. In a larger Java codebase, that quickly becomes tedious, especially when you are seeing the project for the first time.

My first idea was straightforward: build a chatbot that reads the repository and explains it.

Then I changed the design.

I wanted the architecture to be derived from the source code first, rather than reconstructed by an LLM from raw code.

So I built Code2UML AI.

The system accepts a Spring Boot .zip, analyzes the Java source using deterministic static analysis, converts the extracted relationships into structured architecture data, and renders that data as interactive Mermaid diagrams.

An optional Gemma-powered assistant then answers questions about the architecture.

The code determines the architecture. Gemma explains it.

That separation is the core idea behind the project.

I gave the tool to Rahul to test the actual goal: could it make an unfamiliar Spring Boot project easier to understand?

The success criterion wasn't a flashy interface.

It was much simpler:

Can someone go from “I don't understand this codebase” to “I can see how these pieces fit together”?

That's what Code2UML AI is built to help with.

💻 Try the Demo

🔗 Live demo: https://code2uml.onrender.com/

The public version is deployed on Render using Hacktoberfest Render credits.

⚠️ Privacy note: This is a public deployment. Use the included sample project for evaluation. Do not upload proprietary or sensitive source code to the public instance. For private projects, run Code2UML locally and use a local model endpoint.

Try it in about a minute

Click Try Sample Project.
Review the Architecture Observations panel.
Open the Endpoints tab.
Explore the Controller → Service → Repository → Entity relationships.
Ask the Architecture Assistant questions such as:

Which service handles UserController?
What repository is connected to UserServiceImpl?
Is there an authentication component?
1. Compare the answer with the generated architecture and the sample source code.

The sample project contains:

UserController
UserService
UserServiceImpl
UserRepository
User
UserDTO
DemoApplication

The fixture produces 7 detected types, 6 packages, 4 REST endpoints, and 10 deduplicated architectural relationships.

Those expected results are also covered by the automated tests.

Screenshots

The dashboard with the sample project loaded. It shows the detected types, REST endpoints, relationships, rule-based observations, and analysis coverage. Coverage means the files were parsed; it is not a guarantee that every relationship was recovered.

The layered architecture view showing controllers, services, repositories, entities, and DTOs alongside the Architecture Assistant. The selector can switch between the full architecture and a focused controller view.

The UML class view generated from the extracted architecture JSON, including stereotypes, fields, methods, realization edges, and dependency relationships.

The endpoint catalog showing HTTP method, route, controller, handler method, and return type.

The Architecture Assistant identifies which engine produced each answer. The authentication question returns “not detected” rather than inventing a component, and the response is limited to the analyzed project.

The Copy Mermaid action lets you export the generated diagram directly into a README or other documentation.

🔗 Source Code

shraddhaa09 / code2uml

⚡ Code2UML AI

Deterministic Spring Boot architecture visualizer with an optional Gemma-powered assistant. The code determines the architecture. Gemma explains it.

Live demo: code2uml.onrender.com · Source: github.com/shraddhaa09/code2uml

⚠️ The hosted demo is a public deployment. Use the built-in sample project and do not upload proprietary or sensitive source code. For private code, run it locally (see Quick Start).

Problem

Understanding a medium-to-large Spring Boot codebase is slow. Developers trace dependency-injection graphs by hand, hunt for REST endpoints across controllers, map JPA entities to repositories, and draw architecture diagrams manually. Many teams also cannot send proprietary source code to a hosted LLM, which rules out the obvious "paste it into a chatbot" shortcut.

…

View on GitHub

The repository includes the backend, frontend, sample Spring Boot project, automated tests, and local setup instructions.

🏗️ How Code2UML AI Works

The system is built around one architectural rule:

Static analysis establishes the structure. AI explains that structure.

The pipeline is:

Spring Boot ZIP
      ↓
Safe archive extraction
      ↓
Deterministic Java analysis
(javalang AST + tokenizer/regex fallback)
      ↓
Structured architecture JSON
      ↓
Mermaid architecture + UML diagrams
      ↓
Endpoints + observations + component catalog
      ↓
Architecture Assistant
      ↓
Deterministic engine OR Gemma

1. Safe ZIP extraction

The FastAPI backend accepts a Spring Boot project as a ZIP archive.

Before extraction, the archive is validated against unsafe conditions such as path traversal and oversized or suspicious archives. Files are extracted into a temporary working directory before analysis.

The upload pipeline also enforces an archive-size limit.

The goal is simple: make repository analysis convenient without treating an uploaded archive as inherently trustworthy.

2. Deterministic Java analysis

The analyzer looks for architectural signals directly in the source code.

It can identify things such as:

@RestController
@Controller
@Service
@Repository
@Entity
@Table
DTOs
Constructor injection
Field injection
REST endpoint mappings
Repository-to-entity relationships

The primary parser uses javalang for Java AST analysis.

When the AST parser cannot handle a particular source construct, the analyzer can fall back to deterministic token and regex-based parsing.

There is no LLM in this stage.

That is important because the architecture should not depend on an AI model guessing what a class probably means.

3. Structured architecture

The extracted information is normalized into structured JSON.

A simplified example looks like this:

{
  "roles": {
    "controllers": ["UserController"],
    "services": ["UserServiceImpl"],
    "repositories": ["UserRepository"],
    "entities": ["User"],
    "dtos": ["UserDTO"]
  },
  "dependencies": [
    {
      "source": "UserController",
      "target": "UserService",
      "type": "injected"
    }
  ],
  "endpoints": [
    {
      "method": "GET",
      "path": "/api/users",
      "controller": "UserController"
    }
  ]
}

This JSON becomes the structured representation used by the rest of the application.

Instead of asking a model to rediscover the architecture every time someone asks a question, the application can work from the same extracted representation.

4. Turning structure into diagrams

The architecture JSON is transformed into Mermaid representations for both architectural and UML-style views.

The frontend supports:

Interactive diagrams
Pan and zoom
Full and focused views
Endpoint inspection
Component inspection
Raw JSON inspection
Mermaid copying

For larger graphs, the application can limit displayed edges so that the visualization remains usable rather than turning into an unreadable wall of connections.

5. Rule-based architectural observations

Not every useful insight needs AI.

Code2UML AI also generates deterministic observations from the extracted structure.

Examples include:

Entities exposed directly through controllers
Skipped architectural layers
Service interfaces without implementations

These checks run without an LLM.

That means the core architecture analysis remains useful even when no AI model is configured.

6. The Architecture Assistant

Gemma is used at the explanation layer.

The assistant can answer architecture-focused questions such as:

“Which service is connected to UserController?”

“What repository does UserServiceImpl use?”

“Is there an authentication component?”

There are two ways to answer those questions.

The deterministic engine handles supported architecture queries directly from the extracted structure.

When Gemma is configured, it receives the structured architecture as context and generates a natural-language response.

The important distinction is that Gemma is not asked to reconstruct the entire repository from raw source code.

The architecture has already been extracted.

The model is explaining the result.

                 ┌──────────────────────┐
                 │  Structured Analysis │
                 │        JSON          │
                 └──────────┬───────────┘
                            │
                ┌───────────┴───────────┐
                ↓                       ↓
      Deterministic Engine          Gemma
                ↓                       ↓
       Architecture answers    Natural-language answers

When Gemma is unavailable, the deterministic engine remains available for supported questions.

7. Coverage and diagnostics

Static analysis is not perfect, so the application exposes parsing diagnostics instead of pretending that every file and relationship was understood completely.

The project tracks successful parsing, fallback parsing, failed files, and other analysis information.

This makes an important limitation visible:

If the analyzer cannot confidently extract something, the system should expose that limitation rather than silently presenting an incomplete graph as a complete one.

🧪 Testing

The repository currently contains a 21-test suite covering unit, integration, and browser-level behavior.

The tests cover areas including:

Golden sample project analysis
Expected type detection
Relationship deduplication
REST endpoint extraction
Mermaid generation
Full and default diagram views
Controller endpoint limits
Gemma grounding
Database-vendor detection
Missing-component responses
Direct and indirect dependency questions
Privacy boundaries
Playwright browser flows
Sample-project loading
Chat Q&A
Empty ZIP handling
Corrupt ZIP handling
Missing Java-file handling

The sample fixture is specifically checked for:

7 detected types + 10 deduplicated relationships + 6 packages + 4 REST endpoints

These tests are meant to verify known behavior on controlled fixtures.

They are not presented as a benchmark for large production repositories.

⚠️ Known Limitations

Code2UML AI is a static-analysis tool. It is not a complete Java program-understanding system.

There are several important limitations.

Static analysis can miss relationships that depend on runtime behavior, dynamic wiring, generated code, reflection, or other information that is not directly visible in the analyzed source.

Multi-module projects can be analyzed when their relevant Java source is included in the uploaded archive.

The generated diagrams represent extracted structure. They are not runtime execution traces.

Gemma can still produce incorrect answers. Supplying structured architecture instead of raw source narrows the problem, but it does not eliminate model errors.

The deterministic assistant only understands the architectural signals it has been designed to extract.

And the public deployment has different privacy properties from a local deployment.

I would rather make those limitations explicit than claim that AI or static analysis can perfectly understand every Spring Boot application.

🌍 Why Open Models Matter Here

Code2UML AI uses Gemma 4, with Gemma 4 26B A4B IT used for the natural-language Architecture Assistant through the Google API integration.

The important part is not simply adding a model to the application.

The model is integrated into a system where the architecture itself is established independently.

That creates a clear separation:

Source Code
    ↓
Deterministic Analyzer
    ↓
Structured Architecture
    ↓
Chosen AI Model

rather than:

Source Code
    ↓
One AI Model
    ↓
"Trust the explanation"

Local inference

The repository also supports OpenAI-compatible local endpoints such as Ollama.

That makes this possible:

Local Code2UML
      ↓
Local static analysis
      ↓
Structured architecture
      ↓
Local Gemma

For developers working with sensitive code, this provides a path toward keeping both analysis and inference on their own machine.

Model independence

The AI endpoint and model are configurable through environment variables.

The deterministic analyzer does not need to be redesigned just because the inference provider changes.

The architecture remains:

Code → Analyzer → Structured Architecture
                         ↓
                    Chosen Model

The model is replaceable because it is not the component responsible for discovering the architecture.

AI is optional

This is one of the most important design decisions in the project.

Without an external AI model, Code2UML AI can still:

Parse Java projects
Identify Spring components
Extract endpoints
Build architecture diagrams
Generate rule-based observations
Answer supported architecture questions deterministically

Gemma adds natural-language exploration.

It does not become the source of truth.

🔐 Privacy Model

Privacy depends on how Code2UML AI is deployed.

Deployment	Code analysis	AI inference	Data leaving the machine
Local + local Gemma	Local	Local	None to an external AI provider
Local + hosted Gemma	Local	External provider	Structured architecture context is sent to the configured provider
Public Render demo	Render server	External Gemma API	The uploaded ZIP reaches the Render server, and structured context may be sent to the configured AI provider

That means the public demo should not be treated as a private deployment.

For proprietary or sensitive projects, the intended approach is to run Code2UML locally and connect it to a local model endpoint.

The analyzer itself does not require an AI model to construct the architecture.

That separation is deliberate.

🏆 Best Use of Gemma

The interesting part of the Gemma integration is not that Code2UML has a chatbot.

It is what the chatbot is given.

Gemma is provided with structured architectural information produced by deterministic analysis rather than being asked to infer the entire application architecture from raw source code.

That creates a clear division of responsibility:

Static analysis extracts the facts.

Gemma explains those facts.

For example, the system can extract:

UserController
      ↓
UserService
      ↓
UserRepository
      ↓
User

and Gemma can turn that structure into an explanation a developer can understand.

When Gemma is unavailable, the deterministic engine can still answer supported architecture questions.

The model is therefore an explanation layer, not the system of record.

☁️ Best Use of Render

Code2UML AI is deployed as a live web application on Render so judges and developers can try the project without setting up the entire stack locally.

The repository includes a Render Blueprint, and the application exposes a health endpoint at:

/api/health

The hosted flow is:

Browser
   ↓
Render Web Service
   ↓
FastAPI
   ↓
Deterministic Spring Boot Analyzer
   ↓
Structured Architecture
   ↓
Gemma API

This makes the project immediately testable from the browser while keeping the local setup available for developers who need a private deployment.

The public demo intentionally uses the included sample project rather than asking users to upload sensitive repositories.

🎯 Why I Built It This Way

The most important decision in Code2UML AI was deciding what the model should not be responsible for.

A general-purpose AI code assistant can read a repository and produce an explanation that sounds convincing.

But a convincing explanation is not necessarily a structurally correct one.

So instead of asking:

“AI, understand this entire Spring Boot project.”

Code2UML AI asks a narrower question:

“Here is the architecture extracted from the code. Now explain it.”

That changes the role of the model.

The architecture is established first.

The model explains it second.

For Rahul, that means the first step into an unfamiliar codebase can start with a visual map rather than dozens of unrelated Java files.

And that is the real reason I built this.

Not to replace reading code.

Not to pretend static analysis is perfect.

Not to let an LLM confidently invent relationships.

Just to make the first hour inside an unfamiliar Spring Boot project a lot less painful.

The next feature I want to explore is deeper request-flow tracing, where Code2UML AI can follow a specific endpoint from controller through service and repository layers instead of only showing the extracted relationships.

The code determines the structure. AI helps explain it.

DEV Community: Shraddha Khetmalis