viz-compose

A production-minded Docker Compose visualizer and architectural audit tool that reads complex Compose topologies and generates Mermaid dependency graphs with built-in security and design validation.

Viz-compose is designed for platform engineers, DevOps teams, and security-conscious developers who want to understand the shape of a Compose stack before deployment, while also surfacing risky patterns such as database exposure, broken dependencies, and circular service relationships.

Highlights

• Parses real-world Compose files with support for multi-file override composition
• Resolves environment placeholders such as ${POSTGRES_VERSION:-latest}
• Supports profile-based filtering with --profile
• Detects dependency cycles, dead dependencies, and implicit network leaks
• Highlights risky database services exposed to public ports or frontend networks
• Produces Mermaid flowcharts with network subgraphs and rich service metadata
• Works cleanly as a CLI for local debugging, CI inspection, and architecture review

Architecture

The project is intentionally modular and keeps the pipeline explicit:

• src/reader.js — Compose file loading, validation, and recursive merge behavior
• src/parser.js — service extraction, env interpolation, profile filtering, and normalization
• src/compiler.js — Mermaid generation with network grouping and visual metadata
• src/analyzer.js — architectural auditing and risk assessment
• src/index.js — CLI orchestration and reporting

Features

Multi-file Compose support

Compose stacks often span multiple files such as:

• docker-compose.yml
• docker-compose.override.yml
• docker-compose.prod.yml

Viz-compose accepts multiple compose files using standard CLI syntax:

node src/index.js -f docker-compose.yml -f docker-compose.override.yml

Files are deeply merged in order, allowing later definitions to override earlier ones while preserving object semantics and arrays in a predictable way.

Environment resolution

Values like this are resolved using runtime environment variables:

image: postgres:${POSTGRES_VERSION:-latest}
ports:
  - "${PUBLIC_PORT:-80}:80"

The parser walks the object tree and resolves placeholders using process.env with safe fallback handling.

Profiles

Optional services can be filtered with:

node src/index.js --profile debug

Any service that defines a profiles list is only included when it matches the selected profile—or if no profile is selected and the service is unprofiled.

Rich Mermaid rendering

Each service node is rendered with richer service identity details, e.g.:

Services display:

• the service name in bold
• image tag or source build marker
• optional container name metadata
• network-specific grouping
• dependency arrows and public port anchors

Architectural validation

The analyzer emits warnings for things like:

• circular dependencies
• database services attached to frontend or public-facing networks
• missing dependency targets
• implicit default-network leaks

This makes the output useful not only as a diagram but as a lightweight architecture review artifact.

Installation

npm install

Usage

Default behavior

If no file is passed, the tool reads docker-compose.yml in the current directory:

node src/index.js

Explicit file selection

node src/index.js docker-compose.yml

Multiple override files

node src/index.js -f docker-compose.yml -f docker-compose.override.yml

Profile filtering

node src/index.js -f docker-compose.yml --profile production

Example output

flowchart TD
  subgraph frontend ["frontend Network"]
    api["<b>api</b><br><small> Source Build</small>"]
    web["<b>web</b><br><small> nginx</small>"]
    db["<b>db</b><br><small>📦 postgres</small>"]
  end
  subgraph backend ["backend Network"]
    redis["<b>redis</b><br><small> redis</small>"]
  end
  api --> db
  api --> redis
  api_internet["🌐 Public"]
  api_internet -->|port 8080| api

  style db fill:#ffdddd,stroke:#ff5555,stroke-width:2px;

 ARCHITECTURAL INSIGHTS:
- [HIGH] network_isolation [db]: Database-like service "db" is exposed on the frontend network or public ports, which violates isolation best practices.

Sample Stack

This repository includes a demo compose file designed to exercise validation logic, including public database exposure and cross-network service relationships.

Roadmap

Potential next steps:

• export as Markdown or SVG
• support Compose version compatibility checks
• detect resource limits and restart policies
• integrate into CI for policy enforcement
• generate architecture reports in JSON or SARIF

What's New (TUI & workflow)

A new interactive terminal UI (node src/tui.js) ships with this release to explore Compose stacks faster. Highlights:

• Dependency Tree: browsable, collapsible view of services with ports/networks shown as children.
• Action Menu: quick actions (1/2/3) to inspect dependencies, apply hardening (with backup + undo), and trace routes.
• Interactive Trace: step through service routes (n/p) and highlight current hop.
• Edit & Commit: edit service ports/networks inline, stage edits, and commit with a safe backup (Ctrl-S).
• File Watch: optional auto-reload of compose files on change (toggle with W).
• Search & Jump: press / to fuzzy-search and jump to a service.
• Session Snapshots: save/restore TUI session state (S/R).
• Export & Reports: export findings, logs, and snapshot reports to JSON for CI or auditing (x).
• Accessibility & Logs: high-contrast mode (m) and a dedicated, scrollable logs pane with timestamps.

Quick run:

node src/tui.js

Open the help inside the TUI (h) for the full keymap and workflow tips.

License

MIT

Contributing

Contributions are welcome. Please keep changes modular, validate behavior with real compose examples, and preserve the project’s focus on clear architecture analysis and secure-by-default patterns.