# Architecture (/developers/pinets/architecture)



## Architecture Guide [#architecture-guide]

This section provides a deep dive into the internal architecture of PineTS. It is intended for **contributors** and **developers** who need to understand the transpilation pipeline, runtime execution model, and core design decisions to extend or debug the engine.

## Overview [#overview]

PineTS bridges the gap between Pine Script's unique time-series semantics and standard JavaScript execution through a three-layer architecture:

```
┌─────────────────────────────────────────────────┐
│          User PineTS Code (Input)           │
│    (Looks like Pine Script, uses JS syntax) │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│           Transpiler Layer                  │
│  • AST Parsing (acorn)                      │
│  • Scope Analysis                           │
│  • Code Transformation                      │
│  • Context Variable Management              │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│         Runtime Execution Layer             │
│  • Context Object ($)                       │
│  • Series Management                        │
│  • Namespace Functions (ta, math, etc.)     │
│  • State Management                         │
└─────────────────────────────────────────────────┘
```

### Main Components [#main-components]

1. **PineTS Class**: Orchestrates market data loading, execution, and pagination
2. **Context Class**: Maintains execution state, series data, and namespaces
3. **Transpiler**: Transforms PineTS code into executable JavaScript
4. **Namespaces**: Provide Pine Script functions (ta.ema, math.abs, etc.)

## Documentation Structure [#documentation-structure]

### Core Architecture [#core-architecture]

* [Transpiler Architecture](/developers/pinets/architecture/transpiler): Details on AST parsing, scope analysis, and code transformation.
  * [Scope Manager](/developers/pinets/architecture/transpiler/scope-manager): Variable renaming and unique ID generation
  * [Transformers](/developers/pinets/architecture/transpiler/transformers): AST transformation logic
  * [Real Examples](/developers/pinets/architecture/transpiler/examples): Actual transpilation output examples
* [Runtime Engine](/developers/pinets/architecture/runtime): How the `Context`, `Series`, and execution loop work.
  * [Context Class](/developers/pinets/architecture/runtime/context): The global state object
  * [Series Class](/developers/pinets/architecture/runtime/series): Forward storage with reverse access
  * [Execution Flow](/developers/pinets/architecture/runtime/execution-flow): Run loop and pagination
* [Namespaces](/developers/pinets/architecture/namespaces): Implementation of `ta`, `math`, `request`, etc.
  * [Technical Analysis (ta)](/developers/pinets/architecture/namespaces/ta): TA functions implementation
  * [Math (math)](/developers/pinets/architecture/namespaces/math): Mathematical operations
  * [Array (array)](/developers/pinets/architecture/namespaces/array): Array operations
  * [Request (request)](/developers/pinets/architecture/namespaces/request): Multi-timeframe analysis
  * [Input (input)](/developers/pinets/architecture/namespaces/input): User input handling
* [Critical Implementation Details](/developers/pinets/architecture/specifics): Deep dives into tuple handling, `request.security`, and other complex features.
  * [Tuple Handling](/developers/pinets/architecture/specifics/tuples): Double bracket convention
  * [Request Security](/developers/pinets/architecture/specifics/request-security): Secondary context architecture

### Developer Resources [#developer-resources]

* [Debugging Guide](/developers/pinets/architecture/debugging): Practical debugging techniques and common issues
* [Best Practices](/developers/pinets/architecture/best-practices): Common pitfalls and recommended patterns
* [Syntax Evolution](/developers/pinets/architecture/syntax-evolution): Migration from old to new syntax

## Key Design Principles [#key-design-principles]

1. **Series-First**: Everything is a time-series. The `Series` class is the fundamental data unit.
2. **Forward Storage, Reverse Access**: Data is stored chronologically (push to end) but accessed with reverse indexing (`close[1]` is previous).
3. **Incremental Calculation**: Functions utilize state to calculate values O(1) per bar rather than recalculating history.
4. **State Isolation**: Unique IDs ensure that multiple calls to the same function maintain separate internal states.