kyo-system layering proposal (getkyo/kyo#1852)

kyo-system-layering-dark.svg

kyo-system-layering.dot

digraph kyo_layering {
    rankdir=TB;
    bgcolor="white";
    compound=true;
    node [shape=box, style="filled,rounded", fontname="Helvetica-Bold", fontsize=12, margin="0.22,0.13"];
    edge [fontname="Helvetica", fontsize=10, color="#5A6472", arrowsize=0.8, penwidth=1.2];
    graph [fontname="Helvetica", fontsize=11, ranksep=0.75, nodesep=0.5];

    labelloc="t";
    label=<<b><font point-size="16">kyo-system provides file operations to every schema format</font></b><br/><br/><font point-size="11" color="#5A6472">Solid = depends on.   Dashed = provides <b>path.readAs[A]</b> / <b>path.writeAs[A]</b> to every format via the Codec SPI.</font><br/> >;

    // ============ LAYER 4 : system ============
    system [label="kyo-system\nPath · FileSystem · Process\ncodec-generic file operations",
            fillcolor="#E2D7F0", color="#8B6FB8", penwidth=2.0, fontsize=13];

    // ============ LAYER 3 : formats ============
    sjson  [label="kyo-schema-json\nJson · Json.Lines · Jsonl.pipe", fillcolor="#DCEFE0", color="#7FB08D", penwidth=1.6];
    syaml  [label="kyo-schema-yaml",  fillcolor="#DCEFE0", color="#7FB08D"];
    sother [label="msgpack · bson\nion · protobuf", fillcolor="#DCEFE0", color="#7FB08D"];

    // ============ LAYER 2 : schema core + runtime ============
    schema [label="kyo-schema\nSchema · Codec SPI", fillcolor="#CFE6D4", color="#5F9B70", penwidth=1.6];
    core   [label="kyo-core\nSync · Async · Scope", fillcolor="#F5D3A4", color="#C79A55", penwidth=1.6];

    // ============ LAYER 1 : pure foundation ============
    prelude   [label="kyo-prelude\nStream · Pipe · Abort\n(pure, no threads)", fillcolor="#C6D4E8", color="#5C7CA6", penwidth=1.6];
    scheduler [label="kyo-scheduler\n(threads)", fillcolor="#F7DFC0", color="#C79A55"];

    // ============ LAYER 0 ============
    kernel [label="kyo-kernel", fillcolor="#DCE4EE", color="#8FA3BC"];
    data   [label="kyo-data",   fillcolor="#DCE4EE", color="#8FA3BC"];

    // ---- rank bands ----
    { rank=same; sjson; syaml; sother; }
    { rank=same; schema; core; }
    { rank=same; prelude; scheduler; }

    // ---- dependencies ----
    system -> core   [color="#7A5BA6", penwidth=2.2];
    system -> schema [color="#7A5BA6", penwidth=2.2];

    sjson  -> schema;
    syaml  -> schema;
    sother -> schema;

    sjson -> prelude [color="#1F6FB2", penwidth=2.6,
                      label=<<font color="#1F6FB2"><b>  NEW  </b><br/>  streaming without<br/>  the runtime</font>>];

    schema -> data;
    core   -> prelude;
    core   -> scheduler;
    prelude -> kernel;
    kernel  -> data;

    // ---- capability edge, drawn separately so it reads as "provides", not "depends" ----
    system -> sjson [style=dashed, color="#8B6FB8", penwidth=1.8, constraint=false, arrowhead=vee];
    system -> syaml  [style=dashed, color="#8B6FB8", penwidth=1.4, constraint=false, arrowhead=vee];
    system -> sother [style=dashed, color="#8B6FB8", penwidth=1.4, constraint=false, arrowhead=vee];
}

kyo-system-layering.svg