# assyaeljou/autonomous-ai-testing-agent architecture

> Architecture diagram of the GitHub repository assyaeljou/autonomous-ai-testing-agent, 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/assyaeljou/autonomous-ai-testing-agent
- Repository: https://github.com/assyaeljou/autonomous-ai-testing-agent

## Overview

Autonomous AI Testing Agent is a human-approved web-testing platform for authorized target sites. Users create a session, explore the site for browser evidence, generate and deterministically validate scenarios, review and approve them, execute them through a constrained action registry, then classify failures and produce reports. QA derives read-only campaign, risk, coverage, and evidence-gap views from persisted results. The graph follows documented workflow and composition boundaries; unsampled subsystems are included from README capabilities, but their internal calls are not inferred.

Main entry points: [`src/ai_testing_agent/graph/workflow.py`](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/graph/workflow.py) (LangGraph workflow), [`src/ai_testing_agent/storage/repositories.py`](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/storage/repositories.py) (Persistence repositories), [`src/ai_testing_agent/exploration/explorer.py`](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/exploration/explorer.py) (Explorer agent), [`src/ai_testing_agent/api/app.py`](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/api/app.py) (FastAPI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User and API"]
  node_ui["Streamlit UI<br/>[app.py]"]
  node_api["FastAPI<br/>[app.py]"]
  node_sessions["Session service<br/>[service.py]"]
end

subgraph group_orchestration["Jobs and workflow"]
  node_jobs["Job runner<br/>[runner.py]"]
  node_workflow["LangGraph workflow<br/>[workflow.py]"]
end

subgraph group_discovery["Exploration and security"]
  node_explore["Explorer agent<br/>[explorer.py]"]
  node_browser["Browser controls<br/>[action_registry.py]"]
  node_urlguard["URL scope guard<br/>[url_validator.py]"]
end

subgraph group_scenario["Scenario design"]
  node_designer["Test designer<br/>[designer.py]"]
  node_validator["Scenario validator<br/>[validator.py]"]
  node_llm["LLM client<br/>[client.py]"]
  node_approval["Scenario approval<br/>[scenarios.py]"]
end

subgraph group_results["Execution and insights"]
  node_executor["Test executor<br/>[executor.py]"]
  node_runtime["Pytest runtime<br/>[runtime_runner.py]"]
  node_analysis["Failure analysis<br/>[service.py]"]
  node_qa["QA coverage<br/>[analysis.py]"]
  node_reporter["Report generator<br/>[reporter.py]"]
  node_db[("SQLite database<br/>[db.py]")]
  node_repos["Persistence repositories<br/>[repositories.py]"]
end

node_user(("Human tester"))
node_target{{"Authorized website"}}
node_llmprovider{{"LLM provider"}}

node_user -->|"uses"| node_ui
node_ui -->|"HTTP requests"| node_api
node_api -->|"dispatches jobs"| node_jobs
node_jobs -->|"runs stages"| node_workflow
node_workflow -->|"invokes exploration"| node_explore
node_explore -->|"observes pages"| node_target
node_explore -.->|"uses controls"| node_browser
node_explore -->|"checks navigation"| node_urlguard
node_workflow -->|"invokes generation"| node_designer
node_designer -->|"requests drafts"| node_llm
node_llm -.->|"structured requests"| node_llmprovider
node_designer -->|"validates drafts"| node_validator
node_user -->|"reviews scenarios"| node_approval
node_approval -->|"approved scenarios"| node_executor
node_workflow -->|"invokes execution"| node_executor
node_executor -->|"runs bundle"| node_runtime
node_runtime -->|"dispatches actions"| node_browser
node_runtime -->|"tests pages"| node_target
node_workflow -->|"invokes analysis"| node_analysis
node_analysis -.->|"optional hypothesis"| node_llm
node_analysis -->|"reads execution rows"| node_repos
node_workflow -->|"generates reports"| node_reporter
node_reporter -->|"reads persisted rows"| node_repos
node_api -->|"serves QA views"| node_qa
node_qa -->|"reads stored evidence"| node_repos
node_sessions -->|"persists sessions"| node_repos
node_repos -->|"queries and writes"| node_db
node_jobs -->|"persists jobs"| node_repos

click node_ui "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/frontend/app.py"
click node_api "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/api/app.py"
click node_sessions "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/sessions/service.py"
click node_jobs "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/jobs/runner.py"
click node_workflow "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/graph/workflow.py"
click node_explore "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/exploration/explorer.py"
click node_browser "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/browser/action_registry.py"
click node_urlguard "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/security/url_validator.py"
click node_designer "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/test_generation/designer.py"
click node_validator "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/test_generation/validator.py"
click node_llm "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/llm/client.py"
click node_approval "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/api/routers/scenarios.py"
click node_executor "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/execution/executor.py"
click node_runtime "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/execution/runtime_runner.py"
click node_analysis "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/analysis/service.py"
click node_qa "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/qa/analysis.py"
click node_reporter "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/reporting/reporter.py"
click node_db "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/storage/db.py"
click node_repos "https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/storage/repositories.py"

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_ui,node_api,node_sessions toneBlue
class node_jobs,node_workflow toneAmber
class node_explore,node_browser,node_urlguard toneMint
class node_designer,node_validator,node_llm,node_approval toneRose
class node_executor,node_runtime,node_analysis,node_qa,node_reporter,node_db,node_repos,node_user,node_target,node_llmprovider toneIndigo
```

## Components

### User and API

- [Streamlit UI](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/frontend/app.py): `src/ai_testing_agent/frontend/app.py`
- [FastAPI](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/api/app.py): `src/ai_testing_agent/api/app.py`
- [Session service](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/sessions/service.py): `src/ai_testing_agent/sessions/service.py`

### Jobs and workflow

- [Job runner](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/jobs/runner.py): `src/ai_testing_agent/jobs/runner.py`
- [LangGraph workflow](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/graph/workflow.py): `src/ai_testing_agent/graph/workflow.py`

### Exploration and security

- [Explorer agent](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/exploration/explorer.py): `src/ai_testing_agent/exploration/explorer.py`
- [Browser controls](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/browser/action_registry.py): `src/ai_testing_agent/browser/action_registry.py`
- [URL scope guard](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/security/url_validator.py): `src/ai_testing_agent/security/url_validator.py`

### Scenario design

- [Test designer](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/test_generation/designer.py): `src/ai_testing_agent/test_generation/designer.py`
- [Scenario validator](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/test_generation/validator.py): `src/ai_testing_agent/test_generation/validator.py`
- [LLM client](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/llm/client.py): `src/ai_testing_agent/llm/client.py`
- [Scenario approval](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/api/routers/scenarios.py): `src/ai_testing_agent/api/routers/scenarios.py`

### Execution and insights

- [Test executor](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/execution/executor.py): `src/ai_testing_agent/execution/executor.py`
- [Pytest runtime](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/execution/runtime_runner.py): `src/ai_testing_agent/execution/runtime_runner.py`
- [Failure analysis](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/analysis/service.py): `src/ai_testing_agent/analysis/service.py`
- [QA coverage](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/qa/analysis.py): `src/ai_testing_agent/qa/analysis.py`
- [Report generator](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/reporting/reporter.py): `src/ai_testing_agent/reporting/reporter.py`
- [SQLite database](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/storage/db.py): `src/ai_testing_agent/storage/db.py`
- [Persistence repositories](https://github.com/assyaeljou/autonomous-ai-testing-agent/blob/main/src/ai_testing_agent/storage/repositories.py): `src/ai_testing_agent/storage/repositories.py`

### Other components

- **Human tester**
- **Authorized website**
- **LLM provider**

## Connections

- Human tester → Streamlit UI: uses
- Streamlit UI → FastAPI: HTTP requests
- FastAPI → Job runner: dispatches jobs
- Job runner → LangGraph workflow: runs stages (evidence: `src/ai_testing_agent/jobs/runner.py`)
- LangGraph workflow → Explorer agent: invokes exploration
- Explorer agent → Authorized website: observes pages
- Explorer agent → Browser controls: uses controls
- Explorer agent → URL scope guard: checks navigation (evidence: `src/ai_testing_agent/exploration/explorer.py`)
- LangGraph workflow → Test designer: invokes generation
- Test designer → LLM client: requests drafts (evidence: `src/ai_testing_agent/test_generation/service.py`)
- LLM client → LLM provider: structured requests
- Test designer → Scenario validator: validates drafts (evidence: `src/ai_testing_agent/test_generation/service.py`)
- Human tester → Scenario approval: reviews scenarios
- Scenario approval → Test executor: approved scenarios
- LangGraph workflow → Test executor: invokes execution
- Test executor → Pytest runtime: runs bundle
- Pytest runtime → Browser controls: dispatches actions
- Pytest runtime → Authorized website: tests pages
- LangGraph workflow → Failure analysis: invokes analysis
- Failure analysis → LLM client: optional hypothesis
- Failure analysis → Persistence repositories: reads execution rows (evidence: `src/ai_testing_agent/analysis/service.py`)
- LangGraph workflow → Report generator: generates reports
- Report generator → Persistence repositories: reads persisted rows (evidence: `src/ai_testing_agent/reporting/reporter.py`)
- FastAPI → QA coverage: serves QA views
- QA coverage → Persistence repositories: reads stored evidence (evidence: `src/ai_testing_agent/qa/service.py`)
- Session service → Persistence repositories: persists sessions (evidence: `src/ai_testing_agent/sessions/service.py`)
- Persistence repositories → SQLite database: queries and writes
- Job runner → Persistence repositories: persists jobs (evidence: `src/ai_testing_agent/jobs/runner.py`)
