TopoCode User Guide

Source code architecture analysis platform — an "analysis microscope" for deep code learning

1. Introduction

TopoCode is a source code architecture analysis platform for "deep code learning". Rather than a one-shot prompt-to-diagram tool, it combines static parsing, dependency graph computation, community detection and AI-assisted analysis to help you understand a project's architecture layer by layer and elevate your architectural cognition.

Core Capabilities

• Project import & management — local directory import, file tree browsing, grouping
• Multi-language parsing — Tree-sitter based AST parsing, 18+ languages
• Architecture visualization — dependency / call / community graphs (D3.js / Cytoscape)
• Community detection — Louvain / Leiden algorithms identify module structure
• AI architecture analysis — LLM-driven agent workflow generating component docs & overviews
• Interactive AI assistant — project-context Q&A with tool calling
• External-brain knowledge base — persistent docs forming a store → analyze → use loop
• Architect workbench — semantic assets / requirements / design / Coding Agent delivery
• MCP endpoints — Model Context Protocol (HTTP) access for external agents

Privacy: except for user-configured cloud LLM APIs, parsing, graph computation, analysis and doc serving all run locally. Your source code never leaves the machine.

Form factor: a web app served by a local gateway (:3456); runs on servers, VMs and containers with no desktop/Electron dependency.

2. Installation & Launch

Requirements

• Node.js >= 20.0.0, Python >= 3.10, npm (or pnpm), pip
• Recommended: 4+ CPU cores / 16 GB+ RAM / 10 GB+ disk (Linux / macOS / Windows)
• Analysis mainly relies on frontier cloud models: 4 cores / 8 GB suffices for basic usage; local LLMs require a large-VRAM GPU and a capable model

Install from Source

git clone https://github.com/topocode/topoone-ui
cd topoone-ui
npm run setup   # creates .venv + pip install -e (core + 4 backends) + npm install

Run & Access

npm run serve   # = topo serve: supervisor spawns 9 processes; gateway on :3456
npm run status  # process status (topo status)
bash scripts/serve.sh stop   # stop

The first launch prints an access token. Open in browser:

http://localhost:3456/#token=<token>

Development Mode

npm run dev   # core backend + 4 frontend dev servers concurrently
npm run build # core bundle + portal + 4 sub-app frontends

3. Portal & Layout

TopoCode is a monorepo of sub-apps behind a unified portal, reverse-provided by the local gateway :3456:

UI language (中文 / English) is switchable in settings; AI analysis output follows it.

4. Project Management & Baseline

4.1 Import a Project

Import a local source directory (drag & drop) in the workbench; projects support grouping (M:N), file-tree browsing. TopoCode parses source files directly from disk and requires no build environment.

Code-generated projects: if a project generates source (protobuf, graphql-codegen, go generate...), run the generation command before import so generated files are included in analysis.

4.2 Baseline Setup

The overview page shows a "baseline" card that detects three baseline modes and offers matching actions:

• Git repo — git history as baseline, supports refresh & diff
• codegraph — external codegraph CLI symbol index (.codegraph/codegraph.db in the target project), the symbol source for architect semantic assets
• Self-managed — TopoCode-managed snapshots without git

When codegraph is missing it degrades to a lightweight file scan; topo doctor checks environment health. After the baseline is set, AI component naming runs; view progress or re-run it on the overview page.

5. Architecture Analysis

5.1 Pipeline

1. Parsing — Tree-sitter AST + symbol extraction (pure static, ~2–5 min)
2. Graph building — call / dependency graphs, file centrality (NetworkX)
3. Community detection — Louvain / Leiden identify module structure
4. File pre-summary — LLM batch summarization (optional, ~1 min/file)
5. Component analysis — LLM multi-turn analysis (1–5 min each)
6. Architecture overview — consolidated overview document (1–5 min)

5.2 Visualization

Dependency / call / community graphs support interactive browsing (D3.js / Cytoscape force layouts); Mermaid / PlantUML diagrams embed in documents.

5.3 Change Overview & Digest

After a baseline refresh, the project overview lists changes grouped by component hierarchy (added / modified / deleted / renamed, expandable to files). The "development digest (cockpit)" summarizes recent changes with deep links into baseline diffs or sessions.

6. Document Viewer

The docs sub-app (service :3481) browses analysis outputs: architecture overviews, component docs, AI discussion artifacts — persisted and served via viewer / web-root routes.

Diagram rendering runs on the unified topo kernel (DiagramSchema IR as single source of truth):

• Mermaid — client-side main-thread rendering; the server headless pool (chromium) requires pip install -e "packages/core[diagrams]" + playwright install chromium (render endpoints return 503 otherwise)
• PlantUML — local JVM sidecar (:3491, jar at ~/.topocode/plantuml.jar) preferred, auto-fallback to local jar → remote service

7. AI Chat

The chat sub-app (service :3483, route /chat) provides a project-context interactive assistant:

• Session management: multiple sessions, skills (prompt templates), drafts
• Tool calling: symbol search, file reading, graph queries — answers anchored to real code
• Streaming output; language matches UI setting

Add an LLM under Settings → Model Configuration first (see section 10).

8. Architect Workbench & Coding Agent

The architect sub-app (service :3470, route /architect) is the "from cognition to implementation" workbench: semantic assets, requirements, design, and driving Coding Agents through implementation jobs.

8.1 Semantic Assets

Built on the codegraph symbol index plus AI naming & ownership analysis into a component-tree of semantic assets; supports renaming, merging and unassigned-file management — the knowledge foundation for requirement/design analysis.

8.2 Coding Agent Executors

Implementation jobs run via the runner service (:3458) in isolated worktrees + branches, with three executors:

Job introspection: message stream, token usage, pending approvals, checkpoints. Specs/rules/agent configs can be injected into the job workspace; steering input supported mid-run.

9. Knowledge Base

Analysis documents persist in a local knowledge base (SQLite + DuckDB). The KB is the iteration focus: an external-brain aligned with your cognition — not just static storage but, via MCP and other integrations, a base that helps you command other agent tools, closing the store → analyze → use loop.

10. Settings & Configuration

10.1 Model Configuration

Add LLMs under Settings → Model Configuration; any OpenAI-compatible provider works.

Common endpoints: DeepSeek https://api.deepseek.com; OpenAI https://api.openai.com; local runtimes (Ollama http://localhost:11434, LM Studio http://localhost:1234) also work, with quality depending on the model.

10.2 General Settings

Change HTTP port (default 3456) and bind address, UI language (中 / EN), and theme.

10.3 PlantUML Rendering Service

Self-hosting PlantUML is recommended (data stays in your network):

docker run -d --name plantuml -p 8300:8080 plantuml/plantuml-server:jetty

Then set backend env PLANTUML_SERVER=http://localhost:8300 and restart (default is http://www.plantuml.com/plantuml; intranet deployments must switch to self-hosted).

10.4 MCP Server

MCP (HTTP) endpoints for external agents run as a separate process on :3460 (auto-started by topo serve):

11. FAQ

Token invalid / not logged in?

The first topo serve prints an access token; open http://localhost:3456/#token=<token>. The #token= fragment persists after login.

Port :3470 in use / architect fails to start?

Architect enforces a pidfile mutex: a supervised instance refuses double-launch. Stop the supervisor first (bash scripts/serve.sh stop), then restart.

Analysis is slow?

LLM-heavy stages (file pre-summary, component analysis) depend on model throughput and concurrency — see stage estimates in section 5. Prefer high-throughput frontier cloud models and raise concurrency in settings.

What if codegraph is missing?

Architect semantic assets degrade to a lightweight file scan (lower precision). topo doctor detects it. Prefer building .codegraph/codegraph.db in the target project first.

Render endpoints return 503?

The headless rendering pool isn't installed: run pip install -e "packages/core[diagrams]" and playwright install chromium, or rely on browser-side rendering only.

Generated source files missing from analysis?

TopoCode parses files on disk and never runs builds. Execute codegen (e.g. go generate ./..., protoc) before import, then resync.

Repository: github.com/topocode/topoone-ui · Issues: Issues · Email: topocode@163.com