Problem statement
Design the object model and core APIs for a library that turns a JSON document (a string, or bytes) into an in-memory value tree, and reports precisely where and why malformed input fails. The parser is the engine other code builds on: a config loader, an HTTP body reader, or a REPL all feed it text and read back a typed tree.
Operating context. A single in-process library, no network and no threads shared across a parse. Input is a UTF-8 document conforming to the JSON grammar: an object, an array, or a scalar (string, number, true, false, null). Parsing is two staged jobs the caller may reason about separately — a lexer (tokenizer) that scans characters into a token stream (punctuation, string, number, keyword literals, end-of-input) while tracking line and column, and a recursive-descent parser that consumes tokens to build the value tree. Numbers, strings with escapes, and nesting depth are all part of the grammar. The library also exposes strictness knobs: some callers want RFC-strict JSON, others tolerate trailing commas, comments, or unquoted keys — the same core must serve both without a fork.
Out of scope. Serialization / pretty-printing the tree back to text, a schema-validation or query layer over the tree, mapping the tree onto user-defined classes (binding / reflection), the I/O that reads the file or socket, and performance micro-tuning such as SIMD scanning — model the in-process object graph and its contracts, not the app around it.
What to produce. The class hierarchy (entities such as the Lexer and Parser; a value model for objects, arrays, and primitives; value objects such as a Token, a source Position, and a parse error), the public API each class exposes, and the state transitions for the lexer's scan and the parser's descent. Be explicit about: how the value model represents the six JSON kinds behind one type so callers can walk a heterogeneous tree, how a syntax error carries an exact line/column and an expected-vs-found message instead of a bare boolean, how the lexer stays separable so a future streaming (incremental, chunk-fed) mode drops in without rewriting the parser, and how strictness options plug in so trailing-comma or comment tolerance is a configured policy, not a scattered set of if-branches.