strata-compile/README.md

# Strata

**Static Template Rendering Architecture**

Strata is a compile-time web framework that resolves templates to pure HTML at build time. Zero runtime framework overhead. Maximum performance.

```
 ╔═══════════════════════════════════════════════════════╗
 ║   ███████╗████████╗██████╗  █████╗ ████████╗ █████╗   ║
 ║   ██╔════╝╚══██╔══╝██╔══██╗██╔══██╗╚══██╔══╝██╔══██╗  ║
 ║   ███████╗   ██║   ██████╔╝███████║   ██║   ███████║  ║
 ║   ╚════██║   ██║   ██╔══██╗██╔══██║   ██║   ██╔══██║  ║
 ║   ███████║   ██║   ██║  ██║██║  ██║   ██║   ██║  ██║  ║
 ║   ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝   ╚═╝  ╚═╝  ║
 ╚═══════════════════════════════════════════════════════╝
```

---

## Table of Contents

- [Philosophy](#philosophy)
- [Design Pattern: STRC](#design-pattern-strc)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Commands](#cli-commands)
- [Project Structure](#project-structure)
- [File Types](#file-types)
- [Template Syntax](#template-syntax)
- [Examples](#examples)
- [Import Hierarchy](#import-hierarchy)
- [Development](#development)
- [License](#license)

---

## Philosophy

Strata follows three core principles:

1. **Compile-Time Resolution**: All template logic is resolved during build, not at runtime
2. **Zero Runtime Overhead**: Output is pure HTML/CSS/JS with no framework dependencies
3. **Strict Separation of Concerns**: Each file type has a single responsibility

---

## Design Pattern: STRC

Strata implements the **STRC Pattern** (Static Template Resolution with Compartmentalized Layers):

```
┌─────────────────────────────────────────────────────────────┐
│                      BUILD TIME                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │   .strata    │◄───│ .compiler.sts│◄───│ .service.sts │   │
│  │  (Template)  │    │  (Variables) │    │   (Logic)    │   │
│  └──────────────┘    └──────────────┘    └──────────────┘   │
│         │                   │                   │           │
│         │                   │                   │           │
│         ▼                   ▼                   ▼           │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              STATIC COMPILER                        │    │
│  │   Resolves all variables, loops, and conditionals   │    │
│  └─────────────────────────────────────────────────────┘    │
│                           │                                 │
└───────────────────────────┼─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                      RUNTIME                                │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    PURE HTML                        │    │
│  │         No Strata syntax, no framework code         │    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### STRC Layer Responsibilities

| Layer | File Extension | Purpose | Execution |
|-------|---------------|---------|-----------|
| **Template** | `.strata` | HTML structure with directives | Build time |
| **Compiler** | `.compiler.sts` | Variable definitions, data | Build time |
| **Service** | `.service.sts` | Business logic, API calls | Build time* |
| **Runtime** | `.service.sts` | Optional browser interactivity | Runtime |

*Services can define both build-time data fetching and optional runtime interactivity.

---

## Installation

### Prerequisites

- Go 1.21+ (for building the compiler)
- Node.js 18+ (for project scaffolding)

### Install Strata CLI

```bash
# Clone the repository
git clone https://github.com/CarGDev/strata.git
cd strata

# Build the compiler
make build

# Install globally
make install
```

This installs:
- `strata` - The main CLI compiler
- `create-strata` - Project scaffolding tool

---

## Quick Start

### Create a New Project

```bash
# Create a new Strata project
npx create-strata-compile my-app

# Navigate to project
cd my-app

# Install dependencies
npm install

# Start development server
npm run dev
```

Open http://localhost:3000 to see your app.

### Build for Production

```bash
npm run build
```

Output is in the `dist/` folder - pure static HTML ready for any hosting.

---

## CLI Commands

### Main CLI (`strata`)

```bash
# Development server with HMR
strata-compile dev [--port 3000] [--open]

# Production build
strata-compile build [--output dist]

# Preview production build
strata-compile preview [--port 4000]
```

### Generator Commands

Generate new files with the correct structure:

```bash
# Generate a component
strata-compile gcomponent Button
# Creates: src/components/Button/
#   ├── Button.strata
#   ├── Button.compiler.sts
#   ├── Button.service.sts
#   └── Button.scss

# Generate a page
strata-compile gpage about
# Creates: src/pages/about/
#   ├── about.strata
#   ├── about.compiler.sts
#   ├── about.service.sts
#   └── about.scss

# Generate a service
strata-compile gservice auth
# Creates: src/services/auth.service.sts

# Generate an API contract
strata-compile gapi users
# Creates: src/api/users.api.sts

# Generate a utility
strata-compile gutil format
# Creates: src/utils/format.sts

# Generate a store
strata-compile gstore cart
# Creates: src/stores/cart.store.sts
```

### Shorthand Commands

```bash
strata-compile gc Button    # component
strata-compile gp about     # page
strata-compile gs auth      # service
strata-compile ga users     # api
strata-compile gu format    # util
```

---

## Project Structure

```
my-app/
├── src/
│   ├── components/          # Reusable UI components
│   │   └── Button/
│   │       ├── Button.strata
│   │       ├── Button.compiler.sts
│   │       ├── Button.service.sts
│   │       └── Button.scss
│   │
│   ├── pages/               # Route-based pages
│   │   ├── index/
│   │   │   ├── index.strata
│   │   │   ├── index.compiler.sts
│   │   │   ├── index.service.sts
│   │   │   └── index.scss
│   │   └── about/
│   │       └── ...
│   │
│   ├── services/            # Business logic
│   │   └── auth.service.sts
│   │
│   ├── api/                 # API contracts
│   │   └── users.api.sts
│   │
│   ├── stores/              # State management
│   │   └── cart.store.sts
│   │
│   ├── utils/               # Pure utilities
│   │   └── format.sts
│   │
│   └── assets/
│       └── styles/
│           ├── _variables.scss
│           └── global.scss
│
├── public/                  # Static assets (copied as-is)
├── dist/                    # Build output
├── strataconfig.ts          # Project configuration
└── package.json
```

---

## File Types

### `.strata` - Template Files

Pure HTML structure with Strata directives. No logic, no JavaScript.

```html
<template>
  <main class="page">
    <h1>{ title }</h1>
    <p>{ description }</p>
  </main>
</template>
```

**Rules:**
- Must contain a single `<template>` root
- Can only import other `.strata` files
- Cannot contain `<script>` tags
- All variables come from `.compiler.sts`

### `.compiler.sts` - Compiler Files

Defines variables available to the template. Executed at **build time**.

```typescript
// page.compiler.sts
export const title = 'My Page';
export const description = 'Welcome to my page';

// Arrays for loops
export const items = [
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' },
];

// Booleans for conditionals
export const isProduction = false;
export const showBanner = true;
```

**Rules:**
- All exports become template variables
- Can import from `.service.sts`, `.api.sts`, `.sts`
- Cannot import from `.strata` files
- Runs during compilation, not in browser

### `.service.sts` - Service Files

Business logic layer. Can define both build-time and runtime behavior.

```typescript
// auth.service.sts

// Build-time: fetch data during compilation
export async function fetchUserData() {
  const response = await fetch('https://api.example.com/user');
  return response.json();
}

// Runtime: browser interactivity (optional)
const mount = function() {
  document.getElementById('btn').addEventListener('click', () => {
    console.log('Clicked!');
  });
};

return { mount };
```

**Rules:**
- Can import from `.api.sts`, `.sts`
- Cannot import from `.strata`, `.compiler.sts`

### `.api.sts` - API Contract Files

Declarative API endpoint definitions.

```typescript
// users.api.sts
export const endpoints = {
  getUsers: {
    method: 'GET',
    url: '/api/users',
    cache: 3600
  },
  createUser: {
    method: 'POST',
    url: '/api/users',
    body: { name: 'string', email: 'string' }
  }
};
```

### `.sts` - Utility Files

Pure functions with no side effects. Can be imported anywhere.

```typescript
// format.sts
export function formatDate(date) {
  return new Date(date).toLocaleDateString();
}

export function capitalize(str) {
  return str.charAt(0).toUpperCase() + str.slice(1);
}
```

### `.scss` - Style Files

Scoped styles for components/pages. Standard SCSS syntax.

```scss
// Button.scss
.button {
  padding: 0.5rem 1rem;
  border-radius: 4px;

  &:hover {
    opacity: 0.9;
  }
}
```

---

## Template Syntax

### Variable Interpolation

```html
{ variableName }
```

Variables are defined in the corresponding `.compiler.sts` file.

```html
<!-- page.strata -->
<h1>{ title }</h1>
<p>Author: { author.name }</p>
```

```typescript
// page.compiler.sts
export const title = 'Hello World';
export const author = { name: 'John Doe' };
```

**Output:**
```html
<h1>Hello World</h1>
<p>Author: John Doe</p>
```

### Loops: `s-for`

```html
{ s-for item in items }
  <!-- content repeated for each item -->
{ /s-for }
```

**With index:**
```html
{ s-for item, index in items }
  <div>#{ index }: { item.name }</div>
{ /s-for }
```

**Example:**
```html
<!-- page.strata -->
<ul>
  { s-for user in users }
    <li>{ user.name } - { user.email }</li>
  { /s-for }
</ul>
```

```typescript
// page.compiler.sts
export const users = [
  { name: 'Alice', email: 'alice@example.com' },
  { name: 'Bob', email: 'bob@example.com' },
];
```

**Output:**
```html
<ul>
  <li>Alice - alice@example.com</li>
  <li>Bob - bob@example.com</li>
</ul>
```

### Conditionals: `s-if` / `s-elif` / `s-else`

```html
{ s-if condition }
  <!-- shown if condition is true -->
{ s-elif otherCondition }
  <!-- shown if otherCondition is true -->
{ s-else }
  <!-- shown if all conditions are false -->
{ /s-if }
```

**Example:**
```html
{ s-if isAdmin }
  <div class="admin-panel">Admin Controls</div>
{ s-elif isModerator }
  <div class="mod-panel">Moderator Controls</div>
{ s-else }
  <div class="user-panel">User Dashboard</div>
{ /s-if }
```

```typescript
// page.compiler.sts
export const isAdmin = false;
export const isModerator = true;
```

**Output:**
```html
<div class="mod-panel">Moderator Controls</div>
```

### Negation

```html
{ s-if !isLoggedIn }
  <a href="/login">Please log in</a>
{ /s-if }
```

### Comparison Operators

```html
{ s-if count > 0 }
  <p>You have { count } items</p>
{ /s-if }

{ s-if status === 'active' }
  <span class="badge">Active</span>
{ /s-if }
```

Supported operators: `===`, `==`, `!==`, `!=`, `>`, `<`, `>=`, `<=`

### Component Imports (Coming Soon)

```html
{ s-imp "@components/Button" }
```

---

## Examples

### Basic Page

```html
<!-- src/pages/index/index.strata -->
<template>
  <main class="home">
    <h1>{ title }</h1>
    <p>{ subtitle }</p>

    <section class="features">
      { s-for feature in features }
        <div class="feature-card">
          <span>{ feature.icon }</span>
          <h3>{ feature.name }</h3>
          <p>{ feature.description }</p>
        </div>
      { /s-for }
    </section>

    { s-if showCTA }
      <a href="/signup" class="cta">Get Started</a>
    { /s-if }
  </main>
</template>
```

```typescript
// src/pages/index/index.compiler.sts
export const title = 'Welcome to My App';
export const subtitle = 'Build faster, deploy smarter';
export const showCTA = true;

export const features = [
  { icon: '⚡', name: 'Fast', description: 'Blazing fast performance' },
  { icon: '🔒', name: 'Secure', description: 'Built-in security' },
  { icon: '📦', name: 'Simple', description: 'Easy to use' },
];
```

### Page with Runtime Interactivity

```html
<!-- src/pages/counter/counter.strata -->
<template>
  <main class="counter-page">
    <h1>Counter Example</h1>
    <button id="counterBtn">Click Me</button>
    <p>Count: <span id="count">0</span></p>
  </main>
</template>
```

```typescript
// src/pages/counter/counter.service.sts
const mount = function() {
  const btn = document.getElementById('counterBtn');
  const countEl = document.getElementById('count');
  let count = 0;

  btn.addEventListener('click', function() {
    count++;
    countEl.textContent = count;
  });
};

return { mount };
```

### Build-Time Data Fetching

```typescript
// src/pages/pokemon/pokemon.compiler.sts
export const title = 'Pokemon Gallery';

// This data is fetched at BUILD TIME, not runtime
export const pokemons = [
  { id: 1, name: 'Bulbasaur', type: 'grass' },
  { id: 4, name: 'Charmander', type: 'fire' },
  { id: 7, name: 'Squirtle', type: 'water' },
];

export const totalCount = pokemons.length;
```

```html
<!-- src/pages/pokemon/pokemon.strata -->
<template>
  <main class="pokemon-page">
    <h1>{ title }</h1>
    <p>Showing { totalCount } Pokemon</p>

    <div class="grid">
      { s-for pokemon in pokemons }
        <div class="card">
          <h3>{ pokemon.name }</h3>
          <span class="type">{ pokemon.type }</span>
        </div>
      { /s-for }
    </div>
  </main>
</template>
```

---

## Import Hierarchy

Strata enforces a strict import hierarchy to maintain separation of concerns:

```
┌─────────────┐
│   .strata   │  Can only import: .strata
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│ .compiler.sts   │  Can import: .service.sts, .api.sts, .sts
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  .service.sts   │  Can import: .api.sts, .sts
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│    .api.sts     │  Can import: .sts
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│      .sts       │  Can import: .sts only
└─────────────────┘
```

**Violations will cause build errors.**

---

## Development

### Running Tests

```bash
make test
```

### Building from Source

```bash
# Build compiler
make build

# Build and install
make install

# Clean build artifacts
make clean
```

### Project Configuration

```typescript
// strataconfig.ts
export default {
  // Development server port
  port: 3000,

  // API proxy for development
  api: {
    baseUrl: 'http://localhost:8080',
    proxy: true
  },

  // Build output directory
  output: 'dist',

  // Enable source maps in development
  sourceMaps: true
};
```

---

## License

**Proprietary - All Rights Reserved**

This software is currently in development and is not available for public use, modification, or distribution. See [LICENSE](LICENSE) for details.

---

## Links

- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
- [Report Issues](https://github.com/CarGDev/strata/issues)

---

<p align="center">
  <strong>Strata</strong> - Code Faster. Load Quick. Deploy ASAP.
</p>