# ionic-team/stencil architecture

> Architecture diagram of the GitHub repository ionic-team/stencil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ionic-team/stencil
- Repository: https://github.com/ionic-team/stencil

## Overview

##### Main Components Overview

a. Compiler Core
- Source Code Processing
- TypeScript/JSX Compilation
- Component Generation
- Build Pipeline

b. Runtime
- Component Lifecycle Management
- Shadow DOM Handling
- Virtual DOM Implementation
- Event System

c. Development Tools
- Dev Server
- Hot Module Reload
- Testing Infrastructure
- Screenshot Testing

##### Detailed Component Breakdown

**┌─────────────────────────────────────────────────────────────┐**
- Developer Interface                      │
- ┤
- CLI (src/cli)          Dev Server (src/dev-server)         │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────────┐**
- Compilation Pipeline                      │
- ┤
- TypeScript Transpilation                                  │
- JSX Processing                                           │
- Component Transformation                                  │
- Style Processing                                         │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────────┐**
- Runtime System                          │
- ┤
- Component Lifecycle (src/runtime)                        │
- Virtual DOM (src/runtime/vdom)                          │
- Platform Abstractions                                    │
- ┘
- ↓
**┌─────────────────────────────────────────────────────────────┐**
- Output Targets                          │
- ┤
- Custom Elements                                          │
- Hydrate/SSR                                             │
- Collection                                              │
- ┘

##### Key Interactions to Highlight

- Data flow from source files through the compilation pipeline
- How the compiler transforms decorators into static metadata
- Demonstrate the build process for different output targets

##### Important Details

- Component decorator processing pipeline
- Virtual DOM implementation
- Style processing and scoping
- Testing infrastructure
- Development server architecture
- Build optimization pipeline

##### Specific Implementation Notes

- The compiler's ability to generate different output formats
- The runtime's platform-agnostic nature
- The development server's hot reload capabilities
- The testing system's integration with Jest and Puppeteer

##### Integration Points

Connections with:
- TypeScript compiler
- Browser APIs
- Testing frameworks
- Build tools

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Developer Interface"
        CLI["CLI Tools"]:::devtools
        DevServer["Dev Server"]:::devtools
        HMR["Hot Module Reload"]:::devtools
    end

    subgraph "Compilation Pipeline"
        SourceProcess["Source Processing"]:::compiler
        TSCompile["TypeScript/JSX Compilation"]:::compiler
        CompGen["Component Generation"]:::compiler
        BuildPipe["Build Pipeline"]:::compiler
    end

    subgraph "Runtime System"
        CompLife["Component Lifecycle"]:::runtime
        VDOM["Virtual DOM"]:::runtime
        ShadowDOM["Shadow DOM Handling"]:::runtime
        EventSys["Event System"]:::runtime
    end

    subgraph "Platform Layer"
        NodeSys["Node System"]:::platform
        PlatSpec["Platform Specific"]:::platform
    end

    subgraph "Core Services"
        Hydration["Hydration"]:::service
        MockDOM["Mock DOM"]:::service
        Utils["Utilities"]:::service
    end

    subgraph "Testing Infrastructure"
        TestInfra["Testing Infrastructure"]:::testing
        Screenshot["Screenshot Testing"]:::testing
    end

    subgraph "Output Targets"
        OutputGen["Output Generation"]:::output
        Docs["Documentation"]:::output
        Prerender["Prerendering"]:::output
    end

    %% Relationships
    CLI --> SourceProcess
    DevServer --> HMR
    HMR --> CompLife

    SourceProcess --> TSCompile
    TSCompile --> CompGen
    CompGen --> BuildPipe
    BuildPipe --> OutputGen

    CompLife --> VDOM
    VDOM --> ShadowDOM
    CompLife --> EventSys

    NodeSys --> BuildPipe
    PlatSpec --> ShadowDOM

    TestInfra --> MockDOM
    Screenshot --> TestInfra

    BuildPipe --> Hydration
    BuildPipe --> Prerender
    CompGen --> Docs

    %% Click Events
    click CLI "https://github.com/ionic-team/stencil/tree/main/src/cli/"
    click DevServer "https://github.com/ionic-team/stencil/tree/main/src/dev-server/"
    click HMR "https://github.com/ionic-team/stencil/blob/main/src/dev-server/client/hmr-components.ts"
    click SourceProcess "https://github.com/ionic-team/stencil/tree/main/src/compiler/transpile/"
    click TSCompile "https://github.com/ionic-team/stencil/tree/main/src/compiler/transformers/"
    click CompGen "https://github.com/ionic-team/stencil/tree/main/src/compiler/build/"
    click BuildPipe "https://github.com/ionic-team/stencil/tree/main/src/compiler/bundle/"
    click CompLife "https://github.com/ionic-team/stencil/tree/main/src/runtime/"
    click VDOM "https://github.com/ionic-team/stencil/tree/main/src/runtime/vdom/"
    click ShadowDOM "https://github.com/ionic-team/stencil/tree/main/src/runtime/client/"
    click EventSys "https://github.com/ionic-team/stencil/blob/main/src/runtime/event-emitter.ts"
    click NodeSys "https://github.com/ionic-team/stencil/tree/main/src/sys/node/"
    click PlatSpec "https://github.com/ionic-team/stencil/tree/main/src/client/"
    click TestInfra "https://github.com/ionic-team/stencil/tree/main/src/testing/"
    click Screenshot "https://github.com/ionic-team/stencil/tree/main/src/screenshot/"
    click OutputGen "https://github.com/ionic-team/stencil/tree/main/src/compiler/output-targets/"
    click Docs "https://github.com/ionic-team/stencil/tree/main/src/compiler/docs/"
    click Prerender "https://github.com/ionic-team/stencil/tree/main/src/compiler/prerender/"
    click Hydration "https://github.com/ionic-team/stencil/tree/main/src/hydrate/"
    click MockDOM "https://github.com/ionic-team/stencil/tree/main/src/mock-doc/"
    click Utils "https://github.com/ionic-team/stencil/tree/main/src/utils/"

    %% Styles
    classDef compiler fill:#2374ab
    classDef runtime fill:#2a9d8f
    classDef devtools fill:#f4a261
    classDef platform fill:#8338ec
    classDef service fill:#06d6a0
    classDef testing fill:#ff006e
    classDef output fill:#8b5cf6

    %% Legend
    subgraph Legend
        L1["Compiler Components"]:::compiler
        L2["Runtime Components"]:::runtime
        L3["Development Tools"]:::devtools
        L4["Platform Layer"]:::platform
        L5["Core Services"]:::service
        L6["Testing Components"]:::testing
        L7["Output Components"]:::output
    end
```
