OZmoz

The Client-Side Data OS for Modern Web Apps & AI Vibe-Coding

OZmoz manages the complete application data lifecycle: from AI-assisted schema modeling (Alex AI DBA) to deterministic Edge enforcement and seamless client-side execution.

Like an architect drafting blueprints before construction begins, Alex AI models your business domain and spins up an instant, production-ready backend. OZmoz delivers relational integrity, strict typing, and Edge security to MongoDB Atlas without writing backend boilerplate.

Why OZmoz?

• 100% Frontend Focus: Zero servers, zero custom REST APIs, and zero SQL migrations. Build full-stack applications purely from the client.
• AI Agent Accelerator: Eliminates hallucinations and cuts token usage by 90% via deterministic contracts (svro.schema.json, svro.workflow.json). Agents (Claude Code, Cursor, Windsurf) focus 100% of their reasoning on UX.
• Deterministic Edge Gatekeeper: Sub-millisecond $O(1)$ schema validation at the cloud edge before writes hit the database.
• Zero-Crash Native Web Components: 7 built-in, framework-agnostic Custom Elements (<oz-*>) preventing white-screen crashes on missing or partial data.
• Zero-Rewrite Philosophy: Write the exact same frontend code in trial mode (OZ_PROTOTYPE=true) and production (OZ_PROTOTYPE=false).

Quick Start

1. New Project with an AI Agent

Let your terminal AI agent build the project for you:

npx ozmoz start claude "Your application idea"

Or configure your environment and MCP server:

npx ozmoz login     # Authenticate once in your browser
npx ozmoz mcp       # Generates AGENTS.md, CLAUDE.md, GEMINI.md and MCP settings

2. Integration into an Existing Frontend

Install the package in your Vite project:

npm install ozmoz
npx ozmoz init --keyApp=<APP_KEY> --token=<BOOTSTRAP_TOKEN>
npx ozmoz sync

Execution Modes (.env)

Configure your operational mode in .env:

# Trial / Sandbox mode: all operations are simulated locally with demo data (oz.seed).
# Test code for authentication is always: 0000
OZ_PROTOTYPE=true

# Live mode: enforced physical schema, Edge security, and real database persistence.
OZ_PROTOTYPE=false

SDK Usage & Strict Governance

Every write operation requires literal governance metadata { desc, role, guard } to ensure contract validation.

Writing Data

// 1. Insert a document with mandatory governance
const res = await oz.add('orders', {
  product: 'Desk Pro',
  price: 299
}, {
  desc: 'Create customer order',
  role: 'AUTHENTICATED',
  guard: 'price > 0'
});

if (!res.success) {
  console.error('Order creation failed:', res.error);
} else {
  console.log('Created document ID:', res.documentId);
}

// 2. Update a document
const updateRes = await oz.update('orders', doc._id, {
  price: 249
}, {
  desc: 'Apply discount on order',
  role: 'MANAGER'
});

// 3. Delete a document
const delRes = await oz.delete('orders', doc._id, {
  desc: 'Cancel and delete order',
  role: 'ADMIN'
});

Reading Data

// Read all global documents in a collection
const orders = await oz.getDocsG('orders');

// Read documents owned by the authenticated user
const userOrders = await oz.getDocsU('orders');

// Read a single document by its _id
const order = await oz.getDoc('orders', 'order_123');

Authentication (Passwordless OTP)

// Step 1: Send OTP code (In trial mode, code is always 0000)
const otpRes = await oz.sendotpsvro('[email protected]');

// Step 2: Verify OTP code and establish session
const authRes = await oz.verifyotpsvro('[email protected]', '0000');
if (authRes.success) {
  console.log('Logged in user:', authRes.user);
}

// Check session status
const loggedIn = await oz.isAuthenticated();

Zero-Crash UI Components

Render data safely without risk of runtime null-pointer exceptions:

<!-- Text with fallback -->
<oz-text value={item.name} fallback="No name" />

<!-- Currency formatting with strict fallback -->
<oz-number value={item.price} currency="EUR" invalid-fallback="0" />

<!-- Boolean toggle representation -->
<oz-toggle value={item.isActive} label-true="Active" label-false="Inactive" />

<!-- Formatted date display -->
<oz-date value={item.createdAt} locale="en-US" invalid-fallback="Invalid date" />

<!-- Enum status validator -->
<oz-enum value={item.status} allowed="PENDING,CONFIRMED,DELIVERED" invalid-fallback="Unknown status" />

<!-- Relational reference resolution -->
<oz-reference table="users" id={item.userId} field="fullName" orphan-fallback="Deleted user" />

CLI Reference

| Command | Description | | :--- | :--- | | npx ozmoz login | Authenticate your workstation via browser OAuth. | | npx ozmoz mcp | Configure AI agent directives and register MCP tools. | | npx ozmoz init | Initialize local .env and bootstrap configurations. | | npx ozmoz sync | Seal contract on Cloud Edge and compile TypeScript definitions. | | npx ozmoz sync --check-only | Offline contract and type validation (no network requests). |

eof

### Résumé des éléments générés

1. **`checklist_deploiement.md`** : Fournit le diagnostic complet, les points de vigilance sur les bundles et Cloud Functions, ainsi que les 3 commandes de smoke test à exécuter avant le déploiement.
2. **`README.md`** : Totalement unifié sous la marque **OZmoz**, avec des exemples d'écriture conformes aux règles d'intégrité (gouvernance `{ desc, role }` et vérification de `res.success`).


# ozmoz

```bash
npx ozmoz

OZmoz is the SDK and CLI behind the oz.* API and the <oz-*> tags.

Quick start

Let an AI agent build for you (Claude Code, Gemini CLI, Codex CLI):

npx -y ozmoz start claude "your app idea"

Or connect your agent once, then work as usual:

npx ozmoz login     # approve once in the browser
npx ozmoz mcp       # writes AGENTS.md / CLAUDE.md / GEMINI.md and configures the MCP server

In an existing project

npm install ozmoz
npx ozmoz init --keyApp=<KEY> --token=<TOKEN>
npx ozmoz sync      # seals the schema and generates the contract + IDE types

Use npx ozmoz sync --check-only for an offline check.

Modes

Set in .env:

• OZ_PROTOTYPE=true: trial mode, everything is simulated locally (no backend call).
• OZ_PROTOTYPE=false: live mode, the data contract is enforced.

Run npx ozmoz --help for all commands.