# piwitests/platform architecture

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

- Interactive diagram: https://gitdiagram.com/piwitests/platform
- Repository: https://github.com/piwitests/platform

## Overview

Piwi is a self-hosted Playwright results platform: a reporter streams or submits run data, which the application retains and presents as history, failure investigations, and test-health insights. Engineers browse run evidence, compare trends, triage failure clusters, and optionally use AI diagnosis or locator-healing features. The README also documents desktop/local workflows, notifications, integrations, analytics, REST and MCP access. The tree and excerpts expose only selected implementation details, so links to larger unsampled subsystems reflect documented capabilities rather than inspected call paths.

Main entry points: [`apps/application/server`](https://github.com/piwitests/platform/tree/main/apps/application/server) (Piwi server), [`apps/application/app/composables/useStreamingDiagnosis.ts`](https://github.com/piwitests/platform/blob/main/apps/application/app/composables/useStreamingDiagnosis.ts) (AI diagnosis), [`packages/reporter/src/internal/streaming/stream-manager.ts`](https://github.com/piwitests/platform/blob/main/packages/reporter/src/internal/streaming/stream-manager.ts) (Reporter stream), [`apps/application/app/pages/projects/[id]/index.vue`](https://github.com/piwitests/platform/blob/main/apps/application/app/pages/projects/%5Bid%5D/index.vue) (Run history and detail)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Run capture"]
  node_reporter["Reporter stream<br/>[stream-manager.ts]"]
end

subgraph group_retention["Run retention"]
  node_server["Piwi server"]
  node_runstore[("Run database")]
  node_evidencestore[("Evidence storage")]
  node_runui["Run history and detail<br/>[index.vue]"]
end

subgraph group_investigation["Failure investigation"]
  node_caseui["Test evidence detail<br/>[&#91;id&#93;.vue]"]
  node_clusters["Failure clusters<br/>[&#91;id&#93;.vue]"]
  node_diagnosis["AI diagnosis"]
  node_locatorhealing["Locator healing"]
  node_locatorengine["Locator matching engine<br/>[locator-engine.ts]"]
end

subgraph group_insights["Analytics and insights"]
  node_analytics["Cross-project analytics<br/>[index.vue]"]
  node_dashboards["Custom dashboards<br/>[useDashboards.ts]"]
  node_reports["Scheduled reports<br/>[index.vue]"]
  node_notifications["Notifications"]
end

subgraph group_access["Access and integrations"]
  node_desktop["Desktop workflows"]
  node_integrations["Issue tracker integrations"]
  node_rest["REST and OpenAPI"]
  node_mcp["MCP server<br/>[mcp.vue]"]
end

node_playwright(("Playwright tests"))
node_scm(("Git changes"))
node_engineer(("Engineer"))
node_llm(("Configured LLM"))

node_playwright -->|"reports results"| node_reporter
node_reporter -->|"streams run events"| node_server
node_server -->|"stores run data"| node_runstore
node_server -->|"stores evidence"| node_evidencestore
node_engineer -->|"browses runs"| node_runui
node_runui -->|"requests run data"| node_server
node_engineer -->|"investigates tests"| node_caseui
node_caseui -->|"requests evidence"| node_server
node_engineer -->|"triages failures"| node_clusters
node_clusters -->|"requests cluster data"| node_server
node_diagnosis -->|"loads diagnosis context"| node_server
node_diagnosis -.->|"uses git diff"| node_scm
node_diagnosis -.->|"requests explanation"| node_llm
node_engineer -->|"reviews replacements"| node_locatorhealing
node_locatorhealing -->|"loads locator evidence"| node_server
node_locatorengine -->|"matches locator chains"| node_playwright
node_engineer -->|"reviews trends"| node_analytics
node_analytics -->|"loads analytics"| node_server
node_engineer -->|"configures dashboards"| node_dashboards
node_dashboards -->|"loads dashboard data"| node_server
node_engineer -->|"manages reports"| node_reports
node_reports -->|"requests report data"| node_server
node_server -->|"dispatches notifications"| node_notifications
node_engineer -->|"runs locally"| node_desktop
node_desktop -->|"imports or submits runs"| node_server
node_engineer -->|"configures issue tracking"| node_integrations
node_integrations -->|"requests integration actions"| node_server
node_engineer -->|"calls API"| node_rest
node_rest -->|"serves API requests"| node_server
node_engineer -->|"asks test health"| node_mcp
node_mcp -->|"queries platform"| node_server

click node_reporter "https://github.com/piwitests/platform/blob/main/packages/reporter/src/internal/streaming/stream-manager.ts"
click node_server "https://github.com/piwitests/platform/tree/main/apps/application/server"
click node_evidencestore "https://github.com/piwitests/platform/tree/main/apps/application/server/storage"
click node_runui "https://github.com/piwitests/platform/blob/main/apps/application/app/pages/projects/%5Bid%5D/index.vue"
click node_caseui "https://github.com/piwitests/platform/blob/main/apps/application/app/pages/test-cases/%5Bid%5D.vue"
click node_clusters "https://github.com/piwitests/platform/blob/main/apps/application/app/pages/failure-clusters/%5Bid%5D.vue"
click node_diagnosis "https://github.com/piwitests/platform/blob/main/apps/application/app/composables/useStreamingDiagnosis.ts"
click node_locatorhealing "https://github.com/piwitests/platform/blob/main/apps/application/app/components/shared/LocatorHealingPanel.vue"
click node_locatorengine "https://github.com/piwitests/platform/blob/main/apps/extension/src/content/locator-engine.ts"
click node_analytics "https://github.com/piwitests/platform/blob/main/apps/application/app/pages/analytics/index.vue"
click node_dashboards "https://github.com/piwitests/platform/blob/main/apps/application/app/composables/useDashboards.ts"
click node_reports "https://github.com/piwitests/platform/blob/main/apps/application/app/pages/reports/index.vue"
click node_notifications "https://github.com/piwitests/platform/blob/main/apps/application/app/composables/useNotificationStream.ts"
click node_desktop "https://github.com/piwitests/platform/tree/main/apps/application/app/components/desktop"
click node_integrations "https://github.com/piwitests/platform/tree/main/apps/application/app/components/integrations"
click node_rest "https://github.com/piwitests/platform/tree/main/apps/application/server/api"
click node_mcp "https://github.com/piwitests/platform/blob/main/apps/application/app/pages/mcp.vue"

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_reporter toneBlue
class node_server,node_runstore,node_evidencestore,node_runui toneAmber
class node_caseui,node_clusters,node_diagnosis,node_locatorhealing,node_locatorengine toneMint
class node_analytics,node_dashboards,node_reports,node_notifications toneRose
class node_desktop,node_integrations,node_rest,node_mcp,node_playwright,node_scm,node_engineer,node_llm toneIndigo
```

## Components

### Run capture

- [Reporter stream](https://github.com/piwitests/platform/blob/main/packages/reporter/src/internal/streaming/stream-manager.ts): `packages/reporter/src/internal/streaming/stream-manager.ts`

### Run retention

- [Piwi server](https://github.com/piwitests/platform/tree/main/apps/application/server): `apps/application/server`
- **Run database**
- [Evidence storage](https://github.com/piwitests/platform/tree/main/apps/application/server/storage): `apps/application/server/storage`
- [Run history and detail](https://github.com/piwitests/platform/blob/main/apps/application/app/pages/projects/%5Bid%5D/index.vue): `apps/application/app/pages/projects/[id]/index.vue`

### Failure investigation

- [Test evidence detail](https://github.com/piwitests/platform/blob/main/apps/application/app/pages/test-cases/%5Bid%5D.vue): `apps/application/app/pages/test-cases/[id].vue`
- [Failure clusters](https://github.com/piwitests/platform/blob/main/apps/application/app/pages/failure-clusters/%5Bid%5D.vue): `apps/application/app/pages/failure-clusters/[id].vue`
- [AI diagnosis](https://github.com/piwitests/platform/blob/main/apps/application/app/composables/useStreamingDiagnosis.ts): `apps/application/app/composables/useStreamingDiagnosis.ts`
- [Locator healing](https://github.com/piwitests/platform/blob/main/apps/application/app/components/shared/LocatorHealingPanel.vue): `apps/application/app/components/shared/LocatorHealingPanel.vue`
- [Locator matching engine](https://github.com/piwitests/platform/blob/main/apps/extension/src/content/locator-engine.ts): `apps/extension/src/content/locator-engine.ts`

### Analytics and insights

- [Cross-project analytics](https://github.com/piwitests/platform/blob/main/apps/application/app/pages/analytics/index.vue): `apps/application/app/pages/analytics/index.vue`
- [Custom dashboards](https://github.com/piwitests/platform/blob/main/apps/application/app/composables/useDashboards.ts): `apps/application/app/composables/useDashboards.ts`
- [Scheduled reports](https://github.com/piwitests/platform/blob/main/apps/application/app/pages/reports/index.vue): `apps/application/app/pages/reports/index.vue`
- [Notifications](https://github.com/piwitests/platform/blob/main/apps/application/app/composables/useNotificationStream.ts): `apps/application/app/composables/useNotificationStream.ts`

### Access and integrations

- [Desktop workflows](https://github.com/piwitests/platform/tree/main/apps/application/app/components/desktop): `apps/application/app/components/desktop`
- [Issue tracker integrations](https://github.com/piwitests/platform/tree/main/apps/application/app/components/integrations): `apps/application/app/components/integrations`
- [REST and OpenAPI](https://github.com/piwitests/platform/tree/main/apps/application/server/api): `apps/application/server/api`
- [MCP server](https://github.com/piwitests/platform/blob/main/apps/application/app/pages/mcp.vue): `apps/application/app/pages/mcp.vue`

### Other components

- **Playwright tests**
- **Git changes**
- **Engineer**
- **Configured LLM**

## Connections

- Playwright tests → Reporter stream: reports results
- Reporter stream → Piwi server: streams run events
- Piwi server → Run database: stores run data
- Piwi server → Evidence storage: stores evidence
- Engineer → Run history and detail: browses runs
- Run history and detail → Piwi server: requests run data
- Engineer → Test evidence detail: investigates tests
- Test evidence detail → Piwi server: requests evidence
- Engineer → Failure clusters: triages failures
- Failure clusters → Piwi server: requests cluster data
- AI diagnosis → Piwi server: loads diagnosis context
- AI diagnosis → Git changes: uses git diff
- AI diagnosis → Configured LLM: requests explanation
- Engineer → Locator healing: reviews replacements
- Locator healing → Piwi server: loads locator evidence
- Locator matching engine → Playwright tests: matches locator chains
- Engineer → Cross-project analytics: reviews trends
- Cross-project analytics → Piwi server: loads analytics
- Engineer → Custom dashboards: configures dashboards
- Custom dashboards → Piwi server: loads dashboard data
- Engineer → Scheduled reports: manages reports
- Scheduled reports → Piwi server: requests report data
- Piwi server → Notifications: dispatches notifications
- Engineer → Desktop workflows: runs locally
- Desktop workflows → Piwi server: imports or submits runs
- Engineer → Issue tracker integrations: configures issue tracking
- Issue tracker integrations → Piwi server: requests integration actions
- Engineer → REST and OpenAPI: calls API
- REST and OpenAPI → Piwi server: serves API requests
- Engineer → MCP server: asks test health
- MCP server → Piwi server: queries platform