# asauvage/apisentinel architecture

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

- Interactive diagram: https://gitdiagram.com/asauvage/apisentinel
- Repository: https://github.com/asauvage/apisentinel

## Overview

##### Project Type and Purpose
- This is an open-source, mapping-driven API testing tool written in Python.
- It reads JSON/YAML mappings that describe expected API responses, issues HTTP requests, validates responses, and stores results in MongoDB.

##### File Structure Analysis
- Top-level entrypoints:
- launcher.py and shortcut.py – CLI/bootstrap modules
- data/ – holds service mapping JSONs, YAMLs and a central service_config.py
- models/ – core domain logic: GlobalTester, Tester, Service, ResultsManager, Errors
- utils/ – helper libraries: commons, mapping loader, mapping tester, HTTP request, MongoDB client
- tests/ – unit tests covering models and utils
- Configuration files: requirements.txt, .github/workflows/unit_test.yaml
- Data folder follows a per-service subfolder pattern, with optional generics folder for reusable schemas.

##### README Insights
- Describes mapping DSL for JSON response validation (Number, String, Boolean, Object, Array types).
- Shows how to configure a new service and extend via subclassing GlobalTester.
- External dependencies: Python ≥3.9, a MongoDB server, and the target API under test.

##### Main Components
a. CLI Layer
- launcher.py / shortcut.py
- Parses command-line args (environment, custom headers/options)
- Instantiates a GlobalTester subclass
b. Configuration Layer
- data/service_config.py (SERVICE definitions)
- Mapping files (data/mapping/<service>/<mapping>.json / .yaml)
- Generics subfolder for shared schemas
c. Core Test Engine
- models.GlobalTester: orchestrates test session
- models.Tester: per-endpoint validation logic
- models.Service: holds service metadata (paths, URLs, headers)
- utils.mapping & utils.mapping_tester: parse mappings and perform schema checks
- utils.request_api: issues HTTP GET calls to external API
d. Persistence Layer
- models.ResultsManager: aggregates test results
- utils.mongodb: writes test sessions and results into MongoDB
e. External Systems
- Target API Endpoints (e.g., pokeapi.co)
- MongoDB Server
- (Optional) APISentinel Dashboard for results visualization

##### Relationships and Data Flow
1) User invokes CLI → GlobalTester
2) GlobalTester reads service_config & mapping files
3) For each mapping / endpoint:
- Build full URL (service.url + path + extended_path)
- Call utils.request_api → HTTP response (JSON)
- Pass JSON + mapping to utils.mapping_tester → validation results/errors
- Send results to ResultsManager
4) ResultsManager uses utils.mongodb to persist session, response, errors
5) CLI prints session ID / summary; dashboard can query MongoDB

##### Architectural Patterns and Design Principles
- Layered architecture (CLI → Configuration → Core Engine → Persistence)
- Single Responsibility modules (mapping vs HTTP vs DB vs domain logic)
- Extensibility via subclassing (GlobalTester) and mapping generics
- Configuration-driven behavior (data folder controls tests, no code change)

##### Technologies and Frameworks
- Python 3.9+
- requests library (via utils/request_api)
- PyYAML or ruamel.yaml (for YAML endpoint specs)
- pymongo (MongoDB client)
- unittest / pytest (in tests/)
- GitHub Actions for CI (.github/workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        launcher["launcher.py"]:::code
        shortcut["shortcut.py"]:::code
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        service_config["data/services_config.py"]:::config
        mapping_files["Mapping Files\n(data/mapping/pokeapi/*.json/.yaml)"]:::config
        generics["Generics Schemas\n(data/mapping/pokeapi/generics/)"]:::config
    end

    %% Core Test Engine
    subgraph "Core Test Engine"
        direction TB
        globaltester["GlobalTester\n(models/global_tester.py)"]:::code
        tester["Tester\n(models/tester.py)"]:::code
        service["Service Model\n(models/service.py)"]:::code
        errors["Errors\n(models/errors.py)"]:::code
        mapping_loader["Mapping Loader\n(utils/mapping.py)"]:::code
        mapping_tester["Mapping Tester\n(utils/mapping_tester.py)"]:::code
        request_api["HTTP Client\n(utils/request_api.py)"]:::code
        commons["Common Utils\n(utils/commons.py)"]:::code
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        results_manager["ResultsManager\n(models/results_manager.py)"]:::code
        mongodb_adapter["MongoDB Adapter\n(utils/mongodb.py)"]:::code
    end

    %% External Services
    subgraph "External Systems"
        direction TB
        api["Target API Endpoints"]:::external
        mongodb["MongoDB Server"]:::external
        dashboard["APISentinel Dashboard\n(Optional)"]:::external
    end

    %% Data Flow
    launcher -->|"invoke"| globaltester
    shortcut -->|"invoke subclass"| globaltester

    globaltester -->|"reads"| service_config
    globaltester -->|"loads mapping"| mapping_loader
    mapping_loader -->|"parses files"| mapping_files
    mapping_loader -->|"loads schemas"| generics

    globaltester -->|"creates"| service
    globaltester -->|"handles errors"| errors
    globaltester -->|"orchestrates"| tester

    tester -->|"issues request"| request_api
    request_api -->|"HTTP GET"| api
    api -->|"JSON response"| request_api
    request_api -->|"returns JSON"| tester

    tester -->|"validates JSON"| mapping_tester
    mapping_tester -->|"uses schemas"| mapping_loader

    mapping_tester -->|"ValidationResult"| results_manager
    results_manager -->|"persist session"| mongodb_adapter
    mongodb_adapter -->|"writes data"| mongodb

    globaltester -->|"summary"| launcher
    mongodb -->|"serves data"| dashboard

    %% Click Events
    click launcher "https://github.com/asauvage/apisentinel/blob/main/launcher.py"
    click shortcut "https://github.com/asauvage/apisentinel/blob/main/shortcut.py"
    click service_config "https://github.com/asauvage/apisentinel/blob/main/data/services_config.py"
    click mapping_files "https://github.com/asauvage/apisentinel/tree/main/data/mapping/pokeapi/"
    click generics "https://github.com/asauvage/apisentinel/tree/main/data/mapping/pokeapi/generics/"
    click globaltester "https://github.com/asauvage/apisentinel/blob/main/models/global_tester.py"
    click tester "https://github.com/asauvage/apisentinel/blob/main/models/tester.py"
    click service "https://github.com/asauvage/apisentinel/blob/main/models/service.py"
    click errors "https://github.com/asauvage/apisentinel/blob/main/models/errors.py"
    click results_manager "https://github.com/asauvage/apisentinel/blob/main/models/results_manager.py"
    click mapping_loader "https://github.com/asauvage/apisentinel/blob/main/utils/mapping.py"
    click mapping_tester "https://github.com/asauvage/apisentinel/blob/main/utils/mapping_tester.py"
    click request_api "https://github.com/asauvage/apisentinel/blob/main/utils/request_api.py"
    click mongodb_adapter "https://github.com/asauvage/apisentinel/blob/main/utils/mongodb.py"
    click commons "https://github.com/asauvage/apisentinel/blob/main/utils/commons.py"

    %% Styles
    classDef code fill:#e0f7e9,stroke:#2e7d32,color:#1b5e20
    classDef config fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
```
