# sjquant/sitemapr architecture

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

- Interactive diagram: https://gitdiagram.com/sjquant/sitemapr
- Repository: https://github.com/sjquant/sitemapr

## Overview

##### Project Type and Purpose
- sitemapr is a Python library intended to help users generate and save sitemaps for websites. Its usage is demonstrated via a public API (with classes like Page, Param, and SiteMapr), and it offers features like dynamic URL parameters, chunked sitemaps, and customizable base URLs.
- The project is packaged for distribution through pip (as indicated by the pyproject.toml) and includes a type hint file (py.typed) to signal modern Python type annotations.

##### File Structure
- Top-level directories/files:
- .github/workflows: Contains CI/CD configurations for testing and publishing the library.
- README.md & LICENSE: Provide usage examples, documentation, and licensing information.
- pyproject.toml: Defines project build configurations and packaging details.
- The sitemapr directory includes:
- __init__.py: Marks the package.
- core.py: Likely contains the core logic for generating sitemaps.
- models.py: Holds domain models such as definitions for Page, Param, etc.
- The tests directory provides test coverage (e.g., tests/test_core.py) to validate library functionality.

a. Main Components:
- Public API Layer: Representing the entry points of the library used by developers (the classes and functions exposed via the __init__.py module).
- Sitemap Generation Core: Contained in core.py. This is where the primary logic for generating, chunking, and saving sitemaps lives.
- Domain Models: In models.py, where key objects like Page and Param are defined.
- Testing Suite: Represented in tests, ensuring that core functionalities are validated.
- Build/CI Pipeline: Under .github/workflows, which manage testing and publication processes.
- Packaging & Distribution: Managed by pyproject.toml and other project metadata files.

b. Relationships and Interactions:
- The Public API interacts with the Core logic. When a user instantiates a SiteMapr object, input data (pages, parameters) is passed into the underlying core logic that utilizes domain models.
- The Core module and Models module work closely: the core logic makes use of the models defined for pages and parameters.
- Tests simulate usage of the Public API and verify that interactions between core and models lead to the correct sitemap output.
- CI/CD and packaging components ensure this workflow is continuously tested, built, and published.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: The API, core logic, and data models are clearly divided.
- Modularity: Files and directories are project-specific, which simplifies testing, packaging, and future extensions.
- Automated CI/CD: The inclusion of GitHub workflows for testing and publishing reflects modern development practices.

d. Relevant Technologies/Frameworks:
- Python as-is (with type hints, indicated by the py.typed file).
- CI/CD using GitHub Actions.
- Packaging standards defined in pyproject.toml.

- A “CI/CD and Build” section indicating the workflows under .github.
- A “Packaging & Distribution” block showing pyproject.toml, README.md, LICENSE, etc.

- Data flow from the Public API to the Core Logic.
- That Core Logic uses Domain Models.
- That the Test Suite verifies the Public API & Core Logic.

- Core operational components (API, Core, Models).
- Supporting components (Tests, CI/CD, Packaging).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Library Components"
        A["Public API"]:::api
        B["Core Logic"]:::core
        C["Domain Models"]:::models
    end

    subgraph "Supporting Components"
        D["Test Suite"]:::testing
        E["CI/CD & Build"]:::cicd
        subgraph "Packaging & Distribution"
            F1["pyproject.toml"]:::packaging
            F2["README.md"]:::packaging
            F3["LICENSE"]:::packaging
        end
    end

    A -->|"calls"| B
    B -->|"uses"| C
    D -->|"validates"| A
    D -->|"validates"| B
    E -->|"triggers"| D
    E -->|"initiates"| F1
    E -->|"initiates"| F2
    E -->|"initiates"| F3
    F1 -->|"distributes"| A

    click A "https://github.com/sjquant/sitemapr/blob/main/sitemapr/__init__.py"
    click B "https://github.com/sjquant/sitemapr/blob/main/sitemapr/core.py"
    click C "https://github.com/sjquant/sitemapr/blob/main/sitemapr/models.py"
    click D "https://github.com/sjquant/sitemapr/blob/main/tests/test_core.py"
    click E "https://github.com/sjquant/sitemapr/tree/main/.github/workflows/"
    click F1 "https://github.com/sjquant/sitemapr/blob/main/pyproject.toml"
    click F2 "https://github.com/sjquant/sitemapr/blob/main/README.md"
    click F3 "https://github.com/sjquant/sitemapr/tree/main/LICENSE"

    classDef api fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef core fill:#6495ed,stroke:#333,stroke-width:2px;
    classDef models fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef testing fill:#ffa07a,stroke:#333,stroke-width:2px;
    classDef cicd fill:#f0e68c,stroke:#333,stroke-width:2px;
    classDef packaging fill:#ffb6c1,stroke:#333,stroke-width:2px;
```
