# System Architecture β AI API Testing Assistant
---
## 1. High-Level System Overview
```mermaid
graph TB
subgraph CLIENT["π₯οΈ Client Layer"]
UI["React + Vite SPA
(frontend-react)"]
end
subgraph BACKEND["βοΈ Backend Layer (FastAPI)"]
MW["Middleware Stack
(CORS Β· JWT Auth Β· Rate Limiter Β· Logger)"]
API["REST API Router
/api/v1"]
SVC["Service Layer"]
INT["Integrations"]
end
subgraph DATA["ποΈ Data Layer"]
PG[("PostgreSQL
(via SQLAlchemy)")]
FS["File Storage
(Uploads Dir / Supabase)"]
ALB["Alembic
Migrations"]
end
subgraph LLM["π€ LLM Providers"]
MISTRAL["Mistral AI"]
OPENAI["OpenAI"]
ANTHROPIC["Anthropic Claude"]
GEMINI["Google Gemini"]
GROQ["Groq"]
end
subgraph EXT["π External APIs Under Test"]
TARGET["Target REST APIs
(user-specified base URL)"]
end
UI -->|"HTTPS / REST (JWT)"| MW
MW --> API
API --> SVC
SVC --> INT
SVC --> PG
SVC --> FS
INT -->|"LangChain"| MISTRAL
INT -->|"LangChain"| OPENAI
INT -->|"LangChain"| ANTHROPIC
INT -->|"LangChain"| GEMINI
INT -->|"LangChain"| GROQ
SVC -->|"HTTP Requests"| TARGET
ALB -.->|"schema migrations"| PG
```
---
## 2. Frontend Architecture (React SPA)
```mermaid
graph TD
subgraph ENTRY["Entry Point"]
MAIN["main.jsx"]
APP["App.jsx
(routing + layout)"]
end
subgraph PAGES["Pages"]
SPECS["SpecsPage
Upload & manage API specs"]
EXEC["Execution
(workflow/WorkflowPage)"]
HIST["HistoryPage
Test run history"]
CHAT["ChatAssistant
AI assistant chat"]
MEDIA["MediaHubPage
Assets & media"]
COLL["CollectionsPage
Asset collections"]
USAGE["UsagePage
LLM token usage"]
SETTINGS["SettingsPage
LLM provider config"]
PROFILE["ProfilePage
User profile"]
LOGIN["LoginPage
JWT auth"]
end
subgraph SHARED["Shared Components"]
CTX["AppContext.jsx
(React Context β global state)"]
TOAST["Toast.jsx"]
ERR["ErrorBoundary.jsx"]
end
subgraph SVCL["API Service Layer"]
AXIO["services/
Axios calls to /api/v1"]
end
MAIN --> APP
APP --> CTX
APP --> PAGES
PAGES --> SVCL
SVCL -->|"REST + JWT Bearer"| BACKEND
PAGES --> SHARED
```
---
## 3. Backend API Routes
```mermaid
graph LR
subgraph ROUTER["FastAPI Router (/api/v1)"]
AUTH["/auth
π Public
Login Β· Register"]
SPEC["/specs
π Protected
Upload Postman / Swagger"]
SESS["/sessions
π Protected
CRUD test sessions"]
EXEC["/execution
π Protected
Plan Β· Run Β· Analyze steps"]
HIST["/history
π Protected
Execution history"]
CHAT["/chat
π Protected
AI assistant messages"]
ASSET["/assets
π Protected
File uploads (media/docs)"]
USE["/usage
π Protected
LLM token usage stats"]
SET["/settings
π Protected
LLM provider & model config"]
end
AUTH -->|"issues JWT"| CLIENT
SPEC --> postman_parser & swagger_parser
EXEC --> llm_planner & api_executor & response_analyzer
CHAT --> chat_assistant
ASSET --> asset_service
USE --> usage_service
SET --> llm_factory["LLM Factory
(provider registry)"]
```
---
## 4. Service Layer Internals
```mermaid
graph TD
subgraph SERVICES["backend/services/"]
PP["postman_parser.py
Parse Postman collections"]
SP["swagger_parser.py
Parse OpenAPI / Swagger specs"]
LP["llm_planner.py
Generate AI execution plans"]
AE["api_executor.py
Execute HTTP steps"]
RA["response_analyzer.py
Analyze API responses with LLM"]
CA["chat_assistant.py
AI chat with context"]
AS["asset_service.py
Manage file assets"]
CM["context_manager.py
Track session variables"]
ST["storage.py
File I/O & Supabase storage"]
US["usage_service.py
Track LLM token consumption"]
end
PP -->|parsed endpoints| LP
SP -->|parsed endpoints| LP
LP -->|execution plan JSON| AE
AE -->|request + response| RA
RA -->|analysis JSON| DB[(PostgreSQL)]
CA -->|chat history| DB
CM -->|context vars| AE
AS --> ST
US --> DB
LP --> LLM_INT["LLM Integration Layer"]
RA --> LLM_INT
CA --> LLM_INT
```
---
## 5. LLM Integration Layer
```mermaid
graph TD
subgraph INTEGRATIONS["backend/integrations/llm/"]
FAC["factory.py
LLMClientFactory"]
REG["registry.py
Provider Registry"]
RES["resolver.py
TaskβProvider resolver"]
BASE["base.py
BaseLLMClient (ABC)"]
PROV["providers.py
Concrete Clients"]
end
subgraph PROVIDERS["LLM Provider Clients"]
MC["MistralClient"]
OC["OpenAIClient"]
AC["AnthropicClient"]
GC["GeminiClient"]
GRC["GroqClient"]
end
subgraph TASK_CONFIG["DB: llm_task_config"]
T1["plan_generation β provider + model"]
T2["step_execution β provider + model"]
T3["response_analysis β provider + model"]
T4["chat β provider + model"]
end
FAC --> REG
REG --> RES
RES -->|reads| TASK_CONFIG
FAC --> BASE
BASE --> PROV
PROV --> MC & OC & AC & GC & GRC
MC -->|"LangChain"| MistralAI_API["Mistral AI API"]
OC -->|"LangChain"| OpenAI_API["OpenAI API"]
AC -->|"LangChain"| Anthropic_API["Anthropic API"]
GC -->|"LangChain"| Gemini_API["Google Gemini API"]
GRC -->|"LangChain"| Groq_API["Groq API"]
```
---
## 6. Database Schema (ERD)
```mermaid
erDiagram
spec_documents {
string id PK
string name
text raw_content
json parsed_json
string base_url
json login_credentials
json execution_plan
text scenario
string file_path
datetime uploaded_at
}
sessions {
string id PK
string user_id
string spec_id FK
string spec_name
string base_url
text scenario
json context_variables
datetime created_at
}
execution_history {
int id PK
string session_id
int step
json request_json
json response_json
json analysis_json
json step_definition_json
datetime timestamp
}
collections {
string id PK
string name
text description
string spec_id FK
datetime created_at
}
assets {
string id PK
string name
string file_type
string file_path
int file_size
string category
text description
json tags
json metadata_json
string spec_id FK
datetime uploaded_at
}
asset_collections {
string asset_id FK
string collection_id FK
}
chat_sessions {
string id PK
string user_id
string name
string spec_id FK
string session_id
datetime created_at
datetime updated_at
}
chat_messages {
int id PK
string chat_session_id FK
string role
text content
json action_json
datetime timestamp
}
llm_usage {
int id PK
string session_id
string user_id
string call_type
int prompt_tokens
int completion_tokens
int total_tokens
datetime timestamp
}
llm_providers {
string provider_id PK
json api_key_enc
boolean is_active
}
llm_task_config {
string task_name PK
string provider_id FK
string model_name
float temperature
}
spec_documents ||--o{ sessions : "has"
spec_documents ||--o{ assets : "has"
spec_documents ||--o{ collections : "has"
spec_documents ||--o{ chat_sessions : "linked to"
assets }o--o{ collections : "asset_collections"
chat_sessions ||--o{ chat_messages : "contains"
llm_providers ||--o{ llm_task_config : "configures"
```
---
## 7. Authentication & Security Flow
```mermaid
sequenceDiagram
participant Browser as π₯οΈ Browser (React)
participant API as βοΈ FastAPI
participant JWT as π JWT Middleware
participant DB as ποΈ PostgreSQL
participant Enc as π Fernet Encryption
Browser->>API: POST /api/v1/auth/login
API->>DB: validate credentials
DB-->>API: user record
API-->>Browser: JWT token (HS256)
Browser->>API: GET /api/v1/specs (Bearer token)
API->>JWT: extract_user_state middleware
JWT->>JWT: decode JWT (HS256 + JWT_SECRET)
JWT-->>API: request.state.user = user_id
API->>API: verify_token dependency
API->>DB: fetch protected data
DB-->>API: result
API-->>Browser: JSON response
Note over API,Enc: LLM API keys stored
encrypted with Fernet
(ENCRYPTION_KEY from .env)
API->>Enc: decrypt api_key_enc on use
Enc-->>API: plaintext API key
```
---
## 8. API Test Execution Flow
```mermaid
sequenceDiagram
participant User as π€ User
participant FE as π₯οΈ Frontend
participant BE as βοΈ Backend
participant LLM as π€ LLM Provider
participant Target as π Target API
User->>FE: Upload Postman/Swagger spec
FE->>BE: POST /api/v1/specs
BE->>BE: postman_parser / swagger_parser
BE-->>FE: spec_id + parsed endpoints
User->>FE: Set base URL + scenario
FE->>BE: POST /api/v1/sessions
BE-->>FE: session_id
User->>FE: Generate execution plan
FE->>BE: POST /api/v1/execution/plan
BE->>LLM: llm_planner (prompt with endpoints + scenario)
LLM-->>BE: structured execution plan (JSON)
BE-->>FE: plan steps
loop For each step
User->>FE: Run step
FE->>BE: POST /api/v1/execution/step
BE->>BE: context_manager (resolve variables)
BE->>Target: HTTP request (with auth headers)
Target-->>BE: HTTP response
BE->>LLM: response_analyzer (analyze result)
LLM-->>BE: analysis + pass/fail verdict
BE->>DB: save execution_history
BE-->>FE: step result + analysis
end
```
---
## 9. Technology Stack Summary
| Layer | Technology |
|---|---|
| **Frontend** | React 18, Vite, Vanilla CSS |
| **Backend** | FastAPI (Python), Uvicorn |
| **Database** | PostgreSQL (SQLAlchemy ORM, Alembic migrations) |
| **File Storage** | Local filesystem / Supabase Storage |
| **Authentication** | JWT (HS256), Fernet encryption for secrets |
| **LLM Integration** | LangChain (Mistral, OpenAI, Anthropic, Gemini, Groq) |
| **Rate Limiting** | SlowAPI |
| **Deployment** | Procfile (Heroku-style), `runtime.txt` |