# genai-security-project/aibom-generator architecture

> Architecture diagram of the GitHub repository genai-security-project/aibom-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/genai-security-project/aibom-generator
- Repository: https://github.com/genai-security-project/aibom-generator

## Overview

1. **Purpose and shape of the repo**  
   This is a Python application for generating AI Bills of Materials (AIBOMs) from Hugging Face model repositories. It has two user-facing modes: a **CLI** for batch/terminal use and a **web app** for interactive generation and viewing.

2. **Top-level entry points**  
   `src/main.py` is the web runtime entry point, while `src/cli.py` is the command-line entry point. Both route into the same underlying domain logic, which keeps generation behavior consistent across UI and automation.

3. **Controller layer: interface boundary**  
   `src/controllers/cli_controller.py` and `src/controllers/web_controller.py` isolate input handling from business logic. They translate CLI arguments or HTTP form/request data into service calls, then return either a generated AIBOM, an error page, or a downloadable result.

4. **Core orchestration service**  
   `src/models/service.py` appears to be the main application service that coordinates the end-to-end workflow: validate input, retrieve model metadata, extract structured fields, compute scoring, and assemble the final AIBOM payload. This is the central business boundary to draw in an architecture diagram.

5. **Metadata extraction subsystem**  
   `src/models/extractor.py`, `src/models/model_file_extractors.py`, and `src/models/gguf_metadata.py` handle the model-specific parsing logic. They support extracting metadata from Hugging Face model cards and repository files, including GGUF-related metadata and other model artifacts.

6. **Registry and field mapping**  
   `src/models/registry.py` and `src/models/field_registry.json` define how raw model metadata maps into the AIBOM field model. This is the normalization layer that converts heterogeneous source metadata into a consistent internal representation.

7. **Schema and validation boundary**  
   `src/models/schemas.py` plus the bundled JSON schema files in `src/schemas/` anchor the output format to **CycloneDX BOM 1.6/1.7** and **SPDX**-related schema constraints. The repo is explicitly standards-driven, so schema validation is part of the architecture rather than just an export detail.

8. **Scoring and quality feedback**  
   `src/models/scoring.py` computes AIBOM completeness scores and likely generates improvement recommendations. This is a secondary analysis path over the extracted metadata, used to surface gaps in the generated bill of materials.

9. **Utility services and operational controls**  
   `src/utils/` contains cross-cutting helpers: validation, formatting, license detection, summarization, cleanup, rate limiting, captcha, and analytics. These are mostly supporting concerns around reliability, output quality, and abuse prevention, especially for the web-facing side.

10. **Presentation layer for the web UI**  
    `src/templates/` and `src/static/` provide a server-rendered HTML interface with CSS and JavaScript enhancements. The web app produces an interactive result page, an error page, and reusable header/footer includes.

11. **External dependencies and data sources**  
    The primary external source is **Hugging Face model repositories**, from which metadata is extracted. Optional AI-assisted features are implied by the `--inference` and `--summarize` CLI flags and the utility modules, suggesting the app can enrich metadata through inference-backed or summarization steps when configured.

12. **Docs, tests, and delivery pipeline**  
    `docs/aibom-field-mapping/` documents the field mapping logic, which is important for understanding the normalization layer. `tests/` provides coverage for extraction, scoring, validation, licensing, PURL construction, and service behavior, while `.github/workflows/tests.yml` indicates CI enforcement. Packaging and dependency management are Python-native via `pyproject.toml`, `requirements.txt`, and `uv.lock`.

Main entry points: [`src/models/service.py`](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/service.py) (AIBOM service), [`src/controllers/web_controller.py`](https://github.com/genai-security-project/aibom-generator/blob/main/src/controllers/web_controller.py) (Web controller), [`src/models/extractor.py`](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/extractor.py) (Extractor), [`src/controllers/cli_controller.py`](https://github.com/genai-security-project/aibom-generator/blob/main/src/controllers/cli_controller.py) (CLI controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtimes"]
  node_src_main(("Web entry<br/>entrypoint<br/>[main.py]"))
  node_src_cli(("CLI entry<br/>entrypoint<br/>[cli.py]"))
end

subgraph group_core["Core app"]
  node_web_controller["Web controller<br/>[web_controller.py]"]
  node_cli_controller["CLI controller<br/>[cli_controller.py]"]
  node_service["AIBOM service<br/>orchestrator<br/>[service.py]"]
  node_extractor["Extractor<br/>parser<br/>[extractor.py]"]
  node_file_extractors["File extractors<br/>parser set"]
  node_gguf_metadata["GGUF metadata<br/>parser<br/>[gguf_metadata.py]"]
  node_registry["Field registry<br/>mapping<br/>[registry.py]"]
  node_schemas["Schema layer<br/>validation<br/>[schemas.py]"]
  node_scoring["Scoring<br/>analysis<br/>[scoring.py]"]
end

subgraph group_ui["Web UI"]
  node_templates["Templates<br/>presentation<br/>[index.html]"]
  node_static_assets["Static assets<br/>presentation<br/>[style.css]"]
end

subgraph group_support["Support"]
  node_validation["Validation utils<br/>utilities<br/>[validation.py]"]
  node_other_utils["App utils<br/>utilities<br/>[formatter.py]"]
  node_hf_repo[("Hugging Face repos<br/>external source")]
end

node_src_main -->|"routes"| node_web_controller
node_src_cli -->|"routes"| node_cli_controller
node_web_controller -->|"calls"| node_service
node_cli_controller -->|"calls"| node_service
node_service -->|"checks"| node_validation
node_service -->|"fetches"| node_hf_repo
node_service -->|"extracts"| node_extractor
node_extractor -->|"uses"| node_file_extractors
node_extractor -->|"uses"| node_gguf_metadata
node_extractor -->|"normalizes"| node_registry
node_registry -->|"constrains"| node_schemas
node_service -->|"scores"| node_scoring
node_scoring -.->|"feedback"| node_service
node_service -->|"uses"| node_other_utils
node_web_controller -->|"renders"| node_templates
node_web_controller -->|"serves"| node_static_assets

click node_src_main "https://github.com/genai-security-project/aibom-generator/blob/main/src/main.py"
click node_src_cli "https://github.com/genai-security-project/aibom-generator/blob/main/src/cli.py"
click node_web_controller "https://github.com/genai-security-project/aibom-generator/blob/main/src/controllers/web_controller.py"
click node_cli_controller "https://github.com/genai-security-project/aibom-generator/blob/main/src/controllers/cli_controller.py"
click node_service "https://github.com/genai-security-project/aibom-generator/blob/main/src/models/service.py"
click node_extractor "https://github.com/genai-security-project/aibom-generator/blob/main/src/models/extractor.py"
click node_file_extractors "https://github.com/genai-security-project/aibom-generator/blob/main/src/models/model_file_extractors.py"
click node_gguf_metadata "https://github.com/genai-security-project/aibom-generator/blob/main/src/models/gguf_metadata.py"
click node_registry "https://github.com/genai-security-project/aibom-generator/blob/main/src/models/registry.py"
click node_schemas "https://github.com/genai-security-project/aibom-generator/blob/main/src/models/schemas.py"
click node_scoring "https://github.com/genai-security-project/aibom-generator/blob/main/src/models/scoring.py"
click node_validation "https://github.com/genai-security-project/aibom-generator/blob/main/src/utils/validation.py"
click node_other_utils "https://github.com/genai-security-project/aibom-generator/blob/main/src/utils/formatter.py"
click node_templates "https://github.com/genai-security-project/aibom-generator/blob/main/src/templates/index.html"
click node_static_assets "https://github.com/genai-security-project/aibom-generator/blob/main/src/static/css/style.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_main,node_src_cli toneBlue
class node_web_controller,node_cli_controller,node_service,node_extractor,node_file_extractors,node_gguf_metadata,node_registry,node_schemas,node_scoring toneAmber
class node_templates,node_static_assets toneMint
class node_validation,node_other_utils,node_hf_repo toneRose
```

## Components

### Runtimes

CLI and web entry points that launch the application.

- [Web entry](https://github.com/genai-security-project/aibom-generator/blob/main/src/main.py): entrypoint · Starts the web runtime and wires web requests into the app. · `src/main.py`
- [CLI entry](https://github.com/genai-security-project/aibom-generator/blob/main/src/cli.py): entrypoint · Starts terminal usage and routes command arguments into the app. · `src/cli.py`

### Core app

Orchestration, extraction, normalization, scoring, and schema validation.

- [Web controller](https://github.com/genai-security-project/aibom-generator/blob/main/src/controllers/web_controller.py): controller · Translates web input into service calls and response rendering. · `src/controllers/web_controller.py`
- [CLI controller](https://github.com/genai-security-project/aibom-generator/blob/main/src/controllers/cli_controller.py): controller · Translates CLI arguments into service calls and terminal output. · `src/controllers/cli_controller.py`
- [AIBOM service](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/service.py): orchestrator · Coordinates validation, retrieval, extraction, scoring, and final AIBOM assembly. · `src/models/service.py`
- [Extractor](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/extractor.py): parser · Reads model repository content and extracts metadata from cards and files. · `src/models/extractor.py`
- [File extractors](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/model_file_extractors.py): parser set · Specialized parsers for model artifacts and repository file formats. · `src/models/model_file_extractors.py`
- [GGUF metadata](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/gguf_metadata.py): parser · Extracts metadata from GGUF model files. · `src/models/gguf_metadata.py`
- [Field registry](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/registry.py): mapping · Maps heterogeneous source metadata into normalized AIBOM fields. · `src/models/registry.py`
- [Schema layer](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/schemas.py): validation · Defines and validates the output against BOM and SPDX schemas. · `src/models/schemas.py`
- [Scoring](https://github.com/genai-security-project/aibom-generator/blob/main/src/models/scoring.py): analysis · Computes completeness scores and quality feedback for generated AIBOMs. · `src/models/scoring.py`

### Web UI

Server-rendered templates and static assets for the interactive interface.

- [Templates](https://github.com/genai-security-project/aibom-generator/blob/main/src/templates/index.html): presentation · Server-rendered HTML views for index, result, and error pages. · `src/templates/index.html`
- [Static assets](https://github.com/genai-security-project/aibom-generator/blob/main/src/static/css/style.css): presentation · CSS, JavaScript, and images for the web interface. · `src/static/css/style.css`

### Support

Cross-cutting utilities and external data/control dependencies.

- [Validation utils](https://github.com/genai-security-project/aibom-generator/blob/main/src/utils/validation.py): utilities · Shared validation and input-checking helpers used across the app. · `src/utils/validation.py`
- [App utils](https://github.com/genai-security-project/aibom-generator/blob/main/src/utils/formatter.py): utilities · Formatting, licensing, summarization, cleanup, rate limiting, captcha, and analytics helpers. · `src/utils/formatter.py`
- **Hugging Face repos**: external source · Primary external model repository source consumed by the generator.

## Connections

- Web entry → Web controller: routes · Web entry hands control to the web controller.
- CLI entry → CLI controller: routes · CLI entry hands control to the CLI controller.
- Web controller → AIBOM service: calls · Web requests are converted into service operations.
- CLI controller → AIBOM service: calls · CLI commands are converted into service operations.
- AIBOM service → Validation utils: checks · Service validates input and intermediate results.
- AIBOM service → Hugging Face repos: fetches · Service pulls metadata from Hugging Face model repositories.
- AIBOM service → Extractor: extracts · Service delegates model parsing to the main extractor.
- Extractor → File extractors: uses · Core extraction relies on specialized file parsers.
- Extractor → GGUF metadata: uses · GGUF parsing is handled by a dedicated metadata path.
- Extractor → Field registry: normalizes · Extracted fields are mapped into the internal field model.
- Field registry → Schema layer: constrains · Normalized output is shaped to schema-backed structures.
- AIBOM service → Scoring: scores · Service computes completeness and quality metrics.
- Scoring → AIBOM service: feedback · Scoring informs the final AIBOM payload and recommendations.
- AIBOM service → App utils: uses · Service uses shared helpers for formatting, licensing, and operational controls.
- Web controller → Templates: renders · Web controller renders pages for index, results, and errors.
- Web controller → Static assets: serves · Web UI depends on static styling and client-side behavior.