# piotrfleury/discover architecture

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

- Interactive diagram: https://gitdiagram.com/piotrfleury/discover
- Repository: https://github.com/piotrfleury/discover

## Overview

Step 1: Identify the project type and purpose
- This is a Dart-based command-line interface (CLI) tool called “discover” whose main job is to analyze a Dart/Flutter project’s coverage data, find untested Dart source files, generate an updated coverage file (discover-lcov.info), and produce an HTML report.
- It is not a web or mobile app; it is a developer tool that invokes underlying test runners (e.g. flutter test --coverage), parses coverage outputs, and writes new reports.

Step 2: Analyze the file structure
- bin/discover.dart: the Dart CLI entrypoint.
- lib/src/command_runner.dart: sets up the CLI framework (parses args, dispatches commands).
- lib/src/commands/scan_command.dart & update_command.dart: implement the “scan” and “update” sub-commands.
- lib/src/converters: modules that parse LCOV files and Dart source to extract coverage and code-line metrics.
- lib/src/system/system_runner.dart: abstracts process invocation (calling flutter test, genhtml, opening files).
- lib/src/extensions & models: utility extensions on filesystem entities and data models (e.g., CodeLine).
- flutter_example/: a sample Flutter app project used to demonstrate Discover against a real codebase.
- test/: unit tests for each command, converter, extension, and runner.

Step 3: Examine the README for extra insights
- The “scan” command: looks for an existing coverage tracefile or runs `flutter test --coverage`, reads lcov.info, finds untested sources, writes discover-lcov.info, and generates an HTML report.
- There’s an “ignore” mechanism via a .discoverignore file to filter out files and patterns.
- A minimal “update” command exists (likely to merge or refresh coverage).

a. CLI Layer
- Entrypoint (bin/discover.dart)
- Command Runner (lib/src/command_runner.dart)
b. Command Modules
- ScanCommand
- UpdateCommand
c. Core Services
- SystemRunner (process orchestration)
- Converters
– LcovConverter (parses coverage data)
– DartParser (scans Dart files)
d. Data & Models
- CodeLine model
- Version info
- .discoverignore patterns
e. External Dependencies/Tools
- Flutter test runner (shell command)
- genhtml (coverage HTML generator)
- File system (source directories, lcov.info, discover-lcov.info)
f. User Environment
- Developer’s terminal (stdin/stdout)
- Browser (for HTML report)

Step 5: Determine relationships and data flows
##### ScanCommand asks SystemRunner: “Is there an existing lcov.info?”
– If no, SystemRunner runs `flutter test --coverage`.
##### SystemRunner optionally opens the HTML in a browser.

Step 6: Highlight architectural patterns and design principles
- Modular command pattern: each CLI sub-command is isolated (Scan, Update).
- Separation of concerns: converters handle parsing, SystemRunner isolates side-effects, extensions provide reusable helpers.
- Extensibility: new commands or converters can be added under lib/src/commands or lib/src/converters.

- Flow from user input → core logic → external tools → output artifacts.
- Clear boundaries between in-process components (Dart modules) and out-of-process tools (flutter test, genhtml).
- Plugin/ignore extension point (.discoverignore file).

- Use rectangles for in-process modules (CommandRunner, ScanCommand, LcovConverter, DartParser, SystemRunner).
- Use parallelograms for external tools (Flutter test, genhtml, Browser).
- CLI input → CommandRunner → Commands
- Commands → SystemRunner → External tool
- External tool output → Converters → Commands
- Commands → File system → HTML report
- Commands → SystemRunner → Browser
- Green for core Dart modules
- Blue for external processes/tools
- Orange for data artifacts (coverage files, HTML)

Step 9: Emphasize detail and completeness
- Sub-components under lib/src (commands, converters, system).
- Ignore mechanism as a decision/filter step.
- Error handling paths if relevant (e.g., missing coverage file leads to test run).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Environment
    subgraph "User Environment"
        Dev["Developer Terminal"]:::external
    end

    %% CLI Layer
    Dev -->|"invoke discover scan/update"| CLI["CLI Entrypoint\n(bin/discover.dart)"]:::core
    click CLI "https://github.com/piotrfleury/discover/blob/main/bin/discover.dart"

    CLI -->|"parses args"| CR["CommandRunner\n(lib/src/command_runner.dart)"]:::core
    click CR "https://github.com/piotrfleury/discover/blob/main/lib/src/command_runner.dart"

    %% Commands
    subgraph "Commands"
        SC["ScanCommand\n(lib/src/commands/scan_command.dart)"]:::core
        UC["UpdateCommand\n(lib/src/commands/update_command.dart)"]:::core
    end
    click SC "https://github.com/piotrfleury/discover/blob/main/lib/src/commands/scan_command.dart"
    click UC "https://github.com/piotrfleury/discover/blob/main/lib/src/commands/update_command.dart"

    CR --> SC
    CR --> UC

    %% Extensions & Models
    subgraph "Extensions & Models"
        E1["file_extension.dart"]:::core
        E2["file_system_entity_extension.dart"]:::core
        E3["extensions.dart"]:::core
        CL["code_line.dart"]:::core
        VI["version.dart"]:::core
    end
    click E1 "https://github.com/piotrfleury/discover/blob/main/lib/src/extensions/file_extension.dart"
    click E2 "https://github.com/piotrfleury/discover/blob/main/lib/src/extensions/file_system_entity_extension.dart"
    click E3 "https://github.com/piotrfleury/discover/blob/main/lib/src/extensions/extensions.dart"
    click CL "https://github.com/piotrfleury/discover/blob/main/lib/src/models/code_line.dart"
    click VI "https://github.com/piotrfleury/discover/blob/main/lib/src/version.dart"

    %% Core Services
    SC -->|"uses extensions and models"| E3
    SC --> CL
    SC --> VI

    %% Scan Flow
    SC -->|"check for lcov.info"| SR["SystemRunner\n(lib/src/system/system_runner.dart)"]:::core
    click SR "https://github.com/piotrfleury/discover/blob/main/lib/src/system/system_runner.dart"

    %% External Tools and Data
    SR -->|"runs flutter test --coverage"| FT["Flutter Test"]:::external
    FT --> LcovFile["lcov.info"]:::data

    %% Conversion
    LcovFile --> LC["LcovConverter\n(lib/src/converters/lcov_converter.dart)"]:::core
    click LC "https://github.com/piotrfleury/discover/blob/main/lib/src/converters/lcov_converter.dart"
    LC --> CoverageModel["Coverage Data Model"]:::data

    %% Source Parsing
    SC --> DP["DartParser\n(lib/src/converters/dart_parser.dart)"]:::core
    click DP "https://github.com/piotrfleury/discover/blob/main/lib/src/converters/dart_parser.dart"
    DP -->|"reads project .dart files"| FS["File System"]:::external
    FS --> SourceList["Source Files List"]:::data
    DP --> E1
    DP --> E2

    %% Ignore Mechanism
    DP --> Ign[".discoverignore"]:::data

    %% Comparison and Output
    SC -->|"compare coverage vs sources"| UL["Untested Files"]:::data
    UL --> DiscoverLcov["discover-lcov.info"]:::data

    DiscoverLcov -->|"generate HTML"| GH["genhtml"]:::external
    GH --> HTMLRep["HTML Report"]:::data

    HTMLRep -->|"open report"| B["Browser"]:::external

    %% Styles
    classDef core fill:#e0f7e9,stroke:#2e7d32,stroke-width:1px;
    classDef external fill:#e3f2fd,stroke:#1565c0,stroke-width:1px;
    classDef data fill:#fff3e0,stroke:#ef6c00,stroke-width:1px;
```
