# spalanivelu1989/test-suite architecture

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

- Interactive diagram: https://gitdiagram.com/spalanivelu1989/test-suite
- Repository: https://github.com/spalanivelu1989/test-suite

## Overview

1. **Product shape**
   - This repo is a Next.js-based control plane for an autonomous UI testing system. The user-facing app lives under `app/`, while the core orchestration, knowledge, reporting, and storage logic lives under `src/`.

2. **Primary user flows**
   - The main flow starts in the run UI (`app/page.tsx`, `app/RunForm.tsx`) and drives a test-run lifecycle through `/api/runs`.
   - Users can inspect run state, cancel a run, stream progress, and open generated reports via dedicated routes under `app/api/runs/[id]/...` and views under `app/runs/[id]/`.

3. **Run orchestration boundary**
   - `src/orchestrator/` is the execution brain. It coordinates staged test execution, wires knowledge into the prompt/context, and manages the overall run lifecycle through `runService.ts`, `stages.ts`, and `orchestrate.ts`.
   - This is where the app turns a test request into a structured sequence of crawl/plan/generate/run/heal actions.

4. **Agent execution layer**
   - `src/agents/` contains the low-level runtime guards and workspace/crawl controls that keep browser-driving behavior safe and consistent.
   - The repo also includes `.claude/agents/` and `.claude/skills/playwright-cli/`, which define the AI subagents and the Playwright CLI skill contract they must follow. This is a key architectural boundary: the orchestrator delegates browser work to Claude agents, but those agents are constrained by the Playwright CLI skill set.

5. **Browser and test automation**
   - Playwright is the execution backend for browser interactions and generated tests. The README explicitly requires `npx playwright-cli install --skills`, which indicates the system depends on token-efficient Playwright CLI commands rather than ad hoc browser scripting.
   - The system is built to generate, run, and evolve Playwright test suites rather than just record one-off sessions.

6. **Run persistence and live feedback**
   - Run state and execution artifacts are stored separately from the knowledge base. `src/runStore/` and `src/runManager/` handle persistence and lifecycle management for test runs.
   - The UI consumes run updates through the streaming endpoint (`app/api/runs/[id]/stream/route.ts`) and renders progress/reporting components such as tables, details panes, charts, and trends.

7. **Results and reporting**
   - After execution, results are parsed and validated in `src/results/` and `src/validator/`.
   - `src/reporter/` turns raw run output into human-readable narratives and rendered reports, which are surfaced in the run detail pages and report endpoints.

8. **Knowledge platform subsystem**
   - The `src/knowledge/` tree is a separate but central subsystem for extracting, storing, retrieving, and distilling reusable testing knowledge.
   - It includes ingestion, embeddings, retrieval, healing precedence, global patterns, app profiles, and business-context modeling. This is the system that lets the tool learn from prior runs and reuse patterns across apps.

9. **Knowledge APIs and exploration UI**
   - Knowledge is exposed through API routes under `app/api/knowledge/...`, including apps, patterns, specs, and query translation/execution.
   - The UI has dedicated exploration surfaces such as `app/explore/` and `app/sql-query/`, which suggests the team can inspect, query, and calibrate the knowledge store directly.

10. **Storage and schema**
   - The knowledge store uses Postgres with `pgvector`, confirmed by the migrations in `src/knowledge/store/migrations/` and the architecture docs.
   - This is not just a document store: it holds structured metadata, embeddings, pattern embeddings, title embeddings, and healing playbooks, enabling hybrid semantic and additive matching.

11. **Domain corpus**
   - `business-context/` contains the domain knowledge the system learns from: apps, workflows, screens, and SAP Fiori conventions/patterns.
   - `specs/` and `docs/` capture architecture, design decisions, implementation notes, and phase plans. These files are part of the knowledge supply chain used for distillation and reuse.

12. **Operational tooling**
   - `bin/` contains maintenance and backfill jobs for knowledge distillation, embedding generation, provenance/heal backfills, CI runs, and smoke tests.
   - `src/observability/langfuse.ts` shows optional telemetry/LLM observability integration, which matters because this system is an agent pipeline with long-running, multi-step executions.

13. **Repo-level architecture summary**
   - The architecture is best drawn as four major zones: the Next.js UI/API layer, the orchestration/agent execution layer, the knowledge store/retrieval layer, and the reporting/persistence layer.
   - Data flows from UI → run APIs → orchestrator → Claude/Playwright execution → results/reporting → run store, with a parallel loop from execution artifacts into the knowledge ingestion/distillation pipeline so future runs can reuse and heal from prior experience.

Main entry points: [`src/orchestrator/orchestrate.ts`](https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/orchestrate.ts) (Orchestrate), [`app/api/runs`](https://github.com/spalanivelu1989/test-suite/tree/main/app/api/runs) (Run APIs), [`src/knowledge/store`](https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/store) (KB Store), [`src/orchestrator/runService.ts`](https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/runService.ts) (Run Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Next.js UI"]
  node_app_home["Run UI<br/>nextjs page<br/>[page.tsx]"]
  node_app_runform["Run Form<br/>ui component<br/>[RunForm.tsx]"]
  node_app_run_api["Run APIs<br/>route handlers"]
  node_app_run_views["Run Views<br/>run pages"]
  node_app_knowledge_api["Knowledge APIs<br/>route handlers"]
  node_app_explore["Explore UI<br/>knowledge ui"]
  node_app_sqlquery["SQL Query<br/>query ui"]
end

subgraph group_orchestration["Execution Core"]
  node_orch_service["Run Service<br/>orchestrator service<br/>[runService.ts]"]
  node_orch_stages["Stages<br/>execution plan<br/>[stages.ts]"]
  node_orch_orchestrate["Orchestrate<br/>workflow engine<br/>[orchestrate.ts]"]
  node_agents["Agent Guards<br/>runtime guards"]
  node_results["Results<br/>result parser<br/>[parse.ts]"]
  node_validator["Validator<br/>validation<br/>[validate.ts]"]
  node_reporter["Reporter<br/>reporting<br/>[report.ts]"]
  node_run_store["Run Store<br/>persistence<br/>[store.ts]"]
  node_run_manager["Run Manager<br/>lifecycle<br/>[manager.ts]"]
end

subgraph group_knowledge["Knowledge Platform"]
  node_knowledge_assemble["Context Pack<br/>knowledge assembly<br/>[contextPack.ts]"]
  node_knowledge_retrieve["Retrieval"]
  node_knowledge_ingest["Ingest"]
  node_knowledge_distill["Distill"]
  node_knowledge_heal["Healing"]
  node_knowledge_store[("KB Store<br/>postgres pgvector")]
end

subgraph group_automation["CLI Agents"]
  node_claude_skill["Playwright Skill<br/>claude skill<br/>[SKILL.md]"]
  node_claude_agents["Claude Agents<br/>subagent defs<br/>[agents]"]
end

subgraph group_ops["Operations"]
end

node_app_home -->|"starts"| node_app_runform
node_app_runform -->|"creates runs"| node_app_run_api
node_app_run_api -->|"launches"| node_orch_service
node_orch_service -->|"executes"| node_orch_orchestrate
node_orch_orchestrate -->|"plans"| node_orch_stages
node_orch_orchestrate -->|"delegates"| node_agents
node_agents -->|"constrains"| node_claude_skill
node_agents -->|"uses"| node_claude_agents
node_orch_orchestrate -->|"injects context"| node_knowledge_assemble
node_knowledge_assemble -->|"pulls from"| node_knowledge_retrieve
node_knowledge_retrieve -->|"reads"| node_knowledge_store
node_orch_orchestrate -->|"produces"| node_results
node_results -->|"checks"| node_validator
node_validator -->|"feeds"| node_reporter
node_reporter -->|"surfaces"| node_app_run_views
node_orch_service -->|"manages"| node_run_manager
node_run_manager -->|"persists"| node_run_store
node_app_run_api -->|"streams state"| node_run_store
node_app_run_views -->|"polls/streams"| node_app_run_api
node_app_knowledge_api -->|"queries"| node_knowledge_store
node_app_explore -->|"explores"| node_app_knowledge_api
node_app_sqlquery -->|"inspects"| node_knowledge_store
node_app_run_api -.->|"triggers ingest"| node_knowledge_ingest
node_knowledge_ingest -->|"distills"| node_knowledge_distill
node_knowledge_distill -->|"writes"| node_knowledge_store
node_results -.->|"captures failures"| node_knowledge_heal
node_knowledge_heal -->|"stores playbooks"| node_knowledge_store

click node_app_home "https://github.com/spalanivelu1989/test-suite/blob/main/app/page.tsx"
click node_app_runform "https://github.com/spalanivelu1989/test-suite/blob/main/app/RunForm.tsx"
click node_app_run_api "https://github.com/spalanivelu1989/test-suite/tree/main/app/api/runs"
click node_app_run_views "https://github.com/spalanivelu1989/test-suite/tree/main/app/runs/[id]"
click node_app_knowledge_api "https://github.com/spalanivelu1989/test-suite/tree/main/app/api/knowledge"
click node_app_explore "https://github.com/spalanivelu1989/test-suite/tree/main/app/explore"
click node_app_sqlquery "https://github.com/spalanivelu1989/test-suite/tree/main/app/sql-query"
click node_orch_service "https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/runService.ts"
click node_orch_stages "https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/stages.ts"
click node_orch_orchestrate "https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/orchestrate.ts"
click node_agents "https://github.com/spalanivelu1989/test-suite/tree/main/src/agents"
click node_claude_skill "https://github.com/spalanivelu1989/test-suite/blob/main/.claude/skills/playwright-cli/SKILL.md"
click node_claude_agents "https://github.com/spalanivelu1989/test-suite/blob/main/.claude/agents"
click node_results "https://github.com/spalanivelu1989/test-suite/blob/main/src/results/parse.ts"
click node_validator "https://github.com/spalanivelu1989/test-suite/blob/main/src/validator/validate.ts"
click node_reporter "https://github.com/spalanivelu1989/test-suite/blob/main/src/reporter/report.ts"
click node_run_store "https://github.com/spalanivelu1989/test-suite/blob/main/src/runStore/store.ts"
click node_run_manager "https://github.com/spalanivelu1989/test-suite/blob/main/src/runManager/manager.ts"
click node_knowledge_assemble "https://github.com/spalanivelu1989/test-suite/blob/main/src/knowledge/assemble/contextPack.ts"
click node_knowledge_retrieve "https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/retrieve"
click node_knowledge_ingest "https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/ingest"
click node_knowledge_distill "https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/distill"
click node_knowledge_heal "https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/heal"
click node_knowledge_store "https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/store"

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_app_home,node_app_runform,node_app_run_api,node_app_run_views,node_app_knowledge_api,node_app_explore,node_app_sqlquery toneBlue
class node_orch_service,node_orch_stages,node_orch_orchestrate,node_agents,node_results,node_validator,node_reporter,node_run_store,node_run_manager toneAmber
class node_knowledge_assemble,node_knowledge_retrieve,node_knowledge_ingest,node_knowledge_distill,node_knowledge_heal,node_knowledge_store toneMint
class node_claude_skill,node_claude_agents toneRose
```

## Components

### Next.js UI

User-facing app pages, API routes, and run/knowledge exploration screens.

- [Run UI](https://github.com/spalanivelu1989/test-suite/blob/main/app/page.tsx): nextjs page · Entry page for launching and inspecting test runs. · `app/page.tsx`
- [Run Form](https://github.com/spalanivelu1989/test-suite/blob/main/app/RunForm.tsx): ui component · Collects run inputs and starts the main lifecycle. · `app/RunForm.tsx`
- [Run APIs](https://github.com/spalanivelu1989/test-suite/tree/main/app/api/runs): route handlers · Creates runs, streams progress, cancels, and exposes reports/state. · `app/api/runs`
- [Run Views](https://github.com/spalanivelu1989/test-suite/tree/main/app/runs/[id]): run pages · Run detail and report-facing screens. · `app/runs/[id]`
- [Knowledge APIs](https://github.com/spalanivelu1989/test-suite/tree/main/app/api/knowledge): route handlers · App, pattern, spec, and query endpoints for the knowledge store. · `app/api/knowledge`
- [Explore UI](https://github.com/spalanivelu1989/test-suite/tree/main/app/explore): knowledge ui · Pattern explorer and SQL query surfaces for inspecting knowledge. · `app/explore`
- [SQL Query](https://github.com/spalanivelu1989/test-suite/tree/main/app/sql-query): query ui · Direct SQL exploration and calibration interface. · `app/sql-query`

### Execution Core

Run orchestration, agent controls, results processing, validation, and reporting.

- [Run Service](https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/runService.ts): orchestrator service · Coordinates run lifecycle state and orchestration entrypoints. · `src/orchestrator/runService.ts`
- [Stages](https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/stages.ts): execution plan · Defines the staged crawl/plan/generate/run/heal flow. · `src/orchestrator/stages.ts`
- [Orchestrate](https://github.com/spalanivelu1989/test-suite/blob/main/src/orchestrator/orchestrate.ts): workflow engine · Main orchestration logic that turns requests into structured execution. · `src/orchestrator/orchestrate.ts`
- [Agent Guards](https://github.com/spalanivelu1989/test-suite/tree/main/src/agents): runtime guards · Safety and workspace controls for browser-driving agent execution. · `src/agents`
- [Results](https://github.com/spalanivelu1989/test-suite/blob/main/src/results/parse.ts): result parser · Parses raw execution output into structured run results. · `src/results/parse.ts`
- [Validator](https://github.com/spalanivelu1989/test-suite/blob/main/src/validator/validate.ts): validation · Checks run output and generated artifacts for correctness. · `src/validator/validate.ts`
- [Reporter](https://github.com/spalanivelu1989/test-suite/blob/main/src/reporter/report.ts): reporting · Builds narratives, rendered reports, and success metrics. · `src/reporter/report.ts`
- [Run Store](https://github.com/spalanivelu1989/test-suite/blob/main/src/runStore/store.ts): persistence · Stores run state and artifacts for live and post-run access. · `src/runStore/store.ts`
- [Run Manager](https://github.com/spalanivelu1989/test-suite/blob/main/src/runManager/manager.ts): lifecycle · Manages run persistence and lifecycle coordination. · `src/runManager/manager.ts`

### Knowledge Platform

Business context, retrieval, ingestion, healing, embeddings, and persistent store.

- [Context Pack](https://github.com/spalanivelu1989/test-suite/blob/main/src/knowledge/assemble/contextPack.ts): knowledge assembly · Packages reusable knowledge into prompt/context bundles. · `src/knowledge/assemble/contextPack.ts`
- [Retrieval](https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/retrieve): knowledge retrieval · Fetches app profiles, global patterns, and healing precedents. · `src/knowledge/retrieve`
- [Ingest](https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/ingest): knowledge ingestion · Extracts run artifacts and feeds them into the knowledge pipeline. · `src/knowledge/ingest`
- [Distill](https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/distill): knowledge distillation · Clusters, summarizes, and promotes reusable learnings. · `src/knowledge/distill`
- [Healing](https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/heal): knowledge healing · Captures failures and builds healing precedents and provenance. · `src/knowledge/heal`
- [KB Store](https://github.com/spalanivelu1989/test-suite/tree/main/src/knowledge/store): postgres pgvector · Persistent knowledge database with embeddings and playbooks. · `src/knowledge/store`

### CLI Agents

Claude agent definitions and the Playwright CLI skill contract.

- [Playwright Skill](https://github.com/spalanivelu1989/test-suite/blob/main/.claude/skills/playwright-cli/SKILL.md): claude skill · Contract for token-efficient Playwright CLI usage. · `.claude/skills/playwright-cli/SKILL.md`
- [Claude Agents](https://github.com/spalanivelu1989/test-suite/blob/main/.claude/agents): subagent defs · Designer, discoverer, and evolver roles used by orchestration. · `.claude/agents`

## Connections

- Run UI → Run Form: starts · The landing page drives users into the run creation form.
- Run Form → Run APIs: creates runs · Form submissions call the run API lifecycle endpoint.
- Run APIs → Run Service: launches · Run routes delegate lifecycle control to the orchestrator service.
- Run Service → Orchestrate: executes · The service enters the main orchestration workflow.
- Orchestrate → Stages: plans · Orchestration is driven by staged execution steps.
- Orchestrate → Agent Guards: delegates · Browser work is handed to guarded agent/runtime controls.
- Agent Guards → Playwright Skill: constrains · Agent behavior follows the Playwright CLI skill contract.
- Agent Guards → Claude Agents: uses · Guarded execution is performed by Claude subagents.
- Orchestrate → Context Pack: injects context · Knowledge is packed into prompts and execution context.
- Context Pack → Retrieval: pulls from · Context packs are built from retrieved knowledge.
- Retrieval → KB Store: reads · Retrieval queries the persistent knowledge database.
- Orchestrate → Results: produces · Execution output is parsed into structured results.
- Results → Validator: checks · Parsed results are validated before reporting.
- Validator → Reporter: feeds · Validation outcomes shape the generated report.
- Reporter → Run Views: surfaces · Reports and narratives are shown in run detail pages.
- Run Service → Run Manager: manages · Lifecycle coordination is backed by the run manager.
- Run Manager → Run Store: persists · Run state and artifacts are stored for live updates.
- Run APIs → Run Store: streams state · API routes read and expose stored run updates.
- Run Views → Run APIs: polls/streams · Run views consume run state, cancellations, and reports.
- Knowledge APIs → KB Store: queries · Knowledge APIs expose database-backed content and search.
- Explore UI → Knowledge APIs: explores · The exploration UI calls knowledge endpoints.
- SQL Query → KB Store: inspects · SQL query UI is for direct store inspection and calibration.
- Run APIs → Ingest: triggers ingest · Completed or updated runs can be fed into ingestion.
- Ingest → Distill: distills · Ingested artifacts are summarized into reusable knowledge.
- Distill → KB Store: writes · Distilled patterns and embeddings are persisted.
- Results → Healing: captures failures · Failures and fixes feed the healing memory pipeline.
- Healing → KB Store: stores playbooks · Healing provenance and playbooks are written to the store.