Overview

AppraiseJS is a local-first Next.js platform that combines visual test authoring, orchestration, execution, and reporting in one runtime.

Architecture map

UI layer (src/app, src/components): authoring screens, the Settings sync dashboard, run dashboards, and report views.
Server layer (src/actions, src/app/api): input validation, persistence, sync and run orchestration, streaming APIs.
Core orchestration (src/lib, scripts): feature generation, sync logic, execution coordination, report parsing, and maintenance scripts.
Data layer (prisma + SQLite): authoritative model for authored entities, runs, reports, and metrics.
Runner layer (src/tests): Cucumber + Playwright execution, hooks, trace capture, step libraries.

The following diagram illustrates the architecture flow.

#direction: right
#stroke: #64748b
#fill: #f8fafc
[UI Pages] -> [Server Actions / API Routes]
[Server Actions / API Routes] -> [Core Libs + Scripts]
[Core Libs + Scripts] -> [Prisma + SQLite]
[Core Libs + Scripts] -> [Cucumber + Playwright]
[Cucumber + Playwright] -> [Cucumber JSON + Traces]
[Cucumber JSON + Traces] -> [Core Libs + Scripts]
[Server Actions / API Routes] -> [UI Pages]

How to read this section

Execution Lifecycle: request-to-result runtime flow.
Synchronization Pipeline: DB <-> filesystem parity and artifact generation.
Data and Reporting Model: run/report entities and matching logic.
Runtime Services and APIs: process manager, SSE logs, traces, and downloads.

Key implementation anchors

Test run execution: src/lib/test-run/test-run-executor.ts
Process lifecycle and events: src/lib/test-run/process-manager.ts
Report parsing and enum mapping: src/lib/test-run/report-parser.ts
Bidirectional sync: src/lib/bidirectional-sync.ts
Feature generation: src/lib/feature-file-generator.ts
Run orchestration action: src/actions/test-run/test-run-actions.ts