spalanivelu1989/test-suite

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.