# astewartau/dicompare architecture

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

- Interactive diagram: https://gitdiagram.com/astewartau/dicompare
- Repository: https://github.com/astewartau/dicompare

## Overview

##### Main Components
- Command-line Interface (CLI): Located under dicompare/cli, including entry points like “dcm-gen-session”, “dcm-check-session”, and “start_web”. These components act as interfaces for users to either generate or validate sessions.
- Testing Suite: The tests directory (with fixtures and several test modules) represents the testing layer that verifies module behavior.
- Documentation & Guidelines: The docs and guidelines directories are used to provide guidance and reference implementations (like qsm). They are important to show how guidelines are integrated and where developer/user documentation exists.
- CI/CD and Configuration: The .github/workflows files and configuration files (setup.py, .gitignore, LICENSE) are supporting elements that manage releases, packaging, and version control.
- External Artifacts: The valid_fields.json file and image assets (under img) serve as ancillary resources for the tool.

##### Relationships and Interactions
- The CLI and Browser-based Interface (front-end) both funnel into the core library. They trigger operations such as reading a DICOM session (via the IO module) and then using the compliance module to compare sessions based on JSON schemas.
- Both interfaces leverage the Python API for generating the schema and performing compliance checks.
- The testing suite interacts with the core modules to ensure proper functionality.
- The CI/CD pipeline (GitHub Actions) integrates with the repository to build, test, and publish releases, ensuring that changes in the codebase are continuously validated.
- The guidelines saved under the guidelines folder get used by the core validation routines as reference points for domain-specific checks (for instance, the QSM guidelines).

##### Architectural Patterns and Design Principles
- Separation of Concerns: The design clearly separates the CLI/API functionality (in dicompare/cli) from the core logic (in modules like io.py, compliance.py, etc.).
- Modularity: Each component (schema generation, compliance checking, data I/O) is encapsulated within its module, allowing them to be individually tested and reused.
- Extensibility: The presence of guidelines and the structure of the package suggest that the tool is designed for easy extension, whether for additional study protocols or domain guidelines.
- Automated Testing & CI: Integration of GitHub workflows showcases a design principle that emphasizes testing and continuous integration.

##### Including Essential Technologies and Tools
- Python as the primary language.
- Pyodide/WASM for browser-based execution.
- GitHub Actions for CI/CD.
- JSON for schema representation.
- Testing frameworks (likely pytest or similar) for running the tests in dicompare/tests.
- Standard file-based configuration (setup.py, .gitignore).

##### Essential Elements
- Clearly Labeled Components: Each major component (CLI, core library modules, Browser Interface, Test Suite, CI/CD) should be clearly labeled.
- Integration Points: Highlight points where external tools (e.g., GitHub workflows, external guidelines) interface with the system.

##### Putting It All Together
- Session I/O (dicompare/io.py)
- Schema Generation (from the CLI commands and supporting functions)
- Compliance Checking (dicompare/compliance.py)
- Utility/Mapping functions (mapping.py, validation.py, utils.py)
- From the API layer, illustrate the output path that produces JSON schema files and compliance reports.
- To the side, add blocks for:
- Testing (illustrating tests running against these modules)
- Deployment/CI (GitHub workflows indicating automatic builds and tests)
- Documentation (docs) and Domain Guidelines (guidelines)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces
    subgraph "User Interfaces"
        subgraph "CLI"
            CLI1["dcm-gen-session (gen_session.py)"]:::ui
            CLI2["dcm-check-session (check_session.py)"]:::ui
        end
        subgraph "Browser Interface"
            WEB1["start_web (start_web.py)"]:::ui
            WEB2["CORS HTTP Server (cors_http_server.py)"]:::ui
        end
    end

    %% Core Library and API Components
    subgraph "Core Python API"
        CORE["Core Library (dicompare)"]:::core
        IO["Session I/O (dicompare/io.py)"]:::core
        COMP["Compliance Check (dicompare/compliance.py)"]:::core
        UTIL["Utilities & Mapping (dicompare/mapping.py, dicompare/utils.py, dicompare/validation.py)"]:::core
        OUTPUT["Output: JSON Schema & Compliance Report"]:::core
    end

    %% Supporting Components
    TEST["Testing Suite (dicompare/tests)"]:::test
    CICD["CI/CD Pipeline (.github/workflows)"]:::ci
    DOCS["Documentation (docs)"]:::doc
    GUIDELINES["Guidelines (guidelines/qsm)"]:::doc
    CONFIG["Configuration (setup.py, .gitignore, LICENSE)"]:::external
    EXTERNAL["External Artifacts (valid_fields.json, img)"]:::external

    %% User Interfaces feeding into Core Library
    CLI1 --> CORE
    CLI2 --> CORE
    WEB1 --> CORE
    WEB2 --> CORE

    %% Core API internal flow
    CORE --> IO
    IO --> COMP
    UTIL --> COMP
    COMP --> OUTPUT

    %% Supporting components interactions
    TEST --> CORE
    CICD --> TEST
    DOCS --> COMP
    GUIDELINES --> COMP
    EXTERNAL --> COMP
    CONFIG --> CICD

    %% Click Events for CLI Components
    click CLI1 "https://github.com/astewartau/dicompare/blob/main/dicompare/cli/gen_session.py"
    click CLI2 "https://github.com/astewartau/dicompare/blob/main/dicompare/cli/check_session.py"
    click WEB1 "https://github.com/astewartau/dicompare/blob/main/dicompare/cli/start_web.py"
    click WEB2 "https://github.com/astewartau/dicompare/blob/main/dicompare/cli/cors_http_server.py"

    %% Click Events for Core Library Components
    click CORE "https://github.com/astewartau/dicompare/tree/main/dicompare"
    click IO "https://github.com/astewartau/dicompare/blob/main/dicompare/io.py"
    click COMP "https://github.com/astewartau/dicompare/blob/main/dicompare/compliance.py"
    click UTIL "https://github.com/astewartau/dicompare/blob/main/dicompare/mapping.py"

    %% Click Events for Supporting Components
    click TEST "https://github.com/astewartau/dicompare/tree/main/dicompare/tests"
    click DOCS "https://github.com/astewartau/dicompare/tree/main/docs"
    click GUIDELINES "https://github.com/astewartau/dicompare/tree/main/guidelines/qsm"
    click CICD "https://github.com/astewartau/dicompare/tree/main/.github/workflows"
    click CONFIG "https://github.com/astewartau/dicompare/blob/main/setup.py"
    click EXTERNAL "https://github.com/astewartau/dicompare/blob/main/valid_fields.json"

    %% Styles
    classDef ui fill:#d9ead3,stroke:#38761d,stroke-width:2px
    classDef core fill:#c9daf8,stroke:#1155cc,stroke-width:2px
    classDef test fill:#ffe599,stroke:#bf9000,stroke-width:2px
    classDef ci fill:#ead1dc,stroke:#b854a1,stroke-width:2px
    classDef doc fill:#d9d2e9,stroke:#734f96,stroke-width:2px
    classDef external fill:#fff2cc,stroke:#bf9000,stroke-width:2px
```
