I built CodeArchy: an open-source that turns any codebase into a visual, explainable architectural experience, powered by Gemma 4.

I. Kennedy Yinusa — Fri, 22 May 2026 16:33:22 +0000

This is a submission for the Gemma 4 Challenge: Build with Gemma 4

What I Built

In this age of Agentic coding, most developers spend more than half their time reading code rather than writing it. For legacy systems, that number is even worse. When you inherit a 100,000-line monolith, clone an unfamiliar open-source project, or receive a repository full of AI-generated code from an agent that has long since stopped caring about your team's conventions, the question is always the same: where do I even start?

CodeArchy answers that question in seconds.

It parses your project using a battle-tested AST engine (Tree-sitter), builds a complete typed dependency graph, and feeds that structured graph to Gemma 4. The model doesn't describe your files — it thinks like a senior architect, grouping low-level modules into named, purposeful subsystems such as "Auth Layer", "Data Access", or "API Gateway", then draws the data flows between them. The result is the whiteboard diagram a principal engineer would sketch on day one, generated in under a minute, entirely offline.

That diagram is interactive. You can ask questions about any subsystem. Gemma 4 answers with architectural context maintained across every turn of the conversation. Every response can be read aloud by a built-in neural TTS engine (Kokoro, also fully offline). And after each answer, Gemma 4 generates a narrated walkthrough — a story player — that animates through the diagram node by node while speaking the explanation aloud, so you don't just read about the architecture, you watch it unfold.

The entire system runs locally. No code ever leaves your machine. No API keys. No cloud costs. All inference targets http://localhost:11434

Demo

Code

Inspect the codebase

How I Used Gemma 4

Gemma 4 is the engine that makes CodeArchy genuinely useful. It powers four (4) distinct capabilities, each one addressing a different point in the developer journey from "I have no idea what this codebase does" to "I confidently understand it and can extend it safely."

1. Architectural Abstraction — From File Graph to Whiteboard Diagram

The hardest part of understanding any codebase is knowing which details to ignore. A 300-file repository has tens of thousands of import relationships. If you visualise all of them, you get an incomprehensible hairball. What you actually want is the architect's view: five to twelve named subsystems and the meaningful flows between them.

This is exactly the task given to Gemma 4.

The pipeline starts with Tree-sitter parsing every file into an AST, extracting symbols, imports, and exports:

// src/parser/IncrementalParser.ts
async parseFile(uri: vscode.Uri): Promise<ParsedTree | undefined> {
    // ...
    // Try tree-sitter first
    if (this.treeSitterReady) {
        tree = await this.parseWithTreeSitter(source, language, ext);
    }
    // Fall back to regex-based parsing
    if (!tree) {
        tree = this.buildLightweightTree(source, language);
    }
    // ...
}

The GraphBuilder then turns those extractions into typed nodes and weighted edges:

// src/graph/GraphBuilder.ts
build(analyses: FileAnalysis[], allFiles: string[]): ArchitectureGraph {
    const nodes = this.buildNodes(analyses);
    const edges = this.buildEdges(analyses, allFiles);
    // ...
    return { nodes, edges, subsystems: [], metadata };
}

Before sending anything to Gemma 4, ArchitectureInference applies a three-phase heuristic pass: directory grouping, semantic keyword matching, and connectivity-based refinement, to pre-cluster modules into candidate subsystems:

// src/inference/ArchitectureInference.ts
const HEURISTIC_GROUPS: Record<string, string[]> = {
    'API / Routes': ['route', 'router', 'controller', 'handler', 'endpoint', 'api', 'middleware'],
    'Models / Data': ['model', 'schema', 'entity', 'dto', 'migration', 'database', 'db', 'repository'],
    'Services / Logic': ['service', 'provider', 'manager', 'engine', 'processor', 'worker', 'job'],
    'Auth / Security': ['auth', 'login', 'session', 'token', 'permission', 'role', 'guard', 'security'],
    'Messaging / Events': ['event', 'listener', 'emitter', 'queue', 'pubsub', 'message', 'notification'],
    // ...
};

The pre-clustered graph is then compressed into a token-efficient summary before being handed to Gemma 4. The summariser intelligently scales the verbosity to match the user's chosen processing depth:

// src/inference/OllamaService.ts
private summarizeGraph(graph: ArchitectureGraph, profile: ProcessingProfile): string {
    const lines: string[] = [];

    // Group by subsystem
    for (const sub of graph.subsystems) {
        lines.push(`## ${sub.name} (${sub.nodeIds.length} modules)`);
        const subNodes = graph.nodes.filter((n) => sub.nodeIds.includes(n.id));
        for (const node of subNodes.slice(0, profile.maxModulesPerSubsystem)) {
            lines.push(`  - ${node.id} (${node.symbols.length} symbols)`);
        }
    }

    // Aggregate file-level edges into subsystem-to-subsystem edges
    // (collapses thousands of imports into a handful of meaningful dependencies)
    const subEdgeCounts = new Map<string, number>();
    for (const edge of graph.edges) {
        const s = nodeToSub.get(edge.source);
        const t = nodeToSub.get(edge.target);
        if (!s || !t || s === t) continue;
        const key = `${s} → ${t}`;
        subEdgeCounts.set(key, (subEdgeCounts.get(key) || 0) + 1);
    }

    lines.push('## Subsystem Dependencies:');
    for (const [key, count] of sortedEdges) {
        lines.push(`  ${key} (${count} refs)`);
    }
    return lines.join('\n');
}

This compression is crucial for small local models. Sending raw source code to an 8B-parameter model would overflow its context window and produce meaningless output. Sending a compact, structured dependency summary gives Gemma 4 everything it needs to reason architecturally.

The prompt instructs Gemma 4 to think and respond like a senior architect, not a code summariser:

// src/inference/OllamaService.ts
private buildArchitecturePrompt(graph: ArchitectureGraph, profile: ProcessingProfile): string {
    const treeSummary = this.summarizeGraph(graph, profile);

    return `You are a senior software architect. Analyze the following codebase structure
and produce a high-level system architecture diagram.

CODEBASE STRUCTURE:
${treeSummary}

INSTRUCTIONS:
1. Identify the major subsystems/layers (e.g., "API Gateway", "Auth Service", "Data Layer").
2. Name each subsystem professionally — NOT by folder name. Use architect-level names.
3. Describe each subsystem's responsibility in one sentence.
4. Identify the key dependencies and data flows between subsystems.
5. Suggest the overall architectural pattern (e.g., MVC, Layered, Microservices, Event-Driven).

Respond ONLY with valid JSON in this exact format:
{
  "pattern": "Architectural pattern name",
  "summary": "One-paragraph architecture summary",
  "nodes": [ { "id": "...", "label": "...", "description": "...", "type": "..." } ],
  "edges": [ { "source": "...", "target": "...", "label": "...", "type": "..." } ]
}`;
}

The response is parsed into SystemArchNode and SystemArchEdge objects and visualised in a React Flow canvas with ELK-powered automatic layout. Every node is assigned a meaningful silhouette shape (cylinder for databases, hexagon for caches, shield for auth services, etc.) entirely from its label and description, metadata needed from the model.

2. Understanding Legacy and AI-Generated Code

Legacy codebases and AI-generated repositories share a common problem: there is no living documentation that explains why the code is structured the way it is. Inline comments describe the what, but never the why at system level. Architecture decision records, if they existed, are years out of date. The original authors have moved on.

For AI-generated codebases, the problem is qualitatively different. An AI coding agent can scaffold a 50-file project in minutes. The result is often syntactically correct, internally consistent, and completely opaque to the humans who inherit it. There is no architectural intent baked in, because the agent never had one. It has patterns, not plans.

Gemma 4 reverses that. When CodeArchy feeds the dependency graph to Gemma 4 with the architect-level prompt, it is asking the model to retroactively infer the intent behind the structure. Because Gemma 4 has been trained on vast quantities of software engineering literature and real-world codebases, it recognises the shapes of MVC, layered architectures, event-driven systems, and microservice topologies even when no one wrote them down.

The model's output names subsystems the way a principal engineer would name them in a design review: "Presentation Layer", "Business Logic", "Data Access", "External Integrations", etc. The dependency arrows tell you which subsystems call which, and the architectural pattern label tells you the family of design you are looking at. In under sixty seconds, a developer joining a legacy project or reviewing AI-generated code has the same mental model that previously took days to build.

3. Conversational Architecture Teaching with Full Context

Once the diagram is rendered, Gemma 4 shifts into its second role: interactive architecture teacher.

The system prompt passes Gemma 4 the full underlying data for all three diagram views, the module-level dependency graph, the AI-generated high-level architecture, and the dense graph, so the model can answer questions grounded in real structure rather than hallucinating:

// src/inference/OllamaService.ts
private buildChatSystemPrompt(): string {
    return `You are CodeArchy, an AI architecture assistant.

THREE DIAGRAM VIEWS ARE AVAILABLE IN THE UI:
- Flow Diagram  : Module-level dependency graph.
- System Diagram: AI-generated high-level architecture.
- Dense Diagram : Full dependency graph.

When a user references any of these diagrams by name, answer using the matching
data provided below.

${this.buildSystemArchSection()}

FLOW DIAGRAM DATA (module-level graph):
${this.architectureContext}

GUIDELINES:
- Answer questions about the architecture, subsystems, dependencies, and design patterns.
- Explain complex relationships in simple terms.
- Never say you lack access to a diagram — you have its full data above.`;
}

Conversation history is maintained in the extension host across turns and replayed on context switches (for example, when the user switches workspaces). The slice of history sent to Gemma 4 is scaled to the user's processing mode:

// src/inference/OllamaService.ts
async chat(message: string, modelTag: string, onChunk?, onThinkChunk?, mode = 'moderate') {
    const profile = getProcessingProfile(mode);
    const messages = [
        { role: 'system', content: systemPrompt },
        ...this.conversationHistory.slice(-profile.maxChatHistory).map((m) => ({
            role: m.role,
            content: m.content,
        })),
    ];
    const response = await this.chatCompletion(modelTag, messages, profile, onChunk, onThinkChunk);
    this.conversationHistory.push({ role: 'assistant', content: response, timestamp: Date.now() });
    return response;
}

Three processing modes are available: Fast, Moderate, and In-Depth — each configured with precisely tuned inference parameters:

// src/inference/OllamaService.ts
const PROCESSING_PROFILES: Record<ProcessingMode, ProcessingProfile> = {
    fast: {
        numPredict: 512,
        numCtx: 2048,
        maxChatHistory: 4,
        think: false,
        temperature: 0.2,
    },
    moderate: {
        numPredict: 1024,
        numCtx: 4096,
        maxChatHistory: 6,
        think: false,
        temperature: 0.1,
    },
    indepth: {
        numPredict: 4096,
        numCtx: 8192,
        maxChatHistory: 10,
        think: true,       // enables Gemma 4's hidden "thinking" tokens
        temperature: 0.0,
    },
};

In-Depth mode enables Gemma 4's extended thinking tokens, giving the model additional internal reasoning steps before it produces its final answer, particularly valuable when a developer asks a complex cross-subsystem question such as "trace the data flow from the HTTP request handler all the way to the database write".

4. The Interactive Voice Narrator — Architecture Explained Aloud

The most distinctive capability of CodeArchy is the narrated story player. After every chat response, Gemma 4 runs two additional inference passes that together produce an animated, spoken walk-through of the architecture.

Pass 1 - Key Flow Extraction: Gemma 4 distils the verbose chat answer into a compact ordered list of architectural steps, stripping prose, rationale, and examples down to the essential execution path:

// src/inference/OllamaService.ts
async extractKeyFlow(input: { question: string; answer: string }, modelTag: string) {
    const prompt =
        `You are an architecture analyst. Read the assistant's answer below and extract the\n` +
        `essential architectural flow as a SHORT ordered list. Strip prose, examples, code,\n` +
        `and rationale — keep only the steps that describe how the system works.\n` +
        `\nReturn 4–10 plain bullet lines, one per step, in execution order.\n` +
        `Each bullet must be a single sentence (<= 140 chars), no markdown, no numbering.`;
    // ...
}

Pass 2 - Narrator Timeline: Gemma 4 takes that compressed key flow and maps it onto the actual diagram nodes, producing a JSON timeline of steps that each reference a real node ID:

// src/inference/OllamaService.ts
const prompt =
    `You are an architecture narrator. Convert the assistant's answer into a short visual walkthrough.\n` +
    `\nAvailable nodes (id :: label):\n${nodeLines}\n` +
    `\nReturn ONLY a valid JSON object:\n` +
    `{"title":"<short title>","steps":[{"targetNodeId":"<id from list>","narration":"<one plain-text sentence>","action":"focus"}]}\n` +
    `Rules:\n` +
    `- 2 to 10 steps.\n` +
    `- Every targetNodeId must exactly match an id from the list above.\n` +
    `- narration must be plain English, <= 180 chars.\n` +
    `- Output the JSON object only.`;

The useStoryPlayer hook drives the animation: each step highlights the target node in the React Flow or System diagram, while the Kokoro neural TTS engine reads the narration aloud. The story player's timing logic adapts to the speech engine, when Kokoro finishes speaking a sentence, it advances to the next step; a safety timer ensures the sequence never stalls:

// webview-ui/src/components/useStoryPlayer.ts
const runStep = useCallback((index: number) => {
    const step = steps[index];
    onStepRef.current(step, index); // animates the diagram node

    const words = step.narration.split(/\s+/).filter(Boolean).length;
    const estMs = Math.min(14_000, Math.max(300 + words * 280, step.durationMs ?? 2_600));

    const advance = () => {
        if (statusRef.current !== 'playing') return;
        runStep(stepIndexRef.current + 1);
    };

    // Cache-first playback: instant if the step's PCM was previously synthesised
    if (cached) {
        void playCachedAudio(cached.pcm, cached.sampleRate, {
            onEnd: () => advance(),
            onError: () => advance(),
        });
    } else if (kokoroActive) {
        // On-demand synthesis + persist for future instant replay
        const audio = await synthesizeKokoroAudio(step.narration, activeVoice);
        void playCachedAudio(audio.pcm, audio.sampleRate, { onEnd: () => advance() });
        await updateNarratorStepVoice(myNarratorId, myIndex, audio); // persist to IndexedDB
    }
}, []);

Once synthesised, each narration step's audio is persisted to IndexedDB so replaying the same walk-through is instant. The system accumulates a library of spoken architectural explanations, each grounded in the live codebase graph.

Why These Specific Models?

CodeArchy exposes three (3) model variants to users and recommends one based on the task:

Model	Ollama Tag	Best For
Gemma 4 E2B	`gemma4:e2b`	Quick architecture snapshots; fast chat responses
Gemma 4 E4B	`gemma4:e4b`	Richer subsystem detection; default for most users
Gemma 4 26B	`gemma4:26b`	Deep cross-subsystem analysis; large codebases

E2B is the right choice for fast mode: architecture generation, real-time streaming, and narration timeline extraction where latency matters more than depth. E4B hits the sweet spot for most day-to-day use, rich enough to name subsystems meaningfully, small enough to run on a developer laptop without a discrete GPU. 26B is reserved for teams with the hardware to run it and codebases complex enough to warrant the extra analytical depth.

All three models share the same offline guarantee. The model weights are pulled once via Ollama's registry. After that, everything runs at localhost:11434 with zero network dependency.

What This Means for Engineering Teams

The practical impact of combining Gemma 4's architectural reasoning with CodeArchy's offline delivery model breaks down into four concrete time savings:

Onboarding: A developer joining a new team can generate the system architecture diagram of their assigned codebase in the time it takes to make a coffee. The named subsystems immediately answer "where does X live?" and "which layer should I touch for Y?", questions that previously required finding the right person to ask.

Understanding AI-generated code: When a coding agent hands off a repository, CodeArchy lets the receiving engineer ask Gemma 4 directly: "does this architecture match our expected user flow?". The interactive narration walks through the data paths so the engineer can verify that the AI-generated structure aligns with product requirements before it gets merged.

Legacy archaeology: Instead of spending a week tracing call chains through a monolith, a developer can ask "how does a payment request flow through this system?" and receive a step-by-step narrated walk-through with the relevant nodes highlighted on screen.

Safe feature additions: Before adding a feature, a developer can ask "what will be affected if I change the Auth subsystem?" and receive an answer grounded in the actual dependency graph, not documentation that may be a year out of date.

All of these happens without a browser tab, without pasting code into a chat interface, and without trusting any third-party service with proprietary code. Gemma 4's quality, running locally via Ollama, makes the offline-first constraint feel like a feature rather than a compromise.

DEV Community: I. Kennedy Yinusa

I built CodeArchy: an open-source that turns any codebase into a visual, explainable architectural experience, powered by Gemma 4.

What I Built

Demo

Code

How I Used Gemma 4