# naveeth235/apiguard architecture

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

- Interactive diagram: https://gitdiagram.com/naveeth235/apiguard
- Repository: https://github.com/naveeth235/apiguard

## Overview

APIGuard is a CLI for provider-side contract verification: it loads JSON contracts, sends real HTTP requests to a running provider, validates response status and body shape, and produces console or HTML results. Failed contracts can optionally receive AI explanations; deterministic validation remains authoritative. The repository also includes an e-commerce demo spanning customer profiles, catalog, inventory, and orders. The graph preserves these product branches. Some runner, loader, reporting, and analysis relationships are inferred from the documented workflow rather than sampled implementation, so those edges are dashed and uncited.

Main entry points: [`src/main/java/apiguard/runner/ContractRunner.java`](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/runner/ContractRunner.java) (Contract Runner), [`src/main/java/apiguard/runner/APIGuardRunner.java`](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/runner/APIGuardRunner.java) (APIGuard Runner), [`src/main/java/apiguard/executor/TestExecutor.java`](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/executor/TestExecutor.java) (HTTP Executor), [`src/main/java/apiguard/validator/ResponseValidator.java`](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/validator/ResponseValidator.java) (Response Validator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guard["Contract Verification"]
  node_contracts["JSON Contracts<br/>[Contract.java]"]
  node_request_schema["Request Schema<br/>[Request.java]"]
  node_contract_loader["Contract Loader"]
  node_api_runner["APIGuard Runner"]
  node_contract_runner["Contract Runner"]
  node_test_executor["HTTP Executor<br/>[TestExecutor.java]"]
end

subgraph group_results["Validation And Reports"]
  node_response_validator["Response Validator"]
  node_failure_analysis["Failure Analysis"]
  node_test_report["Test Reports"]
  node_html_report["HTML Report"]
end

subgraph group_ai["Optional AI Analysis"]
  node_ai_context["Failure Context"]
  node_ai_service["AI Analysis"]
  node_ollama["Ollama Provider"]
  node_mock_ai["Mock Provider"]
end

subgraph group_commerce["Commerce Demo"]
  node_catalog["Product Catalog"]
  node_inventory[("Inventory")]
  node_orders[("Order Processing<br/>[OrderService.java]")]
end

subgraph group_identity["Identity Demo"]
  node_user_profiles["Customer Profiles"]
  node_provider_users["Provider Users<br/>[UserService.java]"]
end

node_cli_user(("CLI User"))
node_provider(("Running Provider"))
node_ollama_service(("Ollama Service"))

node_cli_user -.->|"starts CLI"| node_api_runner
node_api_runner -.->|"loads contracts"| node_contract_loader
node_contract_loader -.->|"reads JSON"| node_contracts
node_contracts -->|"defines request"| node_request_schema
node_api_runner -.->|"runs suite"| node_contract_runner
node_contract_runner -.->|"sends requests"| node_test_executor
node_test_executor -.->|"HTTP requests"| node_provider
node_test_executor -.->|"validates response"| node_response_validator
node_response_validator -->|"checks expectations"| node_contracts
node_response_validator -->|"classifies failures"| node_failure_analysis
node_contract_runner -.->|"collects results"| node_test_report
node_test_report -.->|"renders HTML"| node_html_report
node_contract_runner -.->|"builds failure context"| node_ai_context
node_ai_context -.->|"requests explanation"| node_ai_service
node_ai_service -.->|"selects provider"| node_ollama
node_ai_service -.->|"selects provider"| node_mock_ai
node_ollama -->|"sends analysis request"| node_ollama_service
node_user_profiles -.->|"serves profile data"| node_user_profiles
node_provider_users -->|"manages users"| node_provider_users
node_catalog -->|"serves product data"| node_catalog
node_orders -->|"fetches products"| node_catalog
node_orders -->|"reserves stock"| node_inventory

click node_contracts "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/contract/Contract.java"
click node_request_schema "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/contract/Request.java"
click node_contract_loader "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/loader/ContractLoader.java"
click node_api_runner "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/runner/APIGuardRunner.java"
click node_contract_runner "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/runner/ContractRunner.java"
click node_test_executor "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/executor/TestExecutor.java"
click node_response_validator "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/validator/ResponseValidator.java"
click node_failure_analysis "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/analysis/FailureAnalyzer.java"
click node_test_report "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/report/TestSuiteReport.java"
click node_html_report "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/report/HtmlReportGenerator.java"
click node_ai_context "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/FailureContextBuilder.java"
click node_ai_service "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/AIAnalysisService.java"
click node_ollama "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/OllamaAIAnalysisService.java"
click node_mock_ai "https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/MockAIAnalysisService.java"
click node_user_profiles "https://github.com/naveeth235/apiguard/blob/main/user-service/src/main/java/com/apiguard/userservice/service/UserProfileService.java"
click node_provider_users "https://github.com/naveeth235/apiguard/blob/main/provider-service/src/main/java/com/apiguard/provider/service/UserService.java"
click node_catalog "https://github.com/naveeth235/apiguard/blob/main/catalog-service/src/main/java/com/apiguard/catalogservice/service/CatalogService.java"
click node_inventory "https://github.com/naveeth235/apiguard/blob/main/inventory-service/src/main/java/com/apiguard/inventoryservice/service/InventoryService.java"
click node_orders "https://github.com/naveeth235/apiguard/blob/main/order-service/src/main/java/com/apiguard/orderservice/service/OrderService.java"

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_contracts,node_request_schema,node_contract_loader,node_api_runner,node_contract_runner,node_test_executor,node_cli_user toneBlue
class node_response_validator,node_failure_analysis,node_test_report,node_html_report toneAmber
class node_ai_context,node_ai_service,node_ollama,node_mock_ai toneMint
class node_catalog,node_inventory,node_orders toneRose
class node_user_profiles,node_provider_users,node_provider,node_ollama_service toneIndigo
```

## Components

### Contract Verification

- [JSON Contracts](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/contract/Contract.java): `src/main/java/apiguard/contract/Contract.java`
- [Request Schema](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/contract/Request.java): `src/main/java/apiguard/contract/Request.java`
- [Contract Loader](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/loader/ContractLoader.java): `src/main/java/apiguard/loader/ContractLoader.java`
- [APIGuard Runner](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/runner/APIGuardRunner.java): `src/main/java/apiguard/runner/APIGuardRunner.java`
- [Contract Runner](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/runner/ContractRunner.java): `src/main/java/apiguard/runner/ContractRunner.java`
- [HTTP Executor](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/executor/TestExecutor.java): `src/main/java/apiguard/executor/TestExecutor.java`

### Validation And Reports

- [Response Validator](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/validator/ResponseValidator.java): `src/main/java/apiguard/validator/ResponseValidator.java`
- [Failure Analysis](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/analysis/FailureAnalyzer.java): `src/main/java/apiguard/analysis/FailureAnalyzer.java`
- [Test Reports](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/report/TestSuiteReport.java): `src/main/java/apiguard/report/TestSuiteReport.java`
- [HTML Report](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/report/HtmlReportGenerator.java): `src/main/java/apiguard/report/HtmlReportGenerator.java`

### Optional AI Analysis

- [Failure Context](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/FailureContextBuilder.java): `src/main/java/apiguard/ai/FailureContextBuilder.java`
- [AI Analysis](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/AIAnalysisService.java): `src/main/java/apiguard/ai/AIAnalysisService.java`
- [Ollama Provider](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/OllamaAIAnalysisService.java): `src/main/java/apiguard/ai/OllamaAIAnalysisService.java`
- [Mock Provider](https://github.com/naveeth235/apiguard/blob/main/src/main/java/apiguard/ai/MockAIAnalysisService.java): `src/main/java/apiguard/ai/MockAIAnalysisService.java`

### Commerce Demo

- [Product Catalog](https://github.com/naveeth235/apiguard/blob/main/catalog-service/src/main/java/com/apiguard/catalogservice/service/CatalogService.java): `catalog-service/src/main/java/com/apiguard/catalogservice/service/CatalogService.java`
- [Inventory](https://github.com/naveeth235/apiguard/blob/main/inventory-service/src/main/java/com/apiguard/inventoryservice/service/InventoryService.java): `inventory-service/src/main/java/com/apiguard/inventoryservice/service/InventoryService.java`
- [Order Processing](https://github.com/naveeth235/apiguard/blob/main/order-service/src/main/java/com/apiguard/orderservice/service/OrderService.java): `order-service/src/main/java/com/apiguard/orderservice/service/OrderService.java`

### Identity Demo

- [Customer Profiles](https://github.com/naveeth235/apiguard/blob/main/user-service/src/main/java/com/apiguard/userservice/service/UserProfileService.java): `user-service/src/main/java/com/apiguard/userservice/service/UserProfileService.java`
- [Provider Users](https://github.com/naveeth235/apiguard/blob/main/provider-service/src/main/java/com/apiguard/provider/service/UserService.java): `provider-service/src/main/java/com/apiguard/provider/service/UserService.java`

### Other components

- **CLI User**
- **Running Provider**
- **Ollama Service**

## Connections

- CLI User → APIGuard Runner: starts CLI
- APIGuard Runner → Contract Loader: loads contracts
- Contract Loader → JSON Contracts: reads JSON
- JSON Contracts → Request Schema: defines request (evidence: `src/main/java/apiguard/contract/Contract.java`)
- APIGuard Runner → Contract Runner: runs suite
- Contract Runner → HTTP Executor: sends requests
- HTTP Executor → Running Provider: HTTP requests (evidence: `README.md`)
- HTTP Executor → Response Validator: validates response
- Response Validator → JSON Contracts: checks expectations (evidence: `src/main/java/apiguard/validator/ResponseValidator.java`)
- Response Validator → Failure Analysis: classifies failures (evidence: `src/main/java/apiguard/validator/ResponseValidator.java`)
- Contract Runner → Test Reports: collects results
- Test Reports → HTML Report: renders HTML
- Contract Runner → Failure Context: builds failure context
- Failure Context → AI Analysis: requests explanation
- AI Analysis → Ollama Provider: selects provider (evidence: `README.md`)
- AI Analysis → Mock Provider: selects provider (evidence: `README.md`)
- Ollama Provider → Ollama Service: sends analysis request (evidence: `src/main/java/apiguard/ai/OllamaAIAnalysisService.java`)
- Customer Profiles → Customer Profiles: serves profile data (evidence: `README.md`)
- Provider Users → Provider Users: manages users (evidence: `provider-service/src/main/java/com/apiguard/provider/service/UserService.java`)
- Product Catalog → Product Catalog: serves product data (evidence: `catalog-service/src/main/java/com/apiguard/catalogservice/service/CatalogService.java`)
- Order Processing → Product Catalog: fetches products (evidence: `order-service/src/main/java/com/apiguard/orderservice/service/OrderService.java`)
- Order Processing → Inventory: reserves stock (evidence: `order-service/src/main/java/com/apiguard/orderservice/service/OrderService.java`)
