Architecture

OCPP DebugKit is a modular monorepo with independent packages. Each package can be used standalone or together.

Package Structure

ocpp-debugkit/
├── packages/
│   ├── core/          # Data model, parser, normalizer, timeline, failure detection
│   ├── scenarios/     # Predefined trace scenarios for testing
│   ├── reporter/      # Report generators (Markdown)
│   ├── cli/           # Command-line interface
│   ├── replay/        # Replay engine (v0.2+)
│   └── react/         # Reusable React components (v0.2+)
├── apps/
│   └── web/           # Single Next.js app (landing, inspector, docs)
└── turbo.json          # Turborepo task pipeline

Dependency Graph

        core          ← everything depends on this
       /  |  \
  scenarios | reporter
       \  |  /
          cli
          |
       apps/web

Build Order

Packages must be built in dependency order: core → scenarios/reporter → cli → app

Data Flow

The analysis pipeline processes traces in three stages:

1. Parse — parseTrace() accepts JSON Object, JSONL, or bare array input, validates with Zod schemas, and produces normalized Event objects.
2. Analyze — buildSessionTimeline() groups events into sessions, then detectFailures() checks for known failure patterns (failed auth, connector fault, station offline).
3. Report — generateMarkdownReport() produces a human-readable Markdown report with session overview, timeline, failures, and suggested steps.

Browser-Local Processing

All trace processing in the web inspector happens client-side. No trace data is uploaded to any server. The CSMS/CLI process traces locally.

Technology Stack

• TypeScript (strict mode)
• Zod for input validation
• Vitest for testing
• Turborepo for build orchestration
• Next.js + Tailwind CSS for the web app
• Commander for the CLI
• Playwright for E2E tests