Skip to content

Commit d88e010

Browse files
sepehr-safarisepehr-safari
authored
docs: quickstart + glossary + architecture + trace format + CLI reference + scenarios (#46)
- /docs index with navigation sidebar - /docs/quickstart: install, inspect, report, scenario, web inspector, programmatic use - /docs/glossary: OCPP, CSMS, Charge Point, Connector, Transaction, Call types, 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 Closes #31
1 parent d726687 commit d88e010

9 files changed

Lines changed: 616 additions & 11 deletions

File tree

‎CURRENT_STATE.md‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -144,14 +144,24 @@ report exported. CLI and web inspector.
144144
- ✅ Sticky header for better UX on long traces
145145
- ✅ Analyze button shows "Analyzing…" and disables during parsing
146146

147-
### Playwright Smoke Tests (in progress — this PR)
147+
### Playwright Smoke Tests (PR #45)
148148

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

155+
### Docs Content (in progress — this PR)
156+
157+
- ✅ `/docs` index with navigation sidebar
158+
- ✅ `/docs/quickstart` — install, inspect, report, scenario, web inspector, programmatic use
159+
- ✅ `/docs/glossary` — OCPP, CSMS, Charge Point, Connector, Transaction, Call, CallResult, CallError, idTag, Trace, Direction
160+
- ✅ `/docs/architecture` — package structure, dependency graph, data flow, browser-local processing, tech stack
161+
- ✅ `/docs/trace-format` — JSON Object, JSONL, bare array, message structure, timestamps, limits, direction inference
162+
- ✅ `/docs/cli` — install, inspect, report, scenario list, scenario run, options, security
163+
- ✅ `/docs/scenarios` — 5 built-in scenarios, failure detection rules, running scenarios, synthetic data
164+
155165
## What's Next
156166

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

171181
## Known Blockers / Decisions Pending

‎apps/web/src/app/docs/architecture/page.tsx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
export default function ArchitecturePage() {
2+
return (
3+
<div>
4+
<h1>Architecture</h1>
5+
<p>
6+
OCPP DebugKit is a modular monorepo with independent packages. Each package can be used
7+
standalone or together.
8+
</p>
9+
10+
<h2>Package Structure</h2>
11+
<pre>
12+
<code>{`ocpp-debugkit/
13+
├── packages/
14+
│ ├── core/ # Data model, parser, normalizer, timeline, failure detection
15+
│ ├── scenarios/ # Predefined trace scenarios for testing
16+
│ ├── reporter/ # Report generators (Markdown)
17+
│ ├── cli/ # Command-line interface
18+
│ ├── replay/ # Replay engine (v0.2+)
19+
│ └── react/ # Reusable React components (v0.2+)
20+
├── apps/
21+
│ └── web/ # Single Next.js app (landing, inspector, docs)
22+
└── turbo.json # Turborepo task pipeline`}</code>
23+
</pre>
24+
25+
<h2>Dependency Graph</h2>
26+
<pre>
27+
<code>{` core ← everything depends on this
28+
/ | \\
29+
scenarios | reporter
30+
\\ | /
31+
cli
32+
|
33+
apps/web`}</code>
34+
</pre>
35+
36+
<h2>Build Order</h2>
37+
<p>Packages must be built in dependency order: core → scenarios/reporter → cli → app</p>
38+
39+
<h2>Data Flow</h2>
40+
<p>The analysis pipeline processes traces in three stages:</p>
41+
<ol>
42+
<li>
43+
<strong>Parse</strong> — <code>parseTrace()</code> accepts JSON Object, JSONL, or bare
44+
array input, validates with Zod schemas, and produces normalized <code>Event</code>{' '}
45+
objects.
46+
</li>
47+
<li>
48+
<strong>Analyze</strong> — <code>buildSessionTimeline()</code> groups events into
49+
sessions, then <code>detectFailures()</code> checks for known failure patterns (failed
50+
auth, connector fault, station offline).
51+
</li>
52+
<li>
53+
<strong>Report</strong> — <code>generateMarkdownReport()</code> produces a human-readable
54+
Markdown report with session overview, timeline, failures, and suggested steps.
55+
</li>
56+
</ol>
57+
58+
<h2>Browser-Local Processing</h2>
59+
<p>
60+
All trace processing in the web inspector happens client-side. No trace data is uploaded to
61+
any server. The CSMS/CLI process traces locally.
62+
</p>
63+
64+
<h2>Technology Stack</h2>
65+
<ul>
66+
<li>TypeScript (strict mode)</li>
67+
<li>Zod for input validation</li>
68+
<li>Vitest for testing</li>
69+
<li>Turborepo for build orchestration</li>
70+
<li>Next.js + Tailwind CSS for the web app</li>
71+
<li>Commander for the CLI</li>
72+
<li>Playwright for E2E tests</li>
73+
</ul>
74+
</div>
75+
);
76+
}

‎apps/web/src/app/docs/cli/page.tsx‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
export default function CliReferencePage() {
2+
return (
3+
<div>
4+
<h1>CLI Reference</h1>
5+
<p>
6+
The <code>ocpp-debugkit</code> CLI provides commands for inspecting traces, generating
7+
reports, and running scenarios.
8+
</p>
9+
10+
<h2>Installation</h2>
11+
<pre>
12+
<code>{`npm install -g @ocpp-debugkit/cli`}</code>
13+
</pre>
14+
15+
<h2>inspect</h2>
16+
<p>
17+
Parse and analyze an OCPP trace file. Outputs a summary with events, sessions, failures, and
18+
warnings.
19+
</p>
20+
<pre>
21+
<code>{`ocpp-debugkit inspect <file>`}</code>
22+
</pre>
23+
<p>Example:</p>
24+
<pre>
25+
<code>{`ocpp-debugkit inspect trace.json`}</code>
26+
</pre>
27+
28+
<h2>report</h2>
29+
<p>Generate a Markdown report from an OCPP trace file.</p>
30+
<pre>
31+
<code>{`ocpp-debugkit report <file> [options]`}</code>
32+
</pre>
33+
<h3>Options</h3>
34+
<ul>
35+
<li>
36+
<code>-f, --format &lt;format&gt;</code> — Report format (default: markdown)
37+
</li>
38+
<li>
39+
<code>-o, --output &lt;file&gt;</code> — Write report to file (default: stdout)
40+
</li>
41+
</ul>
42+
<p>Example:</p>
43+
<pre>
44+
<code>{`ocpp-debugkit report trace.json --output report.md`}</code>
45+
</pre>
46+
47+
<h2>scenario list</h2>
48+
<p>List all available built-in scenarios.</p>
49+
<pre>
50+
<code>{`ocpp-debugkit scenario list`}</code>
51+
</pre>
52+
53+
<h2>scenario run</h2>
54+
<p>
55+
Run a built-in scenario through the analysis engine. Compares detected failures against
56+
expected failures and reports pass/fail.
57+
</p>
58+
<pre>
59+
<code>{`ocpp-debugkit scenario run <name>`}</code>
60+
</pre>
61+
<p>Example:</p>
62+
<pre>
63+
<code>{`ocpp-debugkit scenario run failed-auth`}</code>
64+
</pre>
65+
<p>
66+
<strong>Note:</strong> <code>scenario run</code> runs static fixtures through the local
67+
analysis engine only. It is not active endpoint testing, WebSocket simulation, or live
68+
station/CSMS testing.
69+
</p>
70+
71+
<h2>Global Options</h2>
72+
<ul>
73+
<li>
74+
<code>-V, --version</code> — output the version number
75+
</li>
76+
<li>
77+
<code>-h, --help</code> — display help for any command
78+
</li>
79+
</ul>
80+
81+
<h2>Security</h2>
82+
<ul>
83+
<li>File paths are validated before reading</li>
84+
<li>Input size limit: 10 MB</li>
85+
<li>Safe JSON parsing with error handling</li>
86+
<li>Non-sensitive error messages (no internal paths exposed)</li>
87+
</ul>
88+
</div>
89+
);
90+
}

‎apps/web/src/app/docs/glossary/page.tsx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
export default function GlossaryPage() {
2+
return (
3+
<div>
4+
<h1>Glossary</h1>
5+
<p>Key OCPP and EV charging terms used throughout this project.</p>
6+
7+
<h2>OCPP</h2>
8+
<p>
9+
Open Charge Point Protocol — the communication protocol between EV charging stations (Charge
10+
Points) and charging station management systems (CSMS). OCPP 1.6 JSON is the primary
11+
protocol supported by DebugKit.
12+
</p>
13+
14+
<h2>Charge Point (CP)</h2>
15+
<p>
16+
The physical EV charging station. Also referred to as a &quot;station&quot;. Communicates
17+
with the CSMS via OCPP.
18+
</p>
19+
20+
<h2>CSMS</h2>
21+
<p>
22+
Charging Station Management System — the central server that manages charging stations. Also
23+
referred to as &quot;the backend&quot;.
24+
</p>
25+
26+
<h2>Connector</h2>
27+
<p>
28+
A physical charging outlet on a charging station. A station may have multiple connectors
29+
(e.g., connector 0 is typically the whole-station connector, connector 1+ are individual
30+
charging outlets).
31+
</p>
32+
33+
<h2>Transaction</h2>
34+
<p>
35+
A single charging session, initiated by a StartTransaction request and terminated by a
36+
StopTransaction request. Each transaction has a unique transactionId assigned by the CSMS.
37+
</p>
38+
39+
<h2>Call</h2>
40+
<p>
41+
An OCPP message type (MessageTypeId = 2) representing a request from one side to the other.
42+
Format: <code>[2, UniqueId, Action, Payload]</code>
43+
</p>
44+
45+
<h2>CallResult</h2>
46+
<p>
47+
An OCPP message type (MessageTypeId = 3) representing a successful response to a Call.
48+
Format: <code>[3, UniqueId, Payload]</code>
49+
</p>
50+
51+
<h2>CallError</h2>
52+
<p>
53+
An OCPP message type (MessageTypeId = 4) representing an error response to a Call. Format:{' '}
54+
<code>[4, UniqueId, ErrorCode, ErrorDescription, ErrorDetails]</code>
55+
</p>
56+
57+
<h2>idTag</h2>
58+
<p>
59+
An identifier (typically an RFID card or app token) used to authorize a charging session.
60+
The CSMS validates the idTag and returns an authorization status (Accepted, Invalid, etc.).
61+
</p>
62+
63+
<h2>Trace</h2>
64+
<p>
65+
A capture of OCPP messages exchanged between a Charge Point and CSMS over a period of time.
66+
Traces are the primary input to DebugKit.
67+
</p>
68+
69+
<h2>Direction</h2>
70+
<p>
71+
The direction of an OCPP message: <code>CS_TO_CSMS</code> (station to backend),{' '}
72+
<code>CSMS_TO_CS</code> (backend to station), or
73+
<code>UNKNOWN</code>.
74+
</p>
75+
</div>
76+
);
77+
}

‎apps/web/src/app/docs/layout.tsx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
import Link from 'next/link';
2+
3+
const docPages = [
4+
{ href: '/docs/quickstart', label: 'Quick Start' },
5+
{ href: '/docs/glossary', label: 'Glossary' },
6+
{ href: '/docs/architecture', label: 'Architecture' },
7+
{ href: '/docs/trace-format', label: 'Trace Format' },
8+
{ href: '/docs/cli', label: 'CLI Reference' },
9+
{ href: '/docs/scenarios', label: 'Scenarios' },
10+
];
11+
12+
export default function DocsLayout({ children }: { children: React.ReactNode }) {
13+
return (
14+
<div className="min-h-screen bg-white dark:bg-neutral-950">
15+
<header className="border-b border-neutral-200 dark:border-neutral-800">
16+
<div className="mx-auto max-w-5xl px-6 py-4">
17+
<Link href="/" className="text-lg font-bold text-neutral-900 dark:text-white">
18+
OCPP DebugKit
19+
</Link>
20+
<span className="ml-2 text-sm text-neutral-500">Docs</span>
21+
</div>
22+
</header>
23+
<div className="mx-auto max-w-5xl px-6 py-8 flex gap-8">
24+
<nav className="w-48 shrink-0">
25+
<ul className="space-y-1">
26+
{docPages.map((page) => (
27+
<li key={page.href}>
28+
<Link
29+
href={page.href}
30+
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"
31+
>
32+
{page.label}
33+
</Link>
34+
</li>
35+
))}
36+
</ul>
37+
</nav>
38+
<main className="flex-1 min-w-0 prose prose-neutral dark:prose-invert max-w-none">
39+
{children}
40+
</main>
41+
</div>
42+
</div>
43+
);
44+
}

‎apps/web/src/app/docs/page.tsx‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,33 @@
1+
import Link from 'next/link';
2+
13
export default function DocsPage() {
24
return (
3-
<main className="flex min-h-screen flex-col items-center justify-center p-8">
4-
<div className="max-w-2xl text-center">
5-
<h1 className="text-4xl font-bold tracking-tight">Documentation</h1>
6-
<p className="mt-4 text-lg text-neutral-600 dark:text-neutral-400">
7-
Documentation is under construction.
8-
</p>
9-
</div>
10-
</main>
5+
<div>
6+
<h1>Documentation</h1>
7+
<p>
8+
Get started with OCPP DebugKit — open-source DevTools for debugging OCPP charging sessions.
9+
</p>
10+
<ul>
11+
<li>
12+
<Link href="/docs/quickstart">Quick Start</Link> — Install and run your first trace
13+
analysis
14+
</li>
15+
<li>
16+
<Link href="/docs/glossary">Glossary</Link> — OCPP terms explained
17+
</li>
18+
<li>
19+
<Link href="/docs/architecture">Architecture</Link> — Package structure and data flow
20+
</li>
21+
<li>
22+
<Link href="/docs/trace-format">Trace Format</Link> — Accepted input formats
23+
</li>
24+
<li>
25+
<Link href="/docs/cli">CLI Reference</Link> — Command-line interface
26+
</li>
27+
<li>
28+
<Link href="/docs/scenarios">Scenarios</Link> — Predefined test scenarios
29+
</li>
30+
</ul>
31+
</div>
1132
);
1233
}

0 commit comments

Comments
 (0)