ModView

日本語版はこちら

ModView is a SystemVerilog module interconnection viewer: a lightweight, OSS-only web application that parses your RTL and draws how the modules are wired together, as a diagram you can rearrange and save.

What ModView does

Reading a hierarchy out of source code is slow, and commercial RTL viewers are tied to a licence and an install. ModView needs neither: point it at a folder of .sv / .v files and it renders the design in a browser.

• Parses with Verible — modules, ports, bus widths, parameters, instances and their connections, including SystemVerilog interface and modport declarations.
• Infers the wiring from nets, not from naming conventions: ports bound to the same signal form a net, one driver is chosen, and links are drawn from it. A sub-module whose source you did not upload still appears, with its port directions inferred from how each net is driven.
• Lays the diagram out automatically with ELK.js: layered left-to-right placement plus orthogonal edge routing computed for all edges at once, so lines avoid the node bodies and each other.
• Shows hierarchy in place — an instance that itself contains instances is drawn as a container with its children nested inside.
• Collapses interface buses into one colour-coded trunk link per interface instance, expandable to the individual signals with a click.
• Lets you edit and keep it — drag nodes with the lock released, and every drop re-routes the connections; save the arrangement as JSON and load it back.

Zoom in one step and the structure is readable: here the encoder's dual processing pipeline, where block_distributor splits blocks across two dct_2d + quantizer chains that output_merger re-interleaves before rle_encoder and huffman_encoder.

At 1:1 the AXI4-Stream handshake between two stages is legible: inputs on the left edge in blue, outputs on the right in orange, clock in red, reset in amber, and bus widths on the labels.

Quick start (Docker)

docker compose up --build

Then open http://localhost:8080. The backend API is exposed on http://localhost:8000.

Quick start (local development)

Backend (requires verible-verilog-syntax on PATH):

cd backend
uv venv && uv pip install -e ".[dev]"
uv run uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
pnpm install --ignore-workspace
pnpm dev          # http://localhost:5173, proxies /api to :8000

Walkthrough: the bundled JPEG encoder

The repository ships a real design to try ModView on: example/jpegenc/rtl, a baseline JPEG encoder in 12 SystemVerilog modules whose stages are connected with AXI4-Stream.

1. Load the sources. Click Select Folder and pick example/jpegenc/rtl — every .sv / .v file under the directory is collected, and the specification .md file beside them is ignored. (Use Select Files if you would rather pick individual files.) A request may carry up to 20 000 files, 50 MB per file and 500 MB in total.

2. Parse. Click Parse. The sidebar fills with the 12 modules, and the top-module dropdown groups them into Top candidates and Other modules. If some files fail to parse, ModView still renders what survived and shows a View errors (N) link in the status bar.

3. Pick the top. jpeg_encoder_top is the only candidate here, so it is selected for you. Any module in the list can be made the top instead — click dct_2d to see that one module's own interconnection.

4. Read the diagram. The encoder flows left to right: rgb2ycbcr → block_splitter → block_distributor → two parallel dct_2d + quantizer pipelines → output_merger → rle_encoder → huffman_encoder → bitstream_assembler. Boundary I/O terminals sit at the far left and right. Use the wheel or + / − to zoom, Fit to frame the whole design.

5. Rearrange it. The diagram opens edit-locked: the toolbar button reads 編集ロック中, and dragging anywhere pans the view. Click the button to switch to 編集可, then drag a node. On each drop, ModView re-routes every connection and refits the parent container — there is no re-route button to press.

   

6. Recover the layout quality. After several moves the per-link routing is less tidy than the first render. Re-layout re-runs the full ELK pipeline to restore it; note that ELK then chooses the node positions again, so your manual arrangement is discarded.

7. Keep it. Save (Ctrl+S / Cmd+S) downloads the layout as JSON; Load (Ctrl+O / Cmd+O) restores it.

To see the parse-error surface, copy one of the example files, break its syntax, and parse the folder again: the modules that still parse are rendered, and the error list opens from the status bar.

Interface trunk links

When a connection binds a SystemVerilog interface — through a modport expression (.bus(axi_bus.master)) or through a port declared as <interface>.<modport> <name> — all signals of that interface instance are drawn as one thick trunk, labelled interface.modport and coloured from the instance name. Click a trunk (while unlocked) to expand it into the individual signals, and click again to collapse it. The JPEG-encoder example does not use interface constructs, so this feature does not appear in the screens above; the test fixtures under backend/tests/fixtures/ exercise it.

Repository layout

modview/
├── backend/      FastAPI + Verible parsing service
├── frontend/     Vite + TypeScript + JointJS diagram UI
├── example/      jpegenc/rtl — the design used in the walkthrough
├── docs/         architecture.md, api.md (+ _ja Japanese editions), images/
├── CHANGELOG.md  version history
└── docker-compose.yml

Tests

cd backend  && uv run pytest          # CST visitor + API
cd frontend && pnpm test              # diagram logic
cd frontend && pnpm audit:routing     # routing smoke audit over the fixtures

Versioning

This project follows Semantic Versioning — MAJOR.MINOR.PATCH. The current version is 0.1.0, the initial release. While MAJOR is 0 the HTTP API and the layout save format may change in a minor release. GET /api/health reports the running backend's version, and CHANGELOG.md records what each version contains. Each release is marked with an annotated git tag named vMAJOR.MINOR.PATCH (v0.1.0 for the initial release).

The version field inside a saved layout file (currently "1.0") is the save-format schema version and is independent of the application version above.

The packages and the Docker images are named modview-backend and modview-frontend. They were renamed from sv-module-viewer-* before the first release that carries the ModView name, so no published artefact changes name mid-life.

Documentation

• docs/architecture.md — system architecture (日本語)
• docs/api.md — HTTP API reference (日本語)
• CHANGELOG.md — version history
• .aiprj/AI_PRJ_REQUIREMENTS.md — requirements
• .aiprj/AI_PRJ_DESIGN.md — design specification

Licenses

ModView's own source code — both packages — is released under the MIT License; see LICENSE.

The bundled example design is third-party content, redistributed unmodified:

Path	Origin	License
example/jpegenc/rtl	https://github.com/aquaxis/jpegenc	MIT, per the upstream repository

Third-party components and their licenses:

Component	License	Notes
Verible	Apache-2.0	Bundled binary in the backend image
verible_verilog_syntax.py	Apache-2.0	Vendored at backend/app/verible/ (© The Verible Authors)
JointJS Core (@joint/core)	MPL-2.0	Used unmodified via npm
ELK.js (elkjs)	EPL-2.0	Layered layout + orthogonal edge routing
FastAPI / Uvicorn / Vite / TypeScript	MIT

The vendored verible_verilog_syntax.py is unmodified and retains its original Apache-2.0 header. JointJS is consumed as an unmodified npm dependency; no MPL-licensed source files are altered in this repository.