Zyra

README

⚡ Zyra Framework

Unified Fullstack Web Framework Unifying Native Go Performance & React/TypeScript DX

---

📑 Table of Contents

1. Overview & PRD
2. System Architecture & Data Flow
3. Core Features
4. Framework Comparison
5. Quick Start
6. Go Action RPC Bridge
7. Database Integrations
8. Starter Templates
9. Middleware & Security Hardening
10. Single-Binary Production Deployment
11. CLI Commands Reference
12. Documentation & GitHub Pages

---

1. Overview & PRD

Zyra is a next-generation fullstack web framework engineered to bridge Go 1.22+ backend execution with React 18 & TypeScript client DX into a unified, single-binary application.

Instead of writing separate Go API controllers, managing OpenAPI specs, configuring CORS, and maintaining duplicate TypeScript interfaces, Zyra lets you write native Go functions annotated with // +zyraaction. Zyra automatically parses the Go AST and generates type-safe TypeScript client bindings.

PRD — Project Requirements Document & System Flow
─────────────────────────────────────────────────────────────────────────────
1. Overview     : Unified Go + React runtime with zero API boilerplate.
2. Architecture : Bun-powered SSR worker pool + Go net/http high-speed engine.
3. RPC Bridge   : AST Go functions scanned -> type-safe TS client generated.
4. Deployment   : Single compiled binary with embedded static & SSR assets.

---

2. System Architecture & Data Flow

┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                                   ZYRA UNIFIED ENGINE                                    │
│                                                                                          │
│   Browser Request         ┌───────────────────────────────┐                              │
│  ───────────────►         │        Go HTTP Server         │                              │
│                           │   - net/http High-Speed Router│                              │
│   SSR HTML Output         │   - Security Headers & CSRF   │                              │
│  ◄───────────────         │   - In-Memory SSR Page Cache  │                              │
│                           └───────────────┬───────────────┘                              │
│                                           │                                              │
│                        Fast JSON IPC      │      Bun SSR Worker Thread Pool              │
│                        ───────────────────┼────────────────────────┐                     │
│                                           ▼                        ▼                     │
│                           ┌───────────────────────────────┐ ┌──────────────────────────┐ │
│                           │      Bun Worker Subprocess    │ │  Go Action AST Generator │ │
│                           │  - React renderToString()     │ │  - Scans // +zyraaction  │ │
│                           │  - Dynamic HTML Shell Inject  │ │  - Output: .generated/   │ │
│                           └───────────────────────────────┘ └──────────────────────────┘ │
│                                                                                          │
│   Type-Safe RPC Call                                                                     │
│  ───────────────────►     Go Backend Logic ───► Database (Postgres / MySQL / SQLite /    │
│                           (actions/*.go)        MongoDB / Firebase / Supabase)           │
└──────────────────────────────────────────────────────────────────────────────────────────┘

---

3. Core Features

• ⚡ Go Action RPC Bridge — Annotate Go functions with // +zyraaction for instant, type-safe TypeScript client RPC calls.
• 🚀 Sub-Millisecond SSR Engine — Bun worker thread pool handles React renderToString via JSON IPC.
• 💾 In-Memory Page Cache — Configurable SSR page cache skips worker rendering for static/cached routes.
• 🛡️ Bank-Grade Security Hardening — Pre-configured security headers (X-Frame-Options, X-Content-Type-Options, Referrer-Policy) & token bucket IP rate limiting.
• 🎨 Tailwind CSS v4 Integration — Zero-config styling compiler with instant hot stylesheet reloads.
• 📊 6 Production Starter Templates — Interactive Demo, SaaS Admin Dashboard, SaaS Landing Page, E-Commerce Storefront, AI Chat Copilot, and Blank Minimal.
• 🗄️ 6 Database Integrations — PostgreSQL, MySQL, SQLite, MongoDB, Firebase/Firestore, and Supabase.
• 📦 Single-Binary Deployment — Packaged into one standalone executable via //go:embed. Zero Node.js runtime required in production.

---

4. Framework Comparison

Feature	Zyra	Next.js	Wails	Templ + HTMX
Backend Runtime	Go 1.22+	Node.js / Vercel	Go 1.22+	Go 1.22+
Frontend UI	React 18 / TSX	React 18 / TSX	React / Svelte / Vue	Server HTML (HTMX)
RPC Bridge	Auto AST Generated	Server Actions (JS)	Auto Generated	N/A
Production Binary	Single Executable	Node Server / Edge	Desktop App (.exe/.dmg)	Single Executable
RAM Footprint	~15 MB	~150 MB+	~80 MB	~10 MB

---

5. Quick Start

Installation

# Linux & macOS
curl -fsSL https://raw.githubusercontent.com/LythianOlyx/Zyra/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/LythianOlyx/Zyra/main/install.ps1 | iex

Create Project

zyra create my-app

Start Dev Server

cd my-app
zyra dev

Your app will be live at http://localhost:3000 with hot reload enabled.

---

6. Go Action RPC Bridge

Go Server Action (actions/user.go)

package actions

import "context"

type UserProfile struct {
	ID       string `json:"id"`
	Username string `json:"username"`
	IsAdmin  bool   `json:"isAdmin"`
}

// +zyraaction
func GetUserProfile(ctx context.Context, userID string) (*UserProfile, error) {
	return &UserProfile{
		ID:       userID,
		Username: "alex_dev",
		IsAdmin:  true,
	}, nil
}

React Client Component (pages/profile.tsx)

import React, { useState, useEffect } from "react";
import { hydrate } from "../runtime/client";
import { GetUserProfile } from "../.generated/actions/actions";

export default function ProfilePage() {
  const [user, setUser] = useState(null);

  useEffect(() => {
    GetUserProfile("usr_100").then(setUser);
  }, []);

  return (
    <main className="min-h-screen bg-slate-950 text-white p-8">
      <h1 className="text-2xl font-bold">Welcome, {user?.username}</h1>
    </main>
  );
}

if (typeof window !== "undefined") {
  hydrate(ProfilePage);
}

---

7. Database Integrations

Zyra provides instant database configurations during zyra create:

• PostgreSQL — GORM / sqlx / lib/pq
• MySQL / MariaDB — GORM / sqlx / go-sql-driver
• SQLite — GORM / sqlx / go-sqlite3
• 🍃 MongoDB — go.mongodb.org/mongo-driver
• 🔥 Firebase / Cloud Firestore — firebase.google.com/go/v4
• ⚡ Supabase — PostgreSQL Cloud

---

8. Starter Templates

When running zyra create, select from 6 starter templates:

1. ⚡ Interactive Go RPC Playground — Latency monitor & RPC action tester
2. 📊 SaaS Admin Dashboard — Stats grid, sidebar, chart & action tester
3. 🚀 SaaS Landing Page — Hero section, feature grid & waitlist form
4. 🛒 E-Commerce Storefront — Product grid, filter pills & RPC checkout cart
5. 🤖 AI Chat Copilot — ChatGPT-style interface with real-time stream simulation
6. 📄 Blank Minimal Project — Clean canvas for custom applications

---

9. Middleware & Security Hardening

Zyra includes built-in Go middleware for production security:

server.Use(server.SecurityHeadersMiddleware())
server.Use(server.RateLimitMiddleware(30, 100)) // 30 req/s, 100 burst

---

10. Single-Binary Production Deployment

Compile frontend assets, SSR bundles, and Go server into one binary:

zyra build

The output standalone binary is created at dist/zyra-server. Run it directly without Node.js:

PORT=8080 ./dist/zyra-server

---

11. CLI Commands Reference

Command	Description
zyra create [name]	Launches interactive prompt to scaffold a new Zyra project
zyra dev	Starts development server with watcher and WebSocket HMR
zyra build	Bundles static assets and compiles single production binary
zyra generate	Scans actions and pages to regenerate TypeScript definitions
zyra upgrade	Upgrades Zyra CLI binary and active project runtime

---

12. Documentation & GitHub Pages

Visit the official interactive documentation site: 👉 https://lythianolyx.github.io/Zyra

---

Built with ⚡ by LythianOlyx & Zyra Contributors