Export the map as architecture-as-code models (LikeC4, Structurizr, Backstage catalog, Mermaid preview)

Abierto
  • ¿Algo no está bien?
#152 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
38/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
go
Área
cli, tooling

Línea de trabajo

Start with the saved-map input and the proposed dircue map export command, then review related issue #103 for shared exporter concerns. Define the model mappings and evidence handling for LikeC4, Structurizr, Backstage, and Mermaid, including unresolved C4 levels and stable identities. Done means deterministic output for each format without rescanning or overwriting human-authored content.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement

User outcome

dircue map export --format likec4 map.json > repo.c4 writes an architecture-as-code model of what the map observed, and does the same for the formats below. People then render, extend and navigate it with the tools they already use. dircue supplies the facts; it doesn't draw.

Why

  • Architecture diagrams are usually hand-drawn or generated by a model, and both drift. A recent public discussion of agent-drawn architecture canvases (https://news.ycombinator.com/item?id=49833867) kept returning to the same three worries:

    • the diagram diverging from the code;
    • "N+1 sources of truth";
    • hallucinated arrows.

    One of that project's own authors described a maintained "software map" of the codebase as the backbone that should power every diagram. The map is that backbone: deterministic, derived from declarations, with evidence for every node and edge, and regenerable at every commit.

  • The ecosystem already has good modeling languages and renderers, so dircue shouldn't build its own (FFmpeg philosophy: emit formats others consume).

    • LikeC4 (MIT) is a model DSL with user-defined element kinds and metadata {} key-value blocks. Elements can link to source files with line ranges (link ../src/index.ts#L1-L10). It has a CLI that renders and exports (JSON, Draw.io, PNG, among others), an MCP server, and it is the format that drift tools such as erode read.
    • Structurizr DSL and workspace JSON are the original C4 tooling, with properties {} per element.
    • Backstage catalog-info.yaml (Component, API, Resource, System; dependsOn, providesApis, consumesApis; annotations) is widely used as a service catalog.
    • Mermaid (architecture-beta, C4 still experimental) and C4-PlantUML render almost anywhere, but carry no evidence.

Proposal

  • Input: a saved map, optionally with attached-report nodes. The source is never rescanned.

  • Output: deterministic, byte-identical text for the same map, in stable order.

  • Formats, in order:

    1. LikeC4 (richest evidence carriage);
    2. Structurizr DSL or workspace JSON;
    3. Backstage catalog-info.yaml entities;
    4. Mermaid, and optionally C4-PlantUML, as lossy previews that state they carry no evidence.

  • Mapping (to be designed; a first cut):

    • the root or forest is a software system;
    • deployables and primary-role components are containers. Workloads, Compose services and functions deploy components via builds/runs.
    • Capabilities (datastores, queues, caches) become container or external-system elements, with uses_capability as relationships.
    • Declared interfaces (ports, gRPC and OpenAPI documents) become element properties or API entities.
    • depends_on_local and member_of give structural relationships. Runtime "uses" arrows between services wait for connects_to (#103), and each format states that they're absent until then.
    • Test, fixture, example, vendored and docs roles are excluded by default and selectable.

  • Evidence and uncertainty travel with every element:

    • dircue node and edge IDs;
    • evidence file and span (as LikeC4 link or Structurizr/Backstage properties and annotations);
    • basis, coverage status and reasons.

    partial and unknown are never rendered as settled facts. A header records the map's source identity, dircue version and the questions whose coverage was not complete.

  • Round trip: a generated model is a starting point a team can extend. Keep generated and hand-written parts separable (LikeC4 multi-file projects, Structurizr workspace extends), so regenerating never clobbers human edits.

Non-goals

  • No layout or rendering engine, diagram server, or hosted service.
  • No LLM involvement.
  • No inferred runtime behavior beyond what the map records.
  • No quality, risk or conformance verdicts (see #153).

Open questions

  • C4's container/component levels don't map one-to-one onto dircue's component/deployable split, especially for monorepos and libraries. Decide this with real repositories (the golden corpus) before freezing a mapping.
  • Where the map is silent, should element identity be stable across map revisions (for diff-friendly exports)? Reuse map node IDs.

Related

  • #103: connects_to and Mermaid/DOT diagram export. This issue covers architecture model formats; #103's simple exporters can share the same export command.
  • #104: offline HTML report.
  • #25: map query and MCP.
  • #10: map compare.
Lenguaje dominante
Go
Estrellas
0
Forks
0
Merge medio
11 h 3 min
PR fusionados (30 d)
5

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de war-and-code/dircue

Todos los issues de war-and-code/dircue

Issues similares

Más issues de Go

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.