# thesephist/torus architecture

> Architecture diagram of the GitHub repository thesephist/torus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thesephist/torus
- Repository: https://github.com/thesephist/torus

## Overview

##### Project type and purpose
- Torus is an event-driven, model-view UI framework for the web, shipped as an npm package (“torus-dom”).
- Its purpose: expose a tiny virtual-DOM, component, templating, data-model (Record/Store/Router) API with no runtime dependencies.

##### File structure
Top-level:
- src/       ← core implementation modules
- renderers/ ← optional renderer backend (string renderer)
- types/     ← TypeScript declaration file
- build/     ← custom build toolchain script
- doc/       ← documentation generator templates and scripts
- docs/      ← published API docs and demos
- samples/   ← sample apps illustrating Torus usage
- test/      ← unit tests
- dist/      ← (generated at build time) packaged outputs
- config & scripts: package.json, .travis.yml, karma.conf.js, .eslintrc.js

##### README for insights
- Runtime API: Component, StyledComponent, Record, Store, Router, jdom tag.
- Build: “yarn build” → runs build/build.js → Webpack → outputs to dist/.
- Docs: “yarn docs” → doc/generate.js → publishes to docs/.
- Tests: “yarn test” (dev build) and “yarn test:prod” (minified build) via Karma.

##### Main components & interactions
a. Core modules (src/)
– jdom.js: template-tag parser → produces virtual DOM representations
– torus.js: defines Component base class, virtual DOM diff & patch engine, CSS-in-JS (StyledComponent), data models (Record, Store), Router
– index.js: entry point that re-exports APIs
b. Renderer plugin (renderers/string-renderer.js)
– Implements a server-side/string output of virtual DOM
c. Build pipeline (build/build.js)
– Cleans debug calls, bundles via Webpack (dev & prod), produces dist/index.js and dist/index.min.js
d. Documentation pipeline (doc/generate.js)
– Parses `//>` comments in src/ → uses template.html & main.css → outputs API docs under docs/
e. Testing (test/*.js + karma.conf.js)
– Unit tests for jdom, torus, CSS injection; run against both dev & prod bundles
f. Samples (samples/*)
– HTML + JS demo apps that import the dist bundle to exercise the API

##### Architectural patterns & design principles
- Modular + plugin-friendly (core + optional renderers)
- Event-driven data models (Observer pattern for Record/Store)
- Virtual DOM diff & patch (in-house minimal implementation)
- CSS-in-JS scoped styling via preprocessor hook on JDOM
- Runtime-only templating (no compile step)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Source"
        jdom["jdom.js"]:::core
        torus["torus.js"]:::core
        index["index.js"]:::core
        types["index.d.ts"]:::core
        stringR["string-renderer.js"]:::core
    end

    subgraph "Build & Docs Pipelines"
        build["build.js"]:::pipeline
        webpack["Webpack (dev & prod)"]:::pipeline
        docGen["generate.js"]:::pipeline
        temHtml["template.html"]:::pipeline
        temCss["main.css"]:::pipeline
    end

    subgraph "Outputs"
        distDev["index.js"]:::output
        distProd["index.min.js"]:::output
        docs["docs/"]:::output
    end

    subgraph "Testing"
        karma["karma.conf.js"]:::test
        testJdom["test/jdom.js"]:::test
        testTorus["test/torus.js"]:::test
        testCss["test/css.js"]:::test
    end

    subgraph "Samples"
        samples["samples/"]:::samples
    end

    subgraph "Config"
        pkg["package.json"]:::config
        travis[".travis.yml"]:::config
        eslint[".eslintrc.js"]:::config
        gitignore[".gitignore"]:::config
    end

    %% Connections
    jdom & torus & index & types & stringR -->|"yarn build"| build
    build --> webpack
    webpack -->|"bundle dev"| distDev
    webpack -->|"bundle prod"| distProd

    jdom & torus & index -->|"yarn docs"| docGen
    docGen --> temHtml
    docGen --> temCss
    temHtml & temCss --> docs

    distDev & distProd -->|"run tests"| karma
    karma --> testJdom
    karma --> testTorus
    karma --> testCss

    distDev & distProd -->|"import"| samples

    %% Click Events
    click jdom "https://github.com/thesephist/torus/blob/master/src/jdom.js"
    click torus "https://github.com/thesephist/torus/blob/master/src/torus.js"
    click index "https://github.com/thesephist/torus/blob/master/src/index.js"
    click types "https://github.com/thesephist/torus/blob/master/types/index.d.ts"
    click stringR "https://github.com/thesephist/torus/blob/master/renderers/string-renderer.js"
    click build "https://github.com/thesephist/torus/blob/master/build/build.js"
    click docGen "https://github.com/thesephist/torus/blob/master/doc/generate.js"
    click temHtml "https://github.com/thesephist/torus/blob/master/doc/template.html"
    click temCss "https://github.com/thesephist/torus/blob/master/doc/main.css"
    click docs "https://github.com/thesephist/torus/tree/master/docs/"
    click karma "https://github.com/thesephist/torus/blob/master/karma.conf.js"
    click testJdom "https://github.com/thesephist/torus/blob/master/test/jdom.js"
    click testTorus "https://github.com/thesephist/torus/blob/master/test/torus.js"
    click testCss "https://github.com/thesephist/torus/blob/master/test/css.js"
    click samples "https://github.com/thesephist/torus/tree/master/samples/"

    %% Styles
    classDef core fill:#e6ffe6,stroke:#268d36
    classDef pipeline fill:#e6f0ff,stroke:#1f6feb
    classDef output fill:#f0f8ff,stroke:#0366d6
    classDef test fill:#fff5e5,stroke:#d55700
    classDef samples fill:#f5e6ff,stroke:#6f42c1
    classDef config fill:#f0f0f0,stroke:#cccccc
```
