Skip to content

docs: quickstart + glossary + architecture + trace format + CLI reference + scenarios #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sepehr-safari merged 1 commit into from
Jul 8, 2026
Merged

docs: quickstart + glossary + architecture + trace format + CLI reference + scenarios #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions CURRENT_STATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,14 +144,24 @@ report exported. CLI and web inspector.
- ✅ Sticky header for better UX on long traces
- ✅ Analyze button shows "Analyzing…" and disables during parsing

### Playwright Smoke Tests (in progress — this PR)
### Playwright Smoke Tests (PR #45)

- ✅ `playwright.config.ts` — chromium, auto-start dev server
- ✅ Landing page tests: page loads, hero, CTA links, features, footer
- ✅ Navigation tests: landing → inspector, landing → docs
- ✅ Inspector tests: empty state, sample scenario → timeline, failures, event click → message inspector, export button, invalid input error
- ✅ CI workflow updated: install browsers + run E2E after unit tests

### Docs Content (in progress — this PR)

- ✅ `/docs` index with navigation sidebar
- ✅ `/docs/quickstart` — install, inspect, report, scenario, web inspector, programmatic use
- ✅ `/docs/glossary` — OCPP, CSMS, Charge Point, Connector, Transaction, Call, CallResult, CallError, idTag, Trace, Direction
- ✅ `/docs/architecture` — package structure, dependency graph, data flow, browser-local processing, tech stack
- ✅ `/docs/trace-format` — JSON Object, JSONL, bare array, message structure, timestamps, limits, direction inference
- ✅ `/docs/cli` — install, inspect, report, scenario list, scenario run, options, security
- ✅ `/docs/scenarios` — 5 built-in scenarios, failure detection rules, running scenarios, synthetic data

## What's Next

1. **Issue #20** → complete (PR #33): data model + parser + normalizer
Expand All @@ -164,8 +174,8 @@ report exported. CLI and web inspector.
8. **Issue #27** → complete (PR #43): Landing page (hero, features, architecture, quick start, footer)
9. **Issue #28** → complete (PR #43): Inspector (trace input + timeline + message inspector + failures + report export)
10. **Issue #29** → complete (PR #44): Inspector polish (loading states, responsive, keyboard nav)
11. **Issue #30** (this PR) → complete: Playwright smoke tests
12. **Issue #31**: Docs content (quickstart, glossary, architecture, CLI reference, API reference)
11. **Issue #30** → complete (PR #45): Playwright smoke tests
12. **Issue #31** (this PR) → complete: Docs content (quickstart, glossary, architecture, trace format, CLI reference, scenarios)
13. **Issue #32**: Release v0.1.0

## Known Blockers / Decisions Pending
Expand Down
76 changes: 76 additions & 0 deletions apps/web/src/app/docs/architecture/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
export default function ArchitecturePage() {
return (
<div>
<h1>Architecture</h1>
<p>
OCPP DebugKit is a modular monorepo with independent packages. Each package can be used
standalone or together.
</p>

<h2>Package Structure</h2>
<pre>
<code>{`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`}</code>
</pre>

<h2>Dependency Graph</h2>
<pre>
<code>{` core ← everything depends on this
/ | \\
scenarios | reporter
\\ | /
cli
|
apps/web`}</code>
</pre>

<h2>Build Order</h2>
<p>Packages must be built in dependency order: core → scenarios/reporter → cli → app</p>

<h2>Data Flow</h2>
<p>The analysis pipeline processes traces in three stages:</p>
<ol>
<li>
<strong>Parse</strong> — <code>parseTrace()</code> accepts JSON Object, JSONL, or bare
array input, validates with Zod schemas, and produces normalized <code>Event</code>{' '}
objects.
</li>
<li>
<strong>Analyze</strong> — <code>buildSessionTimeline()</code> groups events into
sessions, then <code>detectFailures()</code> checks for known failure patterns (failed
auth, connector fault, station offline).
</li>
<li>
<strong>Report</strong> — <code>generateMarkdownReport()</code> produces a human-readable
Markdown report with session overview, timeline, failures, and suggested steps.
</li>
</ol>

<h2>Browser-Local Processing</h2>
<p>
All trace processing in the web inspector happens client-side. No trace data is uploaded to
any server. The CSMS/CLI process traces locally.
</p>

<h2>Technology Stack</h2>
<ul>
<li>TypeScript (strict mode)</li>
<li>Zod for input validation</li>
<li>Vitest for testing</li>
<li>Turborepo for build orchestration</li>
<li>Next.js + Tailwind CSS for the web app</li>
<li>Commander for the CLI</li>
<li>Playwright for E2E tests</li>
</ul>
</div>
);
}
90 changes: 90 additions & 0 deletions apps/web/src/app/docs/cli/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
export default function CliReferencePage() {
return (
<div>
<h1>CLI Reference</h1>
<p>
The <code>ocpp-debugkit</code> CLI provides commands for inspecting traces, generating
reports, and running scenarios.
</p>

<h2>Installation</h2>
<pre>
<code>{`npm install -g @ocpp-debugkit/cli`}</code>
</pre>

<h2>inspect</h2>
<p>
Parse and analyze an OCPP trace file. Outputs a summary with events, sessions, failures, and
warnings.
</p>
<pre>
<code>{`ocpp-debugkit inspect <file>`}</code>
</pre>
<p>Example:</p>
<pre>
<code>{`ocpp-debugkit inspect trace.json`}</code>
</pre>

<h2>report</h2>
<p>Generate a Markdown report from an OCPP trace file.</p>
<pre>
<code>{`ocpp-debugkit report <file> [options]`}</code>
</pre>
<h3>Options</h3>
<ul>
<li>
<code>-f, --format &lt;format&gt;</code> — Report format (default: markdown)
</li>
<li>
<code>-o, --output &lt;file&gt;</code> — Write report to file (default: stdout)
</li>
</ul>
<p>Example:</p>
<pre>
<code>{`ocpp-debugkit report trace.json --output report.md`}</code>
</pre>

<h2>scenario list</h2>
<p>List all available built-in scenarios.</p>
<pre>
<code>{`ocpp-debugkit scenario list`}</code>
</pre>

<h2>scenario run</h2>
<p>
Run a built-in scenario through the analysis engine. Compares detected failures against
expected failures and reports pass/fail.
</p>
<pre>
<code>{`ocpp-debugkit scenario run <name>`}</code>
</pre>
<p>Example:</p>
<pre>
<code>{`ocpp-debugkit scenario run failed-auth`}</code>
</pre>
<p>
<strong>Note:</strong> <code>scenario run</code> runs static fixtures through the local
analysis engine only. It is not active endpoint testing, WebSocket simulation, or live
station/CSMS testing.
</p>

<h2>Global Options</h2>
<ul>
<li>
<code>-V, --version</code> — output the version number
</li>
<li>
<code>-h, --help</code> — display help for any command
</li>
</ul>

<h2>Security</h2>
<ul>
<li>File paths are validated before reading</li>
<li>Input size limit: 10 MB</li>
<li>Safe JSON parsing with error handling</li>
<li>Non-sensitive error messages (no internal paths exposed)</li>
</ul>
</div>
);
}
77 changes: 77 additions & 0 deletions apps/web/src/app/docs/glossary/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
export default function GlossaryPage() {
return (
<div>
<h1>Glossary</h1>
<p>Key OCPP and EV charging terms used throughout this project.</p>

<h2>OCPP</h2>
<p>
Open Charge Point Protocol — the communication protocol between EV charging stations (Charge
Points) and charging station management systems (CSMS). OCPP 1.6 JSON is the primary
protocol supported by DebugKit.
</p>

<h2>Charge Point (CP)</h2>
<p>
The physical EV charging station. Also referred to as a &quot;station&quot;. Communicates
with the CSMS via OCPP.
</p>

<h2>CSMS</h2>
<p>
Charging Station Management System — the central server that manages charging stations. Also
referred to as &quot;the backend&quot;.
</p>

<h2>Connector</h2>
<p>
A physical charging outlet on a charging station. A station may have multiple connectors
(e.g., connector 0 is typically the whole-station connector, connector 1+ are individual
charging outlets).
</p>

<h2>Transaction</h2>
<p>
A single charging session, initiated by a StartTransaction request and terminated by a
StopTransaction request. Each transaction has a unique transactionId assigned by the CSMS.
</p>

<h2>Call</h2>
<p>
An OCPP message type (MessageTypeId = 2) representing a request from one side to the other.
Format: <code>[2, UniqueId, Action, Payload]</code>
</p>

<h2>CallResult</h2>
<p>
An OCPP message type (MessageTypeId = 3) representing a successful response to a Call.
Format: <code>[3, UniqueId, Payload]</code>
</p>

<h2>CallError</h2>
<p>
An OCPP message type (MessageTypeId = 4) representing an error response to a Call. Format:{' '}
<code>[4, UniqueId, ErrorCode, ErrorDescription, ErrorDetails]</code>
</p>

<h2>idTag</h2>
<p>
An identifier (typically an RFID card or app token) used to authorize a charging session.
The CSMS validates the idTag and returns an authorization status (Accepted, Invalid, etc.).
</p>

<h2>Trace</h2>
<p>
A capture of OCPP messages exchanged between a Charge Point and CSMS over a period of time.
Traces are the primary input to DebugKit.
</p>

<h2>Direction</h2>
<p>
The direction of an OCPP message: <code>CS_TO_CSMS</code> (station to backend),{' '}
<code>CSMS_TO_CS</code> (backend to station), or
<code>UNKNOWN</code>.
</p>
</div>
);
}
44 changes: 44 additions & 0 deletions apps/web/src/app/docs/layout.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
import Link from 'next/link';

const docPages = [
{ href: '/docs/quickstart', label: 'Quick Start' },
{ href: '/docs/glossary', label: 'Glossary' },
{ href: '/docs/architecture', label: 'Architecture' },
{ href: '/docs/trace-format', label: 'Trace Format' },
{ href: '/docs/cli', label: 'CLI Reference' },
{ href: '/docs/scenarios', label: 'Scenarios' },
];

export default function DocsLayout({ children }: { children: React.ReactNode }) {
return (
<div className="min-h-screen bg-white dark:bg-neutral-950">
<header className="border-b border-neutral-200 dark:border-neutral-800">
<div className="mx-auto max-w-5xl px-6 py-4">
<Link href="/" className="text-lg font-bold text-neutral-900 dark:text-white">
OCPP DebugKit
</Link>
<span className="ml-2 text-sm text-neutral-500">Docs</span>
</div>
</header>
<div className="mx-auto max-w-5xl px-6 py-8 flex gap-8">
<nav className="w-48 shrink-0">
<ul className="space-y-1">
{docPages.map((page) => (
<li key={page.href}>
<Link
href={page.href}
className="block rounded px-3 py-1.5 text-sm text-neutral-600 hover:bg-neutral-100 dark:text-neutral-400 dark:hover:bg-neutral-900"
>
{page.label}
</Link>
</li>
))}
</ul>
</nav>
<main className="flex-1 min-w-0 prose prose-neutral dark:prose-invert max-w-none">
{children}
</main>
</div>
</div>
);
}
37 changes: 29 additions & 8 deletions apps/web/src/app/docs/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,33 @@
import Link from 'next/link';

export default function DocsPage() {
return (
<main className="flex min-h-screen flex-col items-center justify-center p-8">
<div className="max-w-2xl text-center">
<h1 className="text-4xl font-bold tracking-tight">Documentation</h1>
<p className="mt-4 text-lg text-neutral-600 dark:text-neutral-400">
Documentation is under construction.
</p>
</div>
</main>
<div>
<h1>Documentation</h1>
<p>
Get started with OCPP DebugKit — open-source DevTools for debugging OCPP charging sessions.
</p>
<ul>
<li>
<Link href="/docs/quickstart">Quick Start</Link> — Install and run your first trace
analysis
</li>
<li>
<Link href="/docs/glossary">Glossary</Link> — OCPP terms explained
</li>
<li>
<Link href="/docs/architecture">Architecture</Link> — Package structure and data flow
</li>
<li>
<Link href="/docs/trace-format">Trace Format</Link> — Accepted input formats
</li>
<li>
<Link href="/docs/cli">CLI Reference</Link> — Command-line interface
</li>
<li>
<Link href="/docs/scenarios">Scenarios</Link> — Predefined test scenarios
</li>
</ul>
</div>
);
}
Loading
Loading