Restructure documentation into protocol-first architecture with clean URLs

content/docs/00-introduction/architecture.mdx

@@ -0,0 +1,201 @@
+---
+title: Architecture
+description: Understanding the ObjectStack Protocol Architecture - How 11 protocol namespaces collaborate to build the Enterprise Kernel
+---
+
+import { Layers, Database, Layout, ShieldCheck, Lock, Cog, Brain, Cloud, Zap } from 'lucide-react';
+
+# Architecture Overview
+
+ObjectStack is not a monolithic framework. It is a composable ecosystem designed around a **Protocol-Driven Architecture**. The system is organized into **11 protocol namespaces**, each responsible for a specific domain.
+
+Each protocol is decoupled and communicates via standard JSON schemas defined with Zod. This allows you to swap out implementations (e.g., swapping the Postgres driver for MongoDB, or the React renderer for Flutter) without breaking the rest of the stack.
+
+## The 11 Protocol Namespaces
+
+ObjectStack is organized into 11 protocol namespaces:
+
+<Cards>
+  <Card
+    icon={<Database />}
+    title="Data Protocol"
+    description="Object schema, fields, validation, and queries."
+  />
+  <Card
+    icon={<Cog />}
+    title="Driver Protocol"
+    description="Database adapters (Postgres, MongoDB, SQLite, etc.)."
+  />
+  <Card
+    icon={<ShieldCheck />}
+    title="Permission Protocol"
+    description="Object-level, field-level, sharing, and territory rules."
+  />
+  <Card
+    icon={<Layout />}
+    title="UI Protocol"
+    description="Apps, views, dashboards, reports, and themes."
+  />
+  <Card
+    icon={<Layers />}
+    title="System Protocol"
+    description="Events, jobs, translations, and audit logging."
+  />
+  <Card
+    icon={<Lock />}
+    title="Auth Protocol"
+    description="Identity, roles, sessions, and authentication strategies."
+  />
+  <Card
+    icon={<Cog />}
+    title="Kernel Protocol"
+    description="Plugin lifecycle, manifest, logging, and context."
+  />
+  <Card
+    icon={<Cloud />}
+    title="Hub Protocol"
+    description="Marketplace, licensing, tenancy, and deployment."
+  />
+  <Card
+    icon={<Brain />}
+    title="AI Protocol"
+    description="Agents, RAG, NLQ, predictive models, and orchestration."
+  />
+  <Card
+    icon={<Zap />}
+    title="API Protocol"
+    description="REST contracts, discovery, realtime, and routing."
+  />
+  <Card
+    icon={<Zap />}
+    title="Automation Protocol"
+    description="Workflows, flows, and webhooks."
+  />
+</Cards>
+
+## The Three-Layer Architecture
+
+While ObjectStack has 11 protocol namespaces, they are logically grouped into three architectural layers:
+
+### 1. Data Layer (ObjectQL)
+**"The Universal Data Protocol"**
+
+The foundation layer responsible for **Data Definition** and **Data Access**.
+
+**Protocols:**
+- **Data Protocol:** Object schema, fields, validation, queries, filters
+- **Driver Protocol:** Database adapters for Postgres, MongoDB, SQLite, etc.
+- **Permission Protocol:** Object-level CRUD, field-level security, sharing rules
+- **AI Protocol:** AI agents, RAG pipelines, NLQ, predictive models
+
+**Role:** Defines *Structure* (Schema) and *Intent* (Query AST).
+
+**Responsibility:** It knows *what* a "Customer" object looks like, but it doesn't know *who* is accessing it or *how* it is displayed.
+
+**Key Component:** The **Compiler**. It takes an abstract query (`find customers where active = true`) and translates it into optimized SQL/NoSQL queries for the specific underlying database.
+
+### 2. Presentation Layer (ObjectUI)
+**"Server-Driven UI"**
+
+The interface layer responsible for **Visual Representation** and **User Interaction**.
+
+**Protocols:**
+- **UI Protocol:** Apps, views, dashboards, reports, actions, themes
+
+**Role:** Projects the Data Protocol into visual components.
+
+**Responsibility:** It knows *how* to display a "Customer" form, but it doesn't know the business rules or who can access it.
+
+**Key Component:** The **Renderer**. It takes UI metadata (JSON) and renders it as native components (React, Flutter, etc.).
+
+### 3. Control Layer (ObjectOS)
+**"The Business Kernel"**
+
+The orchestration layer responsible for **Runtime** and **Governance**.
+
+**Protocols:**
+- **System Protocol:** Events, jobs, translations, audit logging
+- **Auth Protocol:** Identity, roles, sessions, authentication
+- **Kernel Protocol:** Plugin lifecycle, manifest, context
+- **Hub Protocol:** Marketplace, licensing, tenancy
+- **API Protocol:** REST contracts, discovery, realtime
+- **Automation Protocol:** Workflows, flows, webhooks
+
+**Role:** Orchestrates the entire system and enforces policies.
+
+**Responsibility:** It knows *who* is accessing *what* and *when* actions should happen.
+
+**Key Component:** The **Kernel**. It manages plugins, handles events, enforces security, and coordinates between layers.
+
+## How They Work Together
+
+```
+┌─────────────────────────────────────────┐
+│          Control Layer (ObjectOS)        │
+│  ┌──────────┐  ┌────────┐  ┌──────────┐│
+│  │ Kernel   │  │ Auth   │  │ System   ││
+│  │ Protocol │  │Protocol│  │ Protocol ││
+│  └──────────┘  └────────┘  └──────────┘│
+└─────────────────────────────────────────┘
+           ↕                    ↕
+┌──────────────────┐    ┌──────────────────┐
+│ Data Layer (QL)  │    │ UI Layer (UI)    │
+│  ┌────────────┐  │    │  ┌────────────┐  │
+│  │ Data       │  │    │  │ UI         │  │
+│  │ Protocol   │  │    │  │ Protocol   │  │
+│  └────────────┘  │    │  └────────────┘  │
+│  ┌────────────┐  │    │                  │
+│  │ Driver     │  │    │                  │
+│  │ Protocol   │  │    │                  │
+│  └────────────┘  │    │                  │
+└──────────────────┘    └──────────────────┘
+         ↕
+   ┌──────────┐
+   │ Database │
+   └──────────┘
+```
+
+### Example: Creating a Record
+
+1. **UI Layer:** User clicks "Save" on a Customer form
+2. **Control Layer:** Kernel receives the request, validates authentication
+3. **Data Layer:** ObjectQL compiler generates SQL INSERT statement
+4. **Driver:** PostgreSQL driver executes the query
+5. **Control Layer:** Event system triggers "after_create" workflow
+6. **UI Layer:** Renderer updates the interface with the new record
+
+## Protocol vs Implementation
+
+**Critical Distinction:**
+
+- **Protocol Layer:** Defined in `packages/spec` (This Repository)
+  - Pure Zod schemas
+  - TypeScript types
+  - No runtime logic
+
+- **Runtime Layer:** Implemented in separate packages
+  - Node.js Kernel (`@objectstack/kernel`)
+  - React Renderer (`@objectstack/react`)
+  - PostgreSQL Driver (`@objectstack/driver-postgres`)
+
+The protocol defines the "what" and "how." The runtime implements it.
+
+## Design Benefits
+
+### 1. Composability
+Each protocol can be used independently or combined with others.
+
+### 2. Replaceability
+Don't like the React renderer? Build a Vue or Flutter one. The protocol stays the same.
+
+### 3. Testability
+Test against the protocol specification, not a specific implementation.
+
+### 4. Future-Proof
+New features are additive, not breaking. Implementations can evolve independently.
+
+## Next Steps
+
+- [Glossary](/docs/00-introduction/glossary) - Key terminology explained
+- [Core Concepts](/docs/01-core-concepts) - Understand metadata-driven development
+- [Protocols](/docs/02-protocols) - Dive into each protocol specification

content/docs/00-introduction/design-principles.mdx

@@ -0,0 +1,161 @@
+---
+title: Design Principles
+description: The unshakable core principles that govern the ObjectStack ecosystem - The Constitution of the Post-SaaS Era
+---
+
+import { Scale, Code2, Database, ScrollText } from 'lucide-react';
+
+# Design Principles
+
+ObjectStack exists to return enterprise application development to its essence: **Data**.
+
+To maintain a healthy, decoupled, and future-proof ecosystem, we uphold the following core principles. These are not suggestions; they are the constraints that enable our freedom.
+
+<Cards>
+  <Card
+    icon={<Scale />}
+    title="I. Protocol Neutrality"
+    description="The Protocol is law. The Implementation is merely an opinion."
+  />
+  <Card
+    icon={<Code2 />}
+    title="II. Mechanism over Policy"
+    description="Provide the tools to build rules, do not hardcode the rules themselves."
+  />
+  <Card
+    icon={<Database />}
+    title="III. Single Source of Truth"
+    description="There is no 'Code'. There is only Schema."
+  />
+  <Card
+    icon={<ScrollText />}
+    title="IV. Local-First by Default"
+    description="The Cloud is a sync peer, not a master."
+  />
+</Cards>
+
+---
+
+## Principle I: Protocol Neutrality
+
+**"The Protocol is neutral. The Engine is replaceable."**
+
+ObjectQL must not contain any logic specific to a particular language (e.g., Node.js), database (e.g., PostgreSQL), or runtime (e.g., Browser).
+
+### The Law
+
+- **Spec before Engine:** Any feature must first be defined in the Specification layer (`packages/spec`) before a single line of code is written in the Engine layer. We reject the "implement first, standardize later" approach.
+- **Zero Leakage:** Implementation details (like React Hooks usage, or SQL specific syntax) must never leak into the Protocol definition.
+
+### The Benefit
+
+This ensures that an ObjectStack application defined today can theoretically run on:
+
+- A Node.js server with PostgreSQL (Today's Standard)
+- A Python server with SQLite (AI/Data Science)
+- A Rust WASM module in the browser (Local-First)
+
+---
+
+## Principle II: Mechanism over Policy
+
+**"Give them the physics, not the simulation."**
+
+ObjectStack provides the **Mechanisms** (The "How"):
+
+- *"Here is how you define a validation rule."*
+- *"Here is how you define a permission scope."*
+
+ObjectStack never dictates the **Policy** (The "What"):
+
+- *It never says "Passwords must be 8 characters".*
+- *It never says "Users must belong to a Department".*
+
+### Separation of Concerns
+
+We cleanly separate the **Definition** from the **Execution**.
+
+| Layer | Responsibility | Example |
+| :--- | :--- | :--- |
+| **Protocol (Mechanism)** | Defines the capabilities. | `allowRead: string` (A slot for a formula) |
+| **App (Policy)** | Defines the business logic. | `allowRead: "$user.role == 'admin'"` |
+| **Engine (Execution)** | Enforces the logic. | Compiles formula to SQL `WHERE` clause. |
+
+---
+
+## Principle III: The Single Source of Truth
+
+**"There is no 'Code'. There is only Schema."**
+
+In a traditional application, the "truth" is scattered:
+
+1. Database Schema (`table.sql`)
+2. Backend Models (`User.ts`)
+3. Frontend Validation (`schema.zod.ts`)
+4. API Documentation (`swagger.json`)
+
+In ObjectStack, **The Object Protocol is the only truth.**
+
+- The Database is a *derivative* of the Protocol.
+- The UI is a *projection* of the Protocol.
+- The API is a *consequence* of the Protocol.
+
+If you change the Protocol, the entire system (DB, API, UI) must adapt automatically.
+
+---
+
+## Principle IV: Local-First by Default
+
+**"The Cloud is a sync peer, not a master."**
+
+We reject the notion that software must stop working when the internet connection drops.
+
+- **Latency is the enemy:** All interactions should be optimistic and instant (0ms).
+- **Ownership is the goal:** The user's data essentially lives on their device. The server is just a hub for backup and collaboration.
+
+### The "Seven Hops" Problem
+
+In a traditional Cloud app, a simple button click travels through:
+
+```
+Click → Wi-Fi → ISP → Cloud Load Balancer → Web Server → Database → Query Execution
+```
+
+...and then all the way back.
+
+### The Local-First Solution
+
+ObjectStack apps are designed to read and write to a **Local Database** (embedded within the client environment) first.
+
+```
+Click → Local DB → UI Update (0ms Latency)
+```
+
+The synchronization with the cloud happens in the background, asynchronously.
+
+**Benefits:**
+
+1. **Instant Response:** The UI reacts immediately (optimistic UI)
+2. **Offline Capability:** Field workers, airplanes, or spotty connections are no longer blockers
+3. **Data Sovereignty:** The data physically resides on the user's device
+
+---
+
+## Summary
+
+These principles guide every design decision in ObjectStack:
+
+| Principle | What it Means |
+| :--- | :--- |
+| **Protocol Neutrality** | The spec is separate from implementation. ObjectStack can run anywhere. |
+| **Mechanism over Policy** | We provide the tools, you define the rules. |
+| **Single Source of Truth** | The schema is the application. Everything else derives from it. |
+| **Local-First** | Users own their data. The cloud is just for sync. |
+
+By adhering to these values, we build software that is **resilient to change**, **respectful of user time**, and **technically sovereign**.
+
+## Next Steps
+
+- [Architecture](/docs/00-introduction/architecture) - See how these principles shape the system
+- [Glossary](/docs/00-introduction/glossary) - Understand key terms
+- [Core Concepts](/docs/01-core-concepts) - Learn about metadata-driven development