Carlos Gutierrez
a63a758cc5
- Static compiler with STRC pattern (Static Template Resolution with
Compartmentalized Layers)
- Template syntax: { } interpolation, { s-for }, { s-if/s-elif/s-else
}
- File types: .strata, .compiler.sts, .service.sts, .api.sts, .sts,
.scss
- CLI tools: strata-compile dev, strata-compile build, strata-compile
g (generators)
- create-strata-compile scaffolding CLI with Pokemon API example
- Dev server with WebSocket HMR (Hot Module Replacement)
- Documentation: README, ARCHITECTURE, CHANGELOG, CONTRIBUTING,
LICENSE
861 lines
60 KiB
Markdown
861 lines
60 KiB
Markdown
# Strata Framework Architecture
|
|
|
|
**Strata** = Static Template Rendering Architecture
|
|
|
|
A compile-time web framework that resolves templates to pure HTML at build time.
|
|
|
|
```
|
|
╔═══════════════════════════════════════════════════════════════════╗
|
|
║ ║
|
|
║ Code Faster. Load Quick. Deploy ASAP. ║
|
|
║ ║
|
|
╚═══════════════════════════════════════════════════════════════════╝
|
|
```
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Core Principles](#core-principles)
|
|
2. [Design Pattern: STRC](#design-pattern-strc)
|
|
3. [Compilation Flow](#compilation-flow)
|
|
4. [File Types & Layers](#file-types--layers)
|
|
5. [Template Syntax](#template-syntax)
|
|
6. [Import Hierarchy](#import-hierarchy)
|
|
7. [Runtime Architecture](#runtime-architecture)
|
|
8. [Dev Server Architecture](#dev-server-architecture)
|
|
9. [Future: Shared Worker](#future-shared-worker-architecture)
|
|
10. [Future: Smart Fetch](#future-smart-fetch-system)
|
|
11. [Future: Encrypted Store](#future-encrypted-store)
|
|
12. [Performance Targets](#performance-targets)
|
|
|
|
---
|
|
|
|
## Core Principles
|
|
|
|
| # | Principle | Description |
|
|
|---|-----------|-------------|
|
|
| 1 | **Static First** | All templates resolved at build time, not runtime |
|
|
| 2 | **Zero Runtime Overhead** | Output is pure HTML with no framework code |
|
|
| 3 | **Strict Separation** | Each file type has exactly one responsibility |
|
|
| 4 | **Go Compiler** | Fast builds with native performance |
|
|
| 5 | **Compartmentalized Layers** | Clear boundaries between template, data, and logic |
|
|
|
|
---
|
|
|
|
## Design Pattern: STRC
|
|
|
|
**STRC** = **S**tatic **T**emplate **R**esolution with **C**ompartmentalized Layers
|
|
|
|
### Pattern Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ BUILD TIME │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ SOURCE FILES STATIC COMPILER │
|
|
│ ════════════ ═══════════════ │
|
|
│ │
|
|
│ ┌─────────────┐ │
|
|
│ │ .strata │─────┐ │
|
|
│ │ (Template) │ │ │
|
|
│ └─────────────┘ │ ┌────────────────────────────────┐ │
|
|
│ │ │ │ │
|
|
│ ┌─────────────┐ ├─────────▶│ STRATA STATIC COMPILER │ │
|
|
│ │ .compiler │─────┤ │ │ │
|
|
│ │ .sts │ │ │ 1. Parse .strata to AST │ │
|
|
│ │ (Variables) │ │ │ 2. Load .compiler.sts exports │ │
|
|
│ └─────────────┘ │ │ 3. Resolve { variables } │ │
|
|
│ │ │ 4. Expand { s-for } loops │ │
|
|
│ ┌─────────────┐ │ │ 5. Evaluate { s-if } blocks │ │
|
|
│ │ .service │─────┘ │ 6. Output pure HTML │ │
|
|
│ │ .sts │ │ │ │
|
|
│ │ (Logic) │ └──────────────┬─────────────────┘ │
|
|
│ └─────────────┘ │ │
|
|
│ │ │
|
|
│ ┌─────────────┐ │ │
|
|
│ │ .scss │───────────────────────────────┤ │
|
|
│ │ (Styles) │ │ │
|
|
│ └─────────────┘ │ │
|
|
│ │ │
|
|
└─────────────────────────────────────────────────┼────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ RUNTIME │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ OUTPUT │
|
|
│ ══════ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ │ │
|
|
│ │ PURE HTML │ │
|
|
│ │ │ │
|
|
│ │ • No { } syntax │ │
|
|
│ │ • No s-for directives │ │
|
|
│ │ • No s-if conditionals │ │
|
|
│ │ • No framework JavaScript (unless .service.sts defines) │ │
|
|
│ │ │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ Optional: Runtime JavaScript from .service.sts │ │
|
|
│ │ (Event handlers, interactivity, etc.) │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Layer Responsibilities
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ STRC LAYERS │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ LAYER 1: TEMPLATE (.strata) │
|
|
│ ═══════════════════════════ │
|
|
│ • Pure HTML structure │
|
|
│ • Strata directives ({ }, s-for, s-if) │
|
|
│ • No logic, no JavaScript │
|
|
│ • Variables injected from compiler layer │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ LAYER 2: COMPILER (.compiler.sts) │
|
|
│ ═════════════════════════════════ │
|
|
│ • Variable definitions │
|
|
│ • Data structures (arrays, objects) │
|
|
│ • Build-time constants │
|
|
│ • Executed during compilation │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ LAYER 3: SERVICE (.service.sts) │
|
|
│ ════════════════════════════════ │
|
|
│ • Business logic │
|
|
│ • API calls (build-time or runtime) │
|
|
│ • Event handlers │
|
|
│ • Optional browser interactivity │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ LAYER 4: API CONTRACT (.api.sts) │
|
|
│ ════════════════════════════════ │
|
|
│ • Declarative endpoint definitions │
|
|
│ • Request/response schemas │
|
|
│ • Cache policies │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ LAYER 5: UTILITIES (.sts) │
|
|
│ ═════════════════════════ │
|
|
│ • Pure functions │
|
|
│ • No side effects │
|
|
│ • Shared helpers │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Compilation Flow
|
|
|
|
### Step-by-Step Process
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ COMPILATION PIPELINE │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ STEP 1: PARSE TEMPLATE │
|
|
│ ══════════════════════ │
|
|
│ │
|
|
│ Input: Output: │
|
|
│ ┌──────────────────────┐ ┌──────────────────────┐ │
|
|
│ │ <template> │ │ AST │ │
|
|
│ │ <h1>{ title }</h1> │ ────▶ │ ├─ TemplateNode │ │
|
|
│ │ { s-for ... } │ │ │ └─ ElementNode │ │
|
|
│ │ </template> │ │ │ └─ Interp... │ │
|
|
│ └──────────────────────┘ └──────────────────────┘ │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ STEP 2: LOAD COMPILER SCOPE │
|
|
│ ═══════════════════════════ │
|
|
│ │
|
|
│ Input: Output: │
|
|
│ ┌──────────────────────┐ ┌──────────────────────┐ │
|
|
│ │ export const title │ │ scope = { │ │
|
|
│ │ = 'Hello'; │ ────▶ │ title: 'Hello', │ │
|
|
│ │ export const items │ │ items: [...] │ │
|
|
│ │ = [...]; │ │ } │ │
|
|
│ └──────────────────────┘ └──────────────────────┘ │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ STEP 3: RESOLVE TEMPLATE │
|
|
│ ════════════════════════ │
|
|
│ │
|
|
│ Process: │
|
|
│ ┌──────────────────────────────────────────────────────────────┐ │
|
|
│ │ │ │
|
|
│ │ For each AST node: │ │
|
|
│ │ │ │
|
|
│ │ • InterpolationNode { var } → Look up in scope, output │ │
|
|
│ │ • ForBlockNode { s-for } → Iterate, create loop scope │ │
|
|
│ │ • IfBlockNode { s-if } → Evaluate, include/exclude │ │
|
|
│ │ • ElementNode <div> → Output tag + recurse │ │
|
|
│ │ • TextNode → Output as-is │ │
|
|
│ │ │ │
|
|
│ └──────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ STEP 4: OUTPUT │
|
|
│ ══════════════ │
|
|
│ │
|
|
│ Result: │
|
|
│ ┌──────────────────────────────────────────────────────────────┐ │
|
|
│ │ <h1>Hello</h1> │ │
|
|
│ │ <div class="item">Item 1</div> │ │
|
|
│ │ <div class="item">Item 2</div> │ │
|
|
│ │ <div class="item">Item 3</div> │ │
|
|
│ └──────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ Pure HTML. No framework syntax. No runtime overhead. │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Expression Resolution
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ EXPRESSION RESOLUTION │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ SIMPLE VARIABLE │
|
|
│ ─────────────── │
|
|
│ Template: { title } │
|
|
│ Scope: { title: "Hello World" } │
|
|
│ Output: Hello World │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ PROPERTY ACCESS │
|
|
│ ─────────────── │
|
|
│ Template: { user.name } │
|
|
│ Scope: { user: { name: "Alice", age: 30 } } │
|
|
│ Output: Alice │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ NESTED ACCESS │
|
|
│ ───────────── │
|
|
│ Template: { config.api.baseUrl } │
|
|
│ Scope: { config: { api: { baseUrl: "https://..." } } } │
|
|
│ Output: https://... │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ LOOP VARIABLE │
|
|
│ ───────────── │
|
|
│ Template: { s-for item in items } │
|
|
│ { item.name } │
|
|
│ { /s-for } │
|
|
│ │
|
|
│ Scope: { items: [{ name: "A" }, { name: "B" }] } │
|
|
│ │
|
|
│ Loop 1: loopScope = { ...scope, item: { name: "A" } } │
|
|
│ Output: A │
|
|
│ │
|
|
│ Loop 2: loopScope = { ...scope, item: { name: "B" } } │
|
|
│ Output: B │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## File Types & Layers
|
|
|
|
### File Extension Matrix
|
|
|
|
| Extension | Layer | Execution | Can Import | Purpose |
|
|
|-----------|-------|-----------|------------|---------|
|
|
| `.strata` | Template | Build | `.strata` | HTML structure |
|
|
| `.compiler.sts` | Compiler | Build | `.service.sts`, `.api.sts`, `.sts` | Variables |
|
|
| `.service.sts` | Service | Build + Runtime | `.api.sts`, `.sts` | Logic |
|
|
| `.api.sts` | API | Build | `.sts` | Endpoints |
|
|
| `.sts` | Utility | Both | `.sts` | Pure functions |
|
|
| `.scss` | Style | Build | - | Styles |
|
|
|
|
### Component/Page Structure
|
|
|
|
```
|
|
src/pages/index/
|
|
├── index.strata # Template (what to render)
|
|
├── index.compiler.sts # Data (what values to use)
|
|
├── index.service.sts # Logic (how it behaves)
|
|
└── index.scss # Styles (how it looks)
|
|
```
|
|
|
|
### File Content Examples
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ index.strata │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ <template> │
|
|
│ <main class="page"> │
|
|
│ <h1>{ title }</h1> │
|
|
│ { s-for item in items } │
|
|
│ <div>{ item.name }</div> │
|
|
│ { /s-for } │
|
|
│ </main> │
|
|
│ </template> │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ index.compiler.sts │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ export const title = 'My Page'; │
|
|
│ │
|
|
│ export const items = [ │
|
|
│ { name: 'Item 1' }, │
|
|
│ { name: 'Item 2' }, │
|
|
│ { name: 'Item 3' }, │
|
|
│ ]; │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ index.service.sts │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ // Runtime interactivity (optional) │
|
|
│ const mount = function() { │
|
|
│ document.getElementById('btn') │
|
|
│ .addEventListener('click', handleClick); │
|
|
│ }; │
|
|
│ │
|
|
│ return { mount }; │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Template Syntax
|
|
|
|
### Interpolation
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ SYNTAX: { expression } │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Simple: { title } │
|
|
│ Property: { user.name } │
|
|
│ Nested: { config.api.url } │
|
|
│ │
|
|
│ Note: Single braces, not double {{ }} │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Loop Directive
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ SYNTAX: { s-for item in collection } ... { /s-for } │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Basic: │
|
|
│ { s-for user in users } │
|
|
│ <div>{ user.name }</div> │
|
|
│ { /s-for } │
|
|
│ │
|
|
│ With Index: │
|
|
│ { s-for user, index in users } │
|
|
│ <div>#{ index }: { user.name }</div> │
|
|
│ { /s-for } │
|
|
│ │
|
|
│ Nested: │
|
|
│ { s-for category in categories } │
|
|
│ <h2>{ category.name }</h2> │
|
|
│ { s-for item in category.items } │
|
|
│ <div>{ item.name }</div> │
|
|
│ { /s-for } │
|
|
│ { /s-for } │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Conditional Directives
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ SYNTAX: { s-if } / { s-elif } / { s-else } / { /s-if } │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ Simple If: │
|
|
│ { s-if isLoggedIn } │
|
|
│ <div>Welcome back!</div> │
|
|
│ { /s-if } │
|
|
│ │
|
|
│ If-Else: │
|
|
│ { s-if isAdmin } │
|
|
│ <div>Admin Panel</div> │
|
|
│ { s-else } │
|
|
│ <div>User Dashboard</div> │
|
|
│ { /s-if } │
|
|
│ │
|
|
│ If-Elif-Else: │
|
|
│ { s-if role === 'admin' } │
|
|
│ <div>Admin</div> │
|
|
│ { s-elif role === 'mod' } │
|
|
│ <div>Moderator</div> │
|
|
│ { s-else } │
|
|
│ <div>User</div> │
|
|
│ { /s-if } │
|
|
│ │
|
|
│ Negation: │
|
|
│ { s-if !isLoggedIn } │
|
|
│ <a href="/login">Log In</a> │
|
|
│ { /s-if } │
|
|
│ │
|
|
│ Comparison Operators: │
|
|
│ === == !== != > < >= <= │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Import Hierarchy
|
|
|
|
### Strict Layer Enforcement
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ IMPORT HIERARCHY │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────┐ │
|
|
│ │ .strata │ │
|
|
│ │ (Template) │ │
|
|
│ └──────┬──────┘ │
|
|
│ │ │
|
|
│ │ can import │
|
|
│ ▼ │
|
|
│ ┌─────────────┐ │
|
|
│ │ .strata │ (other templates only) │
|
|
│ └─────────────┘ │
|
|
│ │
|
|
│ ════════════════════════════════════════════════════════════════ │
|
|
│ │
|
|
│ ┌─────────────────┐ │
|
|
│ │ .compiler.sts │ │
|
|
│ │ (Variables) │ │
|
|
│ └────────┬────────┘ │
|
|
│ │ │
|
|
│ │ can import │
|
|
│ ▼ │
|
|
│ ┌──────────────┼──────────────┐ │
|
|
│ │ │ │ │
|
|
│ ▼ ▼ ▼ │
|
|
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
|
|
│ │ .service │ │ .api.sts │ │ .sts │ │
|
|
│ │ .sts │ │ │ │ │ │
|
|
│ └───────────┘ └───────────┘ └───────────┘ │
|
|
│ │
|
|
│ ════════════════════════════════════════════════════════════════ │
|
|
│ │
|
|
│ ┌─────────────────┐ │
|
|
│ │ .service.sts │ │
|
|
│ │ (Logic) │ │
|
|
│ └────────┬────────┘ │
|
|
│ │ │
|
|
│ │ can import │
|
|
│ ▼ │
|
|
│ ┌────────┴────────┐ │
|
|
│ │ │ │
|
|
│ ▼ ▼ │
|
|
│ ┌───────────┐ ┌───────────┐ │
|
|
│ │ .api.sts │ │ .sts │ │
|
|
│ └───────────┘ └───────────┘ │
|
|
│ │
|
|
│ ════════════════════════════════════════════════════════════════ │
|
|
│ │
|
|
│ ┌─────────────────┐ │
|
|
│ │ .api.sts │ │
|
|
│ │ (API Contract) │ │
|
|
│ └────────┬────────┘ │
|
|
│ │ │
|
|
│ │ can import │
|
|
│ ▼ │
|
|
│ ┌───────────┐ │
|
|
│ │ .sts │ │
|
|
│ └───────────┘ │
|
|
│ │
|
|
│ ════════════════════════════════════════════════════════════════ │
|
|
│ │
|
|
│ ┌─────────────────┐ │
|
|
│ │ .sts │ │
|
|
│ │ (Utilities) │ │
|
|
│ └────────┬────────┘ │
|
|
│ │ │
|
|
│ │ can import │
|
|
│ ▼ │
|
|
│ ┌───────────┐ │
|
|
│ │ .sts │ (other utilities only) │
|
|
│ └───────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
|
|
VIOLATION = BUILD ERROR
|
|
```
|
|
|
|
---
|
|
|
|
## Runtime Architecture
|
|
|
|
### Minimal Runtime
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ RUNTIME OUTPUT │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ index.html │
|
|
│ ══════════ │
|
|
│ │
|
|
│ <!DOCTYPE html> │
|
|
│ <html> │
|
|
│ <head> │
|
|
│ <link rel="stylesheet" href="/assets/css/app.css"> │
|
|
│ </head> │
|
|
│ <body> │
|
|
│ <div id="app"></div> │
|
|
│ <script type="module" src="/assets/js/app.js"></script> │
|
|
│ </body> │
|
|
│ </html> │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ app.js │
|
|
│ ══════ │
|
|
│ │
|
|
│ // Pages registry with pre-compiled HTML │
|
|
│ const pages = { │
|
|
│ '/': { │
|
|
│ render() { │
|
|
│ return `<main>...</main>`; // Pure HTML, no framework │
|
|
│ }, │
|
|
│ mount() { │
|
|
│ // Optional: runtime interactivity from .service.sts │
|
|
│ } │
|
|
│ } │
|
|
│ }; │
|
|
│ │
|
|
│ // Simple router │
|
|
│ function mount() { │
|
|
│ const page = pages[location.pathname] || pages['/']; │
|
|
│ document.getElementById('app').innerHTML = page.render(); │
|
|
│ page.mount(); │
|
|
│ } │
|
|
│ │
|
|
│ mount(); │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Dev Server Architecture
|
|
|
|
### Built-in Go Server with HMR
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ strata-compile dev │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌───────────────┐ │
|
|
│ │ File System │ │
|
|
│ └───────┬───────┘ │
|
|
│ │ │
|
|
│ │ fsnotify │
|
|
│ ▼ │
|
|
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
|
|
│ │ Watcher │────▶│ Compiler │────▶│ Dev Server │ │
|
|
│ │ (Go) │ │ (Go) │ │ (Go) │ │
|
|
│ └───────────────┘ └───────────────┘ └───────┬───────┘ │
|
|
│ │ │
|
|
│ ┌────────┴────────┐ │
|
|
│ │ │ │
|
|
│ ▼ ▼ │
|
|
│ ┌──────────┐ ┌──────────┐│
|
|
│ │ HTTP │ │WebSocket ││
|
|
│ │ :3000 │ │ HMR ││
|
|
│ └──────────┘ └──────────┘│
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ WATCH TARGETS: │
|
|
│ │
|
|
│ src/ │
|
|
│ ├── pages/**/*.strata → Recompile page │
|
|
│ ├── pages/**/*.compiler.sts → Recompile page │
|
|
│ ├── pages/**/*.service.sts → Recompile page │
|
|
│ ├── pages/**/*.scss → Hot reload CSS │
|
|
│ ├── components/**/* → Recompile dependents │
|
|
│ └── ... │
|
|
│ │
|
|
│ strataconfig.ts → Full rebuild │
|
|
│ │
|
|
│ ──────────────────────────────────────────────────────────────── │
|
|
│ │
|
|
│ HMR MESSAGES: │
|
|
│ │
|
|
│ { type: "reload" } → Full page reload │
|
|
│ { type: "css", path: "..." } → CSS hot swap │
|
|
│ { type: "component" } → Component reload │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Future: Shared Worker Architecture
|
|
|
|
> **Status: Planned**
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ Strata Shared Worker │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
|
│ │ Tab 1 │ │ Tab 2 │ │ Tab 3 │ │ Tab N │ │
|
|
│ │ tabId:a1 │ │ tabId:b2 │ │ tabId:c3 │ │ tabId:xx │ │
|
|
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
|
|
│ │ │ │ │ │
|
|
│ └─────────────┴──────┬──────┴─────────────┘ │
|
|
│ │ │
|
|
│ ┌────────▼────────┐ │
|
|
│ │ Shared Worker │ │
|
|
│ │ │ │
|
|
│ │ ┌───────────┐ │ │
|
|
│ │ │ Store │ │ ◄── Encrypted State │
|
|
│ │ └───────────┘ │ │
|
|
│ │ ┌───────────┐ │ │
|
|
│ │ │ Cache │ │ ◄── API Response Cache │
|
|
│ │ └───────────┘ │ │
|
|
│ │ ┌───────────┐ │ │
|
|
│ │ │ TabSync │ │ ◄── Tab Registry │
|
|
│ │ └───────────┘ │ │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Tab Management (Planned)
|
|
|
|
```typescript
|
|
// Auto-generated tabId for each browser tab
|
|
const tabId = strata.tabId; // e.g., "tab_a1b2c3"
|
|
|
|
// Tab-specific state
|
|
strata.store.setForTab(tabId, { draft: formData });
|
|
|
|
// Shared state (all tabs)
|
|
strata.store.setShared({ user: currentUser });
|
|
|
|
// Broadcast to specific tabs
|
|
strata.broadcast('logout', { reason: 'session_expired' }, ['tab_a1b2c3']);
|
|
|
|
// Broadcast to all tabs
|
|
strata.broadcast('refresh', { entity: 'users' });
|
|
```
|
|
|
|
---
|
|
|
|
## Future: Smart Fetch System
|
|
|
|
> **Status: Planned**
|
|
|
|
### Request Deduplication
|
|
|
|
```typescript
|
|
// These calls are deduplicated - only ONE request is made
|
|
const [users1, users2, users3] = await Promise.all([
|
|
strata.fetch('/api/users'),
|
|
strata.fetch('/api/users'),
|
|
strata.fetch('/api/users'),
|
|
]);
|
|
// All three resolve with the same data from single request
|
|
```
|
|
|
|
### Caching Strategy
|
|
|
|
```typescript
|
|
strata.fetch('/api/users', {
|
|
cache: 'smart', // Default: cache until data changes
|
|
cache: 'none', // No caching
|
|
cache: '5m', // Cache for 5 minutes
|
|
cache: 'permanent', // Cache until manual invalidation
|
|
|
|
// Stale-while-revalidate pattern
|
|
stale: '1m', // Serve stale for 1 min while fetching fresh
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Future: Encrypted Store
|
|
|
|
> **Status: Planned**
|
|
|
|
### Build-Time Encryption
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ Build Process │
|
|
├─────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ 1. Generate encryption key at build time │
|
|
│ key = crypto.randomBytes(32) │
|
|
│ │
|
|
│ 2. Embed key in compiled runtime (obfuscated) │
|
|
│ const _k = [0x2f, 0xa1, ...]; // Split & scattered │
|
|
│ │
|
|
│ 3. Store data encrypted in SharedWorker │
|
|
│ encrypted = AES256(JSON.stringify(state), key) │
|
|
│ │
|
|
│ 4. Browser can't read state even with DevTools │
|
|
│ localStorage: "encrypted:a1b2c3d4e5f6..." │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Store Definition (Planned)
|
|
|
|
```typescript
|
|
// stores/user.sts
|
|
import { createStore } from 'strata';
|
|
|
|
export const userStore = createStore('user', {
|
|
state: {
|
|
currentUser: null,
|
|
preferences: {},
|
|
token: null,
|
|
},
|
|
|
|
actions: {
|
|
login(user, token) {
|
|
this.currentUser = user;
|
|
this.token = token;
|
|
},
|
|
logout() {
|
|
this.currentUser = null;
|
|
this.token = null;
|
|
},
|
|
},
|
|
|
|
encrypt: true, // Encrypt entire store
|
|
persist: true, // Persist to SharedWorker storage
|
|
shared: true, // Share across all tabs
|
|
});
|
|
```
|
|
|
|
---
|
|
|
|
## Performance Targets
|
|
|
|
| Metric | Target | Typical React |
|
|
|--------|--------|---------------|
|
|
| Build Memory | < 512MB | 8GB+ |
|
|
| Bundle Size | < 50KB | 2MB+ |
|
|
| Runtime | < 5KB | 40KB+ |
|
|
| Cold Start | < 500ms | 3s+ |
|
|
| HMR | < 100ms | 1s+ |
|
|
| TTFB | < 50ms | 200ms+ |
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
strata/
|
|
├── cli/
|
|
│ └── create-strata/ # Project scaffolding
|
|
│ └── index.js
|
|
│
|
|
├── compiler/
|
|
│ ├── cmd/
|
|
│ │ └── strata/ # CLI entry point
|
|
│ │ ├── main.go
|
|
│ │ ├── dev.go
|
|
│ │ └── build.go
|
|
│ │
|
|
│ └── internal/
|
|
│ ├── ast/ # Abstract Syntax Tree
|
|
│ │ └── nodes.go
|
|
│ │
|
|
│ ├── compiler/ # Static compiler
|
|
│ │ └── static.go
|
|
│ │
|
|
│ ├── parser/ # Template parser
|
|
│ │ └── strata.go
|
|
│ │
|
|
│ ├── server/ # Dev server
|
|
│ │ └── dev.go
|
|
│ │
|
|
│ └── watcher/ # File watcher
|
|
│ └── watcher.go
|
|
│
|
|
├── runtime/ # Browser runtime
|
|
│ └── strata.js
|
|
│
|
|
├── templates/ # Project templates
|
|
│ └── default/
|
|
│
|
|
├── examples/ # Example projects
|
|
│ └── pokemon/
|
|
│
|
|
├── Makefile # Build commands
|
|
├── README.md # User documentation
|
|
├── ARCHITECTURE.md # This file
|
|
├── CHANGELOG.md # Version history
|
|
├── CONTRIBUTING.md # Contribution guidelines
|
|
└── LICENSE # Proprietary license
|
|
```
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Strata implements the **STRC Pattern** (Static Template Resolution with Compartmentalized Layers) to achieve:
|
|
|
|
1. **Build-time compilation** of all template syntax
|
|
2. **Zero runtime overhead** in production
|
|
3. **Clear separation** between template, data, and logic
|
|
4. **Strict import hierarchy** preventing layer violations
|
|
5. **Fast development** with Go-powered HMR
|
|
|
|
The result: websites that are as fast as hand-written HTML, with the developer experience of a modern framework.
|
|
|
|
---
|
|
|
|
<p align="center">
|
|
<strong>Strata</strong> - Static Template Rendering Architecture
|
|
</p>
|