System Architecture

High-Level System Design (HLD)

The project is local and developer-operated. The Python CLI or notebook calls teaching-example functions; each function builds a graph and invokes it synchronously. One helper (add_messages) operates on messages directly without creating a graph. Hosted OpenAI inference is available only for two explicitly opted-in demonstrations.

System context diagram

flowchart TB
    U["Learner / Developer"] --> CLI["Python CLI: argparse"]
    U --> NB["Jupyter Notebook"]
    CLI --> SELECT["Demo selection: --topic / --self-test"]
    NB --> EX["Notebook exercise cells"]
    SELECT --> EXAMPLES["18 independent example functions"]
    EX --> EXAMPLES
    subgraph LG["LangGraph orchestration"]
      BUILDER["StateGraph builder"] --> ROUTE["Nodes, edges and conditional routers"]
      ROUTE --> RUNTIME["Compiled graph: invoke"]
      RUNTIME <--> STATE["Typed state / reducers / messages"]
      RUNTIME --> SUB["Optional nested HR / IT subgraphs"]
    end
    EXAMPLES --> BUILDER
    EXAMPLES --> MSG["add_messages helper (no graph)"]
    EXAMPLES -. "2 opt-in topics" .-> LLM["ChatOpenAI / hosted OpenAI API"]
    RUNTIME --> OUTPUT["Printed JSON / optional results.json"]
    BUILDER --> MMD["Optional per-graph Mermaid .mmd export"]

Loading

Runtime component diagram

flowchart LR
   subgraph Interface["Execution interfaces"]
     CLI["main(argv)"]
     NOTE["Notebook: independent cells"]
   end
   subgraph Controller["Project functions"]
     REG["EXAMPLES registry"]
     DEMO["example_* functions"]
     COMP["compile_graph(builder, name, dir)"]
     TEST["self_test(outputs)"]
   end
   subgraph Framework["External libraries"]
     SG["langgraph.graph.StateGraph"]
     RUN["compiled graph.invoke()"]
     MS["MessagesState / add_messages"]
     PD["Pydantic validation"]
   end
   CLI --> REG --> DEMO
   NOTE --> DEMO
   DEMO --> SG --> COMP --> RUN
   DEMO --> MS
   DEMO --> PD
   RUN --> TEST
   COMP --> MMD["Graph Mermaid output"]
   DEMO -. "opt-in" .-> AI["ChatOpenAI"]

Loading

Components and responsibilities

Component	Source code	Responsibility
CLI dispatcher	main, EXAMPLES	Topic selection, offline self-test, JSON output, diagram export
Independent topic functions	example_*	Construct a new StateGraph; invoke inputs and return result dict
Graph compiler	compile_graph	builder.compile(), optionally saves draw_mermaid() text
LangGraph	StateGraph, MessagesState, add_messages	Directed execution, typed state, channel reducers and messages
Validation	Pydantic BaseModel, Field	Validates in its own demonstration; explicit output validation
Nested workflows	example_subgraph_wrapper, example_subgraph_direct	HR/IT steps using mapped or shared state
Optional model	_openai_llm / ChatOpenAI	Remote inference for llm_node and messages_state_llm only

Data flow and deployment

Inputs are Python strings, numbers, dictionaries, or message lists. The program prints JSON to terminal and optionally writes results.json and graph .mmd files. There is no server, queue, database, checkpoint store or background worker in the submitted implementation. The notebook defines examples locally instead of importing the CLI module.

Boundaries

The full offline path uses installed local libraries only. Two optional ChatOpenAI paths cross the external API trust boundary. See Security.