Architecture RFC-001 • Python-First Fullstack

Modern Python-First Fullstack & Native 3D Spatial Canvas

ZetaGo-Aurum Unified Web Framework. Industrial ASGI speed, declarative async ORM, and Three.js 360° photogrammetry background, compiled with genuine Next.js script chunks.

$npm create zau@latest
$pip install zau-framework
Python ASGI Core

Starlette-backed event loop with type-safe async RPC procedures.

3D Spatial Canvas

WebGL photogrammetry ingestion with interactive raycast anchors.

Chunked Runtime

Modular Next.js script splitting with zero monolithic HTML output.

Dual Styling

Tailwind CSS utility engine combined with Bootstrap icons.

RoomViewer.zau
Single-File Component fusing TypeScript, 3D Canvas, and Reactive Signals
<template>
  <div class="relative w-full h-[650px] rounded-3xl overflow-hidden glass-panel border border-amber-500/20">
    <!-- Native 3D Spatial Canvas with Hallwyl Museum 360 Room -->
    <ZAU.Canvas3D 
      src="/model/3d/the_great_drawing_room/scene_web.gltf"
      exposure={1.3}
      toneMapping="ACESFilmic"
      autoRotate={isRotating}
      fov={55}
    >
      <ZAU.PointLight position={[0, 3.5, 0]} color="#ffb74d" intensity={3.2} />
      <ZAU.DirectionalLight position={[8, 6, 4]} color="#fff9e6" intensity={2.0} />
      <ZAU.Hotspot id="piano" position={[-1.8, -0.6, -2.2]} label="Bechstein Grand" @select="inspectPiano" />
    </ZAU.Canvas3D>

    <!-- Glassmorphic UI HUD Overlaid Directly on 3D Stream -->
    <div class="absolute top-6 left-6 p-4 rounded-2xl glass-panel-glow max-w-sm">
      <div class="flex items-center space-x-2 text-xs font-mono text-amber-400">
        <i class="bi bi-compass-fill"></i>
        <span>360° SPATIAL HUD</span>
      </div>
      <h3 class="text-base font-bold text-white mt-1">{{ roomTitle }}</h3>
      <button @click="toggleRotation" class="mt-3 px-4 py-1.5 rounded-xl bg-amber-500 text-zinc-950 font-bold text-xs">
        <i class="bi bi-arrow-repeat mr-1"></i> Toggle Spin
      </button>
    </div>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from 'zau-framework';

export default defineComponent({
  setup() {
    const isRotating = ref(true);
    const roomTitle = ref("The Great Drawing Room");

    const toggleRotation = () => {
      isRotating.value = !isRotating.value;
    };

    const inspectPiano = async (node: any) => {
      console.log("Inspecting 3D Audio Node:", node);
    };

    return { isRotating, roomTitle, toggleRotation, inspectPiano };
  }
});
</script>

<style scoped>
.glass-panel-glow {
  backdrop-filter: blur(20px);
  border: 1px solid rgba(245, 158, 11, 0.3);
}
</style>
Documentation Language:English (Default)

RFC-001 Unified Architecture Specification

Enterprise Python-First ASGI Core with Modular Client Code Splitting

LAYER 01

Python ASGI Kernel

Powered by Starlette and Uvicorn. Implements asynchronous Server Action RPC, dependency injection, and zero-boilerplate JSON serialization.

  • Starlette / FastAPI-grade throughput
  • Async WebSocket multi-client sync
  • Declarative dependency injection
LAYER 02

Next.js Client Chunking

Client scripts are automatically divided into modular chunks (webpack, main-app, runtime). View-source displays authentic clean script tags.

  • /_next/static/chunks/ bundling
  • Zero monolithic HTML clutter
  • Dynamic hydration & module preload
LAYER 03

3D Spatial Pipeline

Native ingestion for model/3d/ GLTF, OBJ, and binary buffers with Dual-Tier Progressive LOD and Android GPU memory safety.

  • • Three.js r160 WebGL engine
  • Instant Frame 0 paint (664 KB Draco)
  • 8K Desktop / 4K Mobile auto-tiering
Quickstart & Installation Tutorial

Project Installation & Initialization Guide

# 1. Interactive project scaffolding via npm
npm create zau@latest my-app

# 2. Enter project directory & activate Python virtual environment
cd my-app
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venvScriptsactivate

# 3. Install dependencies & start the development server
pip install -r requirements.txt
npm install
zau dev --port 8000
Built-In Template Architectures (4 Official Options):
fullstack-3dFlagship

Python ASGI + 3D Spatial Three.js + Async ORM + Tailwind/Bootstrap.

  • WebGL Three.js r160
  • Draco Mesh LOD
  • Starlette/uvloop
  • ZAU DB Studio
minimalUltra-Lean

Lightweight Python Starlette core + Single-File Component with zero 3D overhead.

  • Zero overhead
  • Fast cold start
  • REST/RPC Ready
  • Tailwind Atomic
dashboardEnterprise

Operational analytics control panel, real-time metrics cards, and database integration.

  • Chart telemetry
  • Data table grid
  • Session security
  • Auto migrations
portfolioLuxury Atelier

High-end 3D spatial showcase with cinematic camera orbits and Seated POV.

  • 3D Room Showcase
  • Seated POV Mode
  • PBR Lighting
  • Audio Ambience

Python ASGI Engine & RPC Actions

Type-Safe Communication Between Python Backend and Client Viewports

ZAU eliminates the traditional gap between backend APIs and frontend client components. Using the @app.action decorator, any asynchronous Python function is exposed as an end-to-end type-safe RPC procedure.

Backend Implementation (main.py)
from zau import ZAUApp

app = ZAUApp()

@app.action("analytics.track")
async def track_viewpoint(coords: list[float]):
    # Type-safe execution directly from client
    await app.db.execute(
        "INSERT INTO telemetry (camera_x, camera_y, camera_z) VALUES (?, ?, ?)",
        coords
    )
    return {"status": "recorded", "origin": "web_client"}
Client Dispatch (zau.client.ts)
import { createClient } from 'zau-framework';

const client = createClient();

// Invokes the Python backend action over ASGI RPC
const result = await client.actions.call('analytics.track', [
  -1.24, 1.18, 1.45
]);

console.log('Telemetry ACK:', result.status);

Declarative Async ORM & State Signals

High-Speed Persistence Layer Supporting SQLite, PostgreSQL, and In-Memory Drivers

Database models in ZAU are declared with pure Python dataclasses and Pydantic v2 schemas. Migrations are calculated atomically and executed with zero application downtime.

from zau.orm import Model, Field

class SpatialHotspot(Model):
    __tablename__ = "spatial_hotspots"

    id: str = Field(primary_key=True)
    title: str = Field(index=True)
    category: str
    coords_x: float
    coords_y: float
    coords_z: float
    is_active: bool = Field(default=True)

3D Spatial Canvas & Dual-Tier Progressive LOD

Photogrammetry Ingestion with Zero Blackscreen and Android GPU Memory Safety

The ZAU 3D Spatial Engine resolves two fundamental limitations of WebGL web rendering: first-frame blackscreen latency and mobile GPU memory exhaustion. Rather than forcing clients to wait for multi-megabyte 8K geometry, ZAU renders an ultra-compact Draco low-poly mesh on Frame 0, then background-streams high-poly geometry tailored to the client GPU memory tier.

TIER 0: FRAME 0

Instant Low-Poly Paint

664 KB Draco mesh decodes in < 20ms. The 3D chamber is immediately visible and interactive before high-res assets finish downloading.

TIER 1A: ANDROID / MOBILE

4K GPU Memory Guard

6.67 MB total package with 4096px texture ceiling. Conserves ~270 MB VRAM, preventing mobile browser crashes, GC stalls, and frame stutter.

TIER 1B: DESKTOP MASTER

8K PBR Master Render

Full 8192x8192 photogrammetry resolution with 16x anisotropic filtering and ACES Filmic tone mapping for workstation GPUs.

CAMERA ANCHOR

Seated Viewpoint Pivot

Seated coordinates (-0.885, 1.15, 2.25) with target (-0.885, 0.70, 1.08), 70° FOV, and orbit clamping to prevent clipping through walls.

.zau Language Ecosystem & Universal Tooling

Industry Standards: LSP 3.17, Multi-Editor Grammars, Browser Runtime, IANA Media Type, GitHub Linguist

The .zau file format is a modern Single File Component (SFC) uniting 3D spatial WebGL viewport declarations, Python/TypeScript signal reactivity, and scoped styling into a cohesive, high-performance architectural standard.

ChamberExperience.zau
<template>
  <div class="viewport-wrapper">
    <zau-canvas id="salt-tower-viewport" shadows>
      <!-- Declarative 3D Camera Configuration with Orbit Controls -->
      <zau-camera
        :position="[-0.885, 1.15, 2.25]"
        :target="[-0.885, 0.70, 1.08]"
        :fov="70"
      />
      <zau-light type="ambient" :intensity="1.25" />
      <zau-light type="directional" :position="[2, 6, -2]" :intensity="1.0" />
      <zau-model
        src="/model/3d/salt_tower/salt_tower_8k.glb"
        progressiveLOD="true"
        tier="auto"
        @load="onModelLoaded"
      />
      <!-- OrbitControls with anti-wall collision clamping: maxDistance 2.2m -->
      <zau-orbit-controls
        :target="[-0.885, 0.70, 1.08]"
        :maxDistance="2.2"
        :minDistance="0.15"
        :maxPolarAngle="1.69"
        enableDamping="true"
        :dampingFactor="0.05"
      />
    </zau-canvas>

    <div class="hud-overlay">
      <h1>{{ chamberTitle }}</h1>
      <button @click="toggleAutoRotate">Toggle Orbit</button>
    </div>
  </div>
</template>

<script lang="ts">
import { signal } from 'zau-framework';

export default {
  setup() {
    const chamberTitle = signal('Tower of London - Salt Tower');
    const isRotating = signal(true);

    function onModelLoaded() {
      console.log('8K photogrammetry model refined successfully.');
    }

    function toggleAutoRotate() {
      isRotating.value = !isRotating.value;
    }

    return { chamberTitle, isRotating, onModelLoaded, toggleAutoRotate };
  }
};
</script>

<style scoped>
.viewport-wrapper { position: relative; width: 100vw; height: 100vh; background: #0a0b10; }
.hud-overlay { position: absolute; top: 2rem; left: 2rem; z-index: 10; }
</style>

Multi-Editor Support & Universal LSP (zau-lsp)

Select your code editor to view industry-standard configuration:

The official Zau Language extension is packaged in standard .vsix format for Visual Studio Code, Cursor, and Open VSX (VSCodium, Eclipse Theia).

# 1. Install extension from VSIX binary package
code --install-extension dist/extensions/zau-1.0.5.vsix

# 2. Or install via Open-VSX (VSCodium)
codium --install-extension dist/extensions/zau-1.0.5.vsix
  • Features: Semantic Tokens, Tag Autocomplete, Diagnostics, Formatter, Hover Cards
  • • Scope: source.zau | File Extension: .zau

Browser Support & Cross-Platform Runtime

Client-side execution of .zau components with zero complex build overhead:

1. In-Browser Autoloader (<script type="text/zau">)

The /js/zau-browser.js script automatically scans the DOM and mounts all 3D spatial scenes:

<script src="/js/zau-browser.js"></script>
<script type="text/zau">
  <template>
    <zau-canvas id="view">
      <zau-model src="/model/3d/salt_tower/salt_tower_8k.glb" />
    </zau-canvas>
  </template>
</script>
2. Web Syntax Highlighters (Prism.js & Monaco)

Instant integration for interactive syntax coloring in documentation pages or online playgrounds:

// Prism.js
import './public/js/prism-zau.js';
Prism.highlight(code, Prism.languages.zau, 'zau');

// Monaco Editor
import { register } from './public/js/monaco-zau.js';
register(monaco);

Global Standardization, IANA Media Type & GitHub Linguist

Official registration blueprints ensuring the .zau extension is recognized by operating systems, web servers, and global repositories:

Standard / RegistryFormat IdentifierBlueprint File Location
IANA Media Types (RFC 6838)text/prs.zau | application/prs.zauiana/media-type-text-prs-zau.txt
Linux (FreeDesktop.org)text/prs.zau (*.zau glob)mime/linux/zau.xml
Windows RegistryHKEY_CLASSES_ROOT\.zaumime/windows/zau.reg
macOS LaunchServices (UTI)com.zetagoaurum.zaumime/macos/Info.plist
Web Servers (Nginx & Apache)AddType text/prs.zau .zaumime/nginx/zau.conf & .htaccess
GitHub Linguisttm_scope: source.zau (ID: 899321)linguist/languages.yml

Dual-Asset Styling Engine

Tailwind CSS Utility Classes Combined with Bootstrap 5.3 Iconography

Tailwind CSS 3.4+

Atomic utility-first styling with hardware-accelerated backdrop blur, glassmorphism tokens, and responsive breakpoints.

Bootstrap 5.3 Iconography

2,000+ vector SVG icons bundled cleanly via font-face, providing crisp iconography without inflating JS bundle weight.

Production Multi-Cloud Deployment

Native Blueprints for Vercel, Docker, Linux VPS, Render, and Fly.io

Vercel Edge + Serverless Python ASGI Architecture

Static frontend & 3D assets are served directly from Vercel Global CDN. The /api/* endpoints are handled by Python ASGI Serverless Functions (api/index.py) with zero cold-start.

View Live Production
1. vercel.json (Edge Rewrites)
{
  "framework": "nextjs",
  "cleanUrls": true,
  "rewrites": [
    { "source": "/api/(.*)", "destination": "/api/index.py" },
    { "source": "/__zau/(.*)", "destination": "/api/index.py" }
  ]
}
2. api/index.py (ASGI Serverless Bridge)
import os
import sys

current_dir = os.path.dirname(os.path.abspath(__file__))
root_dir = os.path.abspath(os.path.join(current_dir, ".."))
if root_dir not in sys.path:
    sys.path.insert(0, root_dir)

from backend.app import app

# Export standard ASGI application callable
app = app.get_asgi_app()
3. Terminal Production Deployment Commands:
# 1. Authenticate with Vercel CLI
npx vercel login

# 2. Deploy directly to Production
npx vercel --prod --yes

# 3. Environment Variables (set in Vercel Dashboard):
#    DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/dbname
#    ZAU_ENV=production