# 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: │ │ ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ │ └─ 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
→ Output tag + recurse │ │ │ │ • TextNode → Output as-is │ │ │ │ │ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ ──────────────────────────────────────────────────────────────── │ │ │ │ STEP 4: OUTPUT │ │ ══════════════ │ │ │ │ Result: │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │

Hello

│ │ │ │
Item 1
│ │ │ │
Item 2
│ │ │ │
Item 3
│ │ │ └──────────────────────────────────────────────────────────────┘ │ │ │ │ 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 │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────────┐ │ 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 } │ │
{ user.name }
│ │ { /s-for } │ │ │ │ With Index: │ │ { s-for user, index in users } │ │
#{ index }: { user.name }
│ │ { /s-for } │ │ │ │ Nested: │ │ { s-for category in categories } │ │

{ category.name }

│ │ { s-for item in category.items } │ │
{ item.name }
│ │ { /s-for } │ │ { /s-for } │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### Conditional Directives ``` ┌─────────────────────────────────────────────────────────────────────┐ │ SYNTAX: { s-if } / { s-elif } / { s-else } / { /s-if } │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Simple If: │ │ { s-if isLoggedIn } │ │
Welcome back!
│ │ { /s-if } │ │ │ │ If-Else: │ │ { s-if isAdmin } │ │
Admin Panel
│ │ { s-else } │ │
User Dashboard
│ │ { /s-if } │ │ │ │ If-Elif-Else: │ │ { s-if role === 'admin' } │ │
Admin
│ │ { s-elif role === 'mod' } │ │
Moderator
│ │ { s-else } │ │
User
│ │ { /s-if } │ │ │ │ Negation: │ │ { s-if !isLoggedIn } │ │ Log In │ │ { /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 │ │ ══════════ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │ │ ──────────────────────────────────────────────────────────────── │ │ │ │ app.js │ │ ══════ │ │ │ │ // Pages registry with pre-compiled HTML │ │ const pages = { │ │ '/': { │ │ render() { │ │ return `
...
`; // 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. ---

Strata - Static Template Rendering Architecture