# suiramdev/docwright architecture

> Architecture diagram of the GitHub repository suiramdev/docwright, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/suiramdev/docwright
- Repository: https://github.com/suiramdev/docwright

## Overview

##### Project Type & Purpose
- Docwright is a library that automates the generation of UI documentation from Playwright-style test scripts. Its purpose is to let users author UI scenarios using a DSL of directives (such as describe, scenario, text, screenshot, highlight) and automatically convert these into documented UI flows. It is built to work on Bun and leverages Playwright for browser automation.

##### Analyzing the File Structure
- There are several high-level directories that suggest a monorepo structure:
- packages/core – Contains the core functionality including the CLI command definitions (commands/generate.ts), configuration resolvers (packages/core/src/config), directive implementations (the “directives” folder with beforeAll, afterEach, etc.), and internal utilities (registry, tracer, worker, models).
- packages/render-markdown – Handles the transformation of processed data into Markdown (and likely other outputs).
- playground – Provides example configuration files and sample UI documentation scripts.
- Additionally, configuration files like tsconfig.json, package.json, and Bun-related files (bun.lock, .bun-version) indicate TypeScript usage and that the project is built to run on Bun.

##### Key Architectural Components & Their Relationships
a. CLI Interface:
- Found in packages/core/src/cli.
- Exposes commands such as "generate" (e.g., via generate.ts) and initialization (docwright init) to the user.
- It acts as the entry point for users to run the docwright library.
b. Configuration Management:
- The configuration resolver (resolve.ts) and configuration schema (schema.ts) are responsible for reading and validating the user's docwright.config.ts file.
- This component determines which test scripts (such as those found in the playground or user-provided scripts) should be processed.
c. Core Engine:
- This is the heart of docwright. It parses and executes Playwright-style test scripts and their embedded documentation directives.
- Within the core engine, the following subcomponents are important:
- Directives: Implementations for describe, scenario, text, screenshot, highlight, etc., which enable users to annotate UI flows.
- Registry: Keeps track of directives and test cases.
- Tracer/Worker: Possibly used for tracking the execution of tests and managing the sequencing or concurrency of tests, gathering output details.
- Models: Definitions (such as Task, TaskCase, TaskSuite, Renderer) that structure the data generated from test runs.
- The core engine interprets the DSL (the special functions exported by the library) and organizes data for documentation.
d. Rendering Module:
- Located in packages/render-markdown.
- Converts the structured output (and potentially raw data from tests) into Markdown format—serving as the final output format for documentation.
- This module ensures that the user gets a readable UI documentation file with descriptions, screenshots, and highlighted elements.

##### Relationships and Data Flow
- The flow starts with a user invoking the CLI (via bunx docwright generate or similar).
- The CLI first uses the Configuration Management component to load the docwright.config.ts file.
- Then, the Core Engine is triggered to parse and execute the user's test scripts:
- The DSL directives (describe, scenario, etc.) capture data as they run.
- The Registry, Tracer, and Worker collaborate to manage and aggregate this data.
- Once the execution is complete and data is assembled into defined Models, the Rendering Module (Markdown Renderer) converts this information into UI documentation.
- If needed, additional scripts (or even integration with external APIs) could be visualized as outputs or further processing steps.

##### Architectural Patterns and Design Principles
- Modular design: The monorepo structure separates concerns (core logic, rendering, CLI, configuration, tests).
- Clear separation of responsibilities: CLI handles user interaction, configuration is abstracted, the core engine orchestrates execution using well-defined models and directives, and rendering is isolated.
- Extensibility: Users can easily add new scenarios or directives without changing the core processing engine.

##### Elements
- Clear labels for each component (e.g. “CLI”, “Configuration Manager”, “Core Engine”, “Directives”, “Registry”, “Tracer/Worker”, “Models”, “Render Markdown”).
- CLI → Config Manager
- Config Manager → Core Engine
- Core Engine (with internal flows among directives, registry, and tracer/worker) → Render Module
- Optionally, include external elements like “Playwright” or “Bun Runtime” to show the external ecosystem in which docwright operates.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["Docwright CLI – Entry Point"]:::utility
    end

    subgraph "Configuration Layer"
        Config["Config Resolver – Loads docwright.config.ts"]:::utility
    end

    subgraph "Core Engine"
        Directives["Directives Engine – Processes DSL directives"]:::processing
        Registry["Registry – Manages test case directives"]:::processing
        subgraph "Tracer/Worker"
            Tracer["Tracer – Tracks execution"]:::processing
            Worker["Worker – Manages concurrency"]:::processing
        end
        Models["Models – Data Structures (Task, Suite, etc.)"]:::processing
    end

    subgraph "Rendering Module"
        Renderer["Markdown Renderer – Generates Documentation Output"]:::processing
    end

    subgraph "External Ecosystem"
        Bun["Bun Runtime"]:::external
        PW["Playwright"]:::external
    end

    CLI -->|"triggers"| Config
    Config -->|"loads_config"| Directives
    Directives -->|"registers"| Registry
    Directives -->|"executes"| Tracer
    Directives -->|"executes"| Worker
    Registry -->|"aggregates"| Models
    Tracer -->|"feeds_data"| Models
    Worker -->|"feeds_data"| Models
    Models -->|"renders_data"| Renderer

    CLI -->|"runs_on"| Bun
    Directives -->|"utilizes"| PW

    click CLI "https://github.com/suiramdev/docwright/tree/develop/packages/core/src/cli"
    click Config "https://github.com/suiramdev/docwright/tree/develop/packages/core/src/config"
    click Directives "https://github.com/suiramdev/docwright/tree/develop/packages/core/src/core/directives"
    click Registry "https://github.com/suiramdev/docwright/blob/develop/packages/core/src/core/registry.ts"
    click Tracer "https://github.com/suiramdev/docwright/blob/develop/packages/core/src/core/tracer.ts"
    click Worker "https://github.com/suiramdev/docwright/blob/develop/packages/core/src/core/worker.ts"
    click Models "https://github.com/suiramdev/docwright/tree/develop/packages/core/src/models"
    click Renderer "https://github.com/suiramdev/docwright/tree/develop/packages/render-markdown/src"

    classDef utility fill:#cce5ff,stroke:#004085,stroke-width:2px
    classDef processing fill:#d4edda,stroke:#155724,stroke-width:2px
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px
```
