# baidu/san-ssr architecture

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

- Interactive diagram: https://gitdiagram.com/baidu/san-ssr
- Repository: https://github.com/baidu/san-ssr

## Overview

##### Project type and purpose
- This is an open-source, CLI and programmatic library (“san-ssr”) that performs static analysis and server-side rendering code generation for San framework components.
- It exposes both a command-line front end (bin/) and a TypeScript/JavaScript API (src/models/SanProject).

##### File-structure analysis
- Top-level directories:
- bin/ – CLI entry scripts (debug, render-by-source, on-the-fly).
- demo/ – example usage to illustrate API and CLI.
- src/ – core modules, organized into:
– parsers/ – turn San/JS/TS source files into AST.
– ast/ – AST utilities, walkers, type guards.
– optimizers/ – AST transforms (bracket-to-dot, literal merges).
– compilers/ – compile ASTs into intermediate compiler models.
– runtime/ – runtime helpers for the generated SSR code.
– target-js/ – JS target implementation of the Compiler interface (emit JS code).
– models/ – type definitions for project, components, compiler, options.
– helpers/ and utils/ – cross-cutting utility functions.
– bin/ – programmatic entry point for SSR in code.
- test/ – unit, E2E, performance, stub and fixture cases.
- types/ – TypeScript declarations for consumers.
- Configuration files (jest.config.js, tsconfig.json, eslint, CI workflows) support testing, linting, and release automation.

##### Insights from README
- Core abstraction: SanProject class orchestrates end-to-end pipeline: component input → parser → AST → optimization → Compiler interface → target code → render function → HTML output.
- Supports multiple targets (js, php) via san-ssr-target-<target> plugins.
- CLI flag `--target` selects emitter implementation.

##### Components
1) CLI / API Layer
2) SanProject Orchestrator
3) Parsers Module
4) AST Utilities
5) Optimizers
6) Compiler Module
7) Target Code Generators (JS / PHP etc.)
8) Runtime Helpers
9) File I/O & Configuration
10) Demo & Tests (supporting examples & validation)
b. Relationships and data flow:
- CLI/API → SanProject
- SanProject → Parsers → produces AST
- AST → Optimizers → transforms AST
- Optimized AST → Compiler → intermediate representation
- IR → Target Code Generator → SSR code (JS or PHP)
- SSR code + Runtime Helpers → render function → HTML string
- File I/O for reading component sources and writing output
- Tests and Demo consume API & CLI to validate pipeline
c. Architectural patterns & principles:
- Pipeline pattern: discrete, composable stages (parse → optimize → compile → emit).
- Plugin/strategy pattern for target code generation (implements a common Compiler interface).
- Modular separation by concern (parsing vs. AST utilities vs. optimization vs. codegen).
- Strong typings via TypeScript for models and interfaces.
d. Key technologies/frameworks:
- Node.js (bin scripts)
- TypeScript (src, tests)
- Jest (unit & E2E tests)
- Semantic Release + GitHub Actions (CI/CD)
- San template parser (peer dependency)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI / API Layer
    subgraph "CLI / API Layer"
        direction TB
        CLI_Debug["debug"]:::cli
        CLI_RenderBySource["render-by-source.js"]:::cli
        CLI_RenderOntheFly["render-onthefly.js"]:::cli
        CLI_AutoComplete["auto-complete"]:::cli
        CLI_SSR["ssr.ts"]:::cli
    end

    %% Orchestrator
    SanProject["SanProject Orchestrator"]:::orchestrator

    %% Pipeline Stages
    subgraph "Parsing Stage"
        direction TB
        Parsers["Parsers Module"]:::parsers
    end

    subgraph "AST Utilities"
        direction TB
        ASTUtils["AST Utilities"]:::ast
    end

    subgraph "Optimization Stage"
        direction TB
        Optimizers["Optimizers"]:::optimizer
    end

    subgraph "Compiler Module"
        direction TB
        Compiler["Compiler Module"]:::compiler
    end

    subgraph "Target Code Generation"
        direction TB
        TargetJS["JS Target Generator"]:::target
        TargetPHP["PHP Target Generator"]:::target_ext
    end

    SSRCode["SSR Code (JS/PHP)"]:::code

    subgraph "Runtime Helpers"
        direction TB
        RuntimeHelpers["Runtime Helpers"]:::runtime
    end

    RenderFunc["Render Function"]:::runtime
    HTMLOutput["HTML Output"]:::output

    %% File I/O & Config
    FileIO["File I/O & Configuration"]:::io

    %% Demo & Tests
    subgraph "Demo & Tests"
        direction TB
        Demo["demo/"]:::demo
        Tests["test/"]:::demo
    end

    %% Data Flow
    FileIO -->|reads config| CLI_Debug
    FileIO -->|reads config| CLI_RenderBySource
    FileIO -->|reads config| CLI_RenderOntheFly
    FileIO -->|reads config| CLI_AutoComplete
    FileIO -->|reads config| CLI_SSR

    CLI_Debug -->|"invokes"| SanProject
    CLI_RenderBySource -->|"invokes"| SanProject
    CLI_RenderOntheFly -->|"invokes"| SanProject
    CLI_AutoComplete -->|"invokes"| SanProject
    CLI_SSR -->|"invokes"| SanProject

    SanProject -->|"parses source"| Parsers
    Parsers -->|"produces AST"| ASTUtils
    ASTUtils -->|"transforms AST"| Optimizers
    Optimizers -->|"produces optimized AST"| Compiler
    Compiler -->|"generates IR"| TargetJS
    Compiler -->|"generates IR"| TargetPHP
    TargetJS -->|"emits SSR code"| SSRCode
    TargetPHP -->|"emits SSR code"| SSRCode
    SSRCode -->|"uses helpers"| RuntimeHelpers
    SSRCode -->|"+ helpers"| RenderFunc
    RuntimeHelpers -->|"provides runtime"| RenderFunc
    RenderFunc -->|"renders"| HTMLOutput

    Demo -->|"uses CLI/API"| CLI_Debug
    Demo -->|"uses CLI/API"| CLI_SSR
    Tests -->|"validates pipeline"| SanProject

    %% Click Events for component mapping
    click CLI_Debug "https://github.com/baidu/san-ssr/tree/master/bin/debug"
    click CLI_RenderBySource "https://github.com/baidu/san-ssr/blob/master/bin/render-by-source.js"
    click CLI_RenderOntheFly "https://github.com/baidu/san-ssr/blob/master/bin/render-onthefly.js"
    click CLI_AutoComplete "https://github.com/baidu/san-ssr/tree/master/bin/auto-complete"
    click CLI_SSR "https://github.com/baidu/san-ssr/blob/master/src/bin/ssr.ts"
    click SanProject "https://github.com/baidu/san-ssr/blob/master/src/models/san-project.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/component-class-parser.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/javascript-san-parser.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/typescript-san-parser.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/san-file-parser.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/parse-template.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/normalize-component.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/remove-modules.ts"
    click Parsers "https://github.com/baidu/san-ssr/blob/master/src/parsers/tsconfig.ts"
    click ASTUtils "https://github.com/baidu/san-ssr/blob/master/src/ast/js-ast-util.ts"
    click ASTUtils "https://github.com/baidu/san-ssr/blob/master/src/ast/ts-ast-util.ts"
    click ASTUtils "https://github.com/baidu/san-ssr/blob/master/src/ast/san-ast-util.ts"
    click ASTUtils "https://github.com/baidu/san-ssr/blob/master/src/ast/san-ast-type-guards.ts"
    click ASTUtils "https://github.com/baidu/san-ssr/blob/master/src/ast/renderer-ast-util.ts"
    click ASTUtils "https://github.com/baidu/san-ssr/blob/master/src/ast/renderer-ast-walker.ts"
    click ASTUtils "https://github.com/baidu/san-ssr/blob/master/src/ast/renderer-ast-dfn.ts"
    click Optimizers "https://github.com/baidu/san-ssr/blob/master/src/optimizers/bracket-to-dot.ts"
    click Optimizers "https://github.com/baidu/san-ssr/blob/master/src/optimizers/merge-literal-add.ts"
    click Compiler "https://github.com/baidu/san-ssr/blob/master/src/compilers/anode-compiler.ts"
    click Compiler "https://github.com/baidu/san-ssr/blob/master/src/compilers/element-compiler.ts"
    click Compiler "https://github.com/baidu/san-ssr/blob/master/src/compilers/renderer-compiler.ts"
    click Compiler "https://github.com/baidu/san-ssr/blob/master/src/compilers/san-expr-compiler.ts"
    click Compiler "https://github.com/baidu/san-ssr/blob/master/src/compilers/ts2js.ts"
    click Compiler "https://github.com/baidu/san-ssr/blob/master/src/compilers/renderer-options.ts"
    click Compiler "https://github.com/baidu/san-ssr/blob/master/src/compilers/reserved-names.ts"
    click TargetJS "https://github.com/baidu/san-ssr/blob/master/src/target-js/index.ts"
    click TargetJS "https://github.com/baidu/san-ssr/blob/master/src/target-js/js-emitter.ts"
    click TargetJS "https://github.com/baidu/san-ssr/blob/master/src/target-js/compilers/component-compiler.ts"
    click TargetJS "https://github.com/baidu/san-ssr/blob/master/src/target-js/compilers/compile-options.ts"
    click RuntimeHelpers "https://github.com/baidu/san-ssr/blob/master/src/runtime/create-helpers.ts"
    click RuntimeHelpers "https://github.com/baidu/san-ssr/blob/master/src/runtime/helpers.ts"
    click RuntimeHelpers "https://github.com/baidu/san-ssr/blob/master/src/runtime/resolver.ts"
    click RuntimeHelpers "https://github.com/baidu/san-ssr/blob/master/src/runtime/san-ssr-data.ts"
    click RuntimeHelpers "https://github.com/baidu/san-ssr/blob/master/src/runtime/underscore.ts"
    click FileIO "https://github.com/baidu/san-ssr/blob/master/src/utils/fs.ts"
    click FileIO "https://github.com/baidu/san-ssr/blob/master/tsconfig.json"
    click FileIO "https://github.com/baidu/san-ssr/blob/master/jest.config.js"
    click FileIO "https://github.com/baidu/san-ssr/blob/master/package.json"
    click Demo "https://github.com/baidu/san-ssr/tree/master/demo/"
    click Tests "https://github.com/baidu/san-ssr/tree/master/test/"

    %% Styles
    classDef cli fill:#ffe4b5,stroke:#d2691e,stroke-width:2px
    classDef orchestrator fill:#add8e6,stroke:#1e90ff,stroke-width:2px
    classDef parsers fill:#e6e6fa,stroke:#9370db,stroke-width:2px
    classDef ast fill:#e0ffe0,stroke:#008000,stroke-width:2px
    classDef optimizer fill:#fffacd,stroke:#ffd700,stroke-width:2px
    classDef compiler fill:#f0f8ff,stroke:#4682b4,stroke-width:2px
    classDef target fill:#ffe4e1,stroke:#dc143c,stroke-width:2px
    classDef target_ext fill:#ffc0cb,stroke:#c71585,stroke-width:2px
    classDef code fill:#faf0e6,stroke:#8b4513,stroke-width:2px
    classDef runtime fill:#e0ffff,stroke:#20b2aa,stroke-width:2px
    classDef output fill:#fff0f5,stroke:#db7093,stroke-width:2px
    classDef io fill:#f5f5f5,stroke:#a9a9a9,stroke-width:2px
    classDef demo fill:#ffe4b5,stroke:#d2691e,stroke-width:1px,stroke-dasharray: 5 5
```
