diff --git a/content/docs/faq.mdx b/content/docs/faq.mdx new file mode 100644 index 000000000..77ff46fc4 --- /dev/null +++ b/content/docs/faq.mdx @@ -0,0 +1,312 @@ +--- +title: FAQ +description: Frequently Asked Questions about ObjectStack Protocol. +--- + +## General Questions + +### What is ObjectStack? + +ObjectStack is a **metadata-driven protocol** for building enterprise applications. It lets you define your entire application—data models, business logic, and UI—as type-safe JSON/TypeScript configurations instead of writing code. + +Think of it as the "Salesforce Platform" or "ServiceNow Platform" but: +- ✅ Open source +- ✅ Self-hosted +- ✅ Type-safe (TypeScript + Zod) +- ✅ Database agnostic + +### Is ObjectStack a framework or a library? + +Neither! ObjectStack is a **protocol** (like HTTP or SQL). It defines: +1. **Schemas** (what data looks like) +2. **Contracts** (how systems communicate) +3. **Standards** (naming conventions, best practices) + +You can build **implementations** of the protocol in any language (Node.js, Go, Python, etc.). + +### How is ObjectStack different from Prisma/TypeORM? + +| Feature | Prisma/TypeORM | ObjectStack | +| :--- | :--- | :--- | +| **Scope** | ORM (database only) | Full platform (data + UI + logic) | +| **Business Logic** | Code-based | Declarative (formulas, workflows) | +| **UI Generation** | None | Server-driven UI included | +| **Validation** | Manual | Built-in validation rules | +| **Multi-DB** | Schema-based | Driver-based (easier to extend) | + +**Use Prisma if:** You just need a type-safe ORM. +**Use ObjectStack if:** You want a complete metadata-driven platform. + +### How is ObjectStack different from Strapi/Directus? + +| Feature | Strapi/Directus | ObjectStack | +| :--- | :--- | :--- | +| **Focus** | Headless CMS | Enterprise platform | +| **Business Logic** | Code plugins | Declarative (no-code) | +| **Type Safety** | Partial | Full (Zod schemas) | +| **Formulas** | None | Yes (like Excel/Salesforce) | +| **Workflows** | Basic | Advanced (state machines) | +| **Offline-First** | No | Yes | + +**Use Strapi if:** You're building a content website. +**Use ObjectStack if:** You're building CRUD-heavy apps (CRM, ERP, internal tools). + +### Can I use ObjectStack with my existing database? + +**Yes!** You have two options: + +1. **Generate ObjectStack schemas from your DB:** + ```bash + objectstack import --from postgres://... + ``` + +2. **Write a custom driver** to wrap your existing DB. + +### Is ObjectStack production-ready? + +ObjectStack is currently in **beta**. The protocol is stable, but implementations are evolving. + +**Stable:** +- ✅ Schema definitions (`@objectstack/spec`) +- ✅ TypeScript types +- ✅ JSON Schema export + +**In Development:** +- 🚧 Reference Kernel implementation +- 🚧 React renderer +- 🚧 PostgreSQL driver + +**Recommendation:** Use for internal tools and non-critical applications. Wait for v1.0 for production SaaS. + +## Technical Questions + +### What databases are supported? + +ObjectStack uses a **driver model**. Official drivers: + +- ✅ **In-Memory Driver** (development/testing) +- 🚧 **PostgreSQL Driver** (in progress) +- 🚧 **MySQL Driver** (planned) +- 🚧 **MongoDB Driver** (planned) + +You can build custom drivers for: +- Any SQL database +- Any NoSQL database +- SaaS APIs (Salesforce, Airtable, etc.) +- Excel files, CSV, etc. + +### Does ObjectStack support GraphQL? + +**Yes!** ObjectStack auto-generates both REST and GraphQL APIs from your schema definitions. + +### Can I customize the generated UI? + +**Yes!** You have multiple levels of customization: + +1. **Theme-level:** Colors, fonts, spacing +2. **Component-level:** Override specific components (Button, Input, etc.) +3. **Layout-level:** Change view configurations +4. **Complete custom renderer:** Build your own UI that consumes ObjectStack APIs + +### How do I handle complex business logic? + +ObjectStack provides multiple ways: + +1. **Formula Fields:** Excel-like formulas for calculations + ```typescript + Field.formula({ expression: 'amount * (1 - discount / 100)' }) + ``` + +2. **Validation Rules:** Declarative constraints + ```typescript + ValidationRule.create({ condition: 'due_date > TODAY()' }) + ``` + +3. **Workflows:** Trigger actions on events + ```typescript + Workflow.create({ trigger: 'after_update', actions: [...] }) + ``` + +4. **Custom Code:** For truly complex logic, write TypeScript plugins + +### How does authentication work? + +ObjectStack supports **pluggable authentication providers**: + +- OAuth 2.0 / OIDC +- SAML +- JWT tokens +- API keys +- Custom providers + +Configure in your app manifest: + +```typescript +Manifest.create({ + authentication: { + provider: 'oauth2', + config: { /* provider config */ }, + }, +}); +``` + +### Is ObjectStack multi-tenant? + +**Yes!** ObjectStack supports multiple multi-tenancy strategies: + +1. **Schema-per-tenant:** Each tenant gets their own database schema +2. **Row-level security:** Single schema with tenant isolation via RLS +3. **Database-per-tenant:** Complete isolation + +Configure based on your needs. + +### How do I deploy ObjectStack apps? + +ObjectStack apps are standard Node.js applications. Deploy like any Node app: + +- **Docker:** `docker build` → `docker run` +- **Kubernetes:** Standard K8s deployment +- **Serverless:** AWS Lambda, Google Cloud Functions +- **PaaS:** Heroku, Railway, Render + +See the [Deployment Guide](/docs/guides/deployment) for details. + +## Development Questions + +### Do I need to know Zod? + +**Helpful but not required.** If you've used Yup, Joi, or similar validation libraries, Zod will feel familiar. + +Basic example: +```typescript +import { z } from 'zod'; + +const schema = z.object({ + name: z.string(), + age: z.number().min(0), +}); +``` + +ObjectStack provides helper functions to hide Zod complexity: + +```typescript +// Instead of raw Zod +const raw = z.object({ title: z.string() }); + +// Use ObjectStack helpers +const Task = ObjectSchema.create({ + fields: { + title: Field.text({ label: 'Title' }), + } +}); +``` + +### How do I debug ObjectStack apps? + +1. **Schema validation errors:** Zod provides detailed error messages +2. **Runtime logs:** ObjectStack kernel logs all operations +3. **Query debugging:** Enable query logging to see generated SQL +4. **UI debugging:** Inspect JSON configs in browser devtools + +### Can I use ObjectStack with React/Vue/Svelte? + +**Yes!** ObjectStack is UI-framework agnostic. + +**Option 1:** Use official renderers +- `@objectstack/react-renderer` (recommended) +- `@objectstack/vue-renderer` (planned) + +**Option 2:** Consume REST/GraphQL APIs from any framework + +```tsx +// React example +function TaskList() { + const { data } = useFetch('/api/v1/objects/task'); + return
{/* your UI */}
; +} +``` + +### How do I contribute to ObjectStack? + +See the [Contributing Guide](https://github.com/objectstack-ai/spec/blob/main/CONTRIBUTING.md). + +We welcome: +- Bug reports +- Documentation improvements +- Driver implementations +- Renderer implementations +- Example applications + +## Business Questions + +### What's the license? + +**Apache 2.0** (open source, permissive). + +You can: +- ✅ Use commercially +- ✅ Modify and distribute +- ✅ Use in proprietary software +- ✅ Sublicense + +### Is there commercial support? + +Not yet. Commercial support and managed hosting are planned for the future. + +For now: +- Community support via GitHub Discussions +- Professional consulting available (contact team) + +### Can I build a SaaS product with ObjectStack? + +**Absolutely!** ObjectStack is designed for multi-tenant SaaS platforms. + +Many use cases: +- Internal developer platforms +- Vertical SaaS (industry-specific apps) +- White-label solutions +- Agency client portals + +### Who is behind ObjectStack? + +ObjectStack is an **open-source project** created by the ObjectStack AI team. See [GitHub Contributors](https://github.com/objectstack-ai/spec/graphs/contributors). + +## Common Errors + +### "Schema validation failed" + +**Cause:** Your schema definition doesn't match the Zod schema. + +**Solution:** Check the error message for which field failed. Common issues: +- Missing required fields +- Wrong field type +- Invalid enum value + +### "Driver not found" + +**Cause:** Kernel can't find the database driver. + +**Solution:** +```typescript +import { MemoryDriver } from '@objectstack/driver-memory'; + +kernel.registerDriver('memory', new MemoryDriver()); +``` + +### "Circular dependency in lookup fields" + +**Cause:** Two objects reference each other, creating a cycle. + +**Solution:** Use lazy references: +```typescript +Field.lookup({ + reference: () => import('./other-object'), +}) +``` + +## Still Have Questions? + +- 📖 Check the [Guides](/docs/guides/getting-started) +- 💬 Ask in [GitHub Discussions](https://github.com/objectstack-ai/spec/discussions) +- 🐛 Report bugs in [GitHub Issues](https://github.com/objectstack-ai/spec/issues) +- 📧 Email: support@objectstack.dev (for urgent issues) diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 39f37b19a..360d4984a 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -15,9 +15,15 @@ This documentation is the authoritative reference for the ObjectStack Protocol. } - title="Getting Started" - href="/docs/guides/getting-started" - description="Build your first Object in 5 minutes. Learn the basics with practical examples." + title="Quick Start" + href="/docs/quick-start" + description="Get started in under 5 minutes. Choose your learning path based on your role." + /> + } + title="Tutorials" + href="/docs/tutorials" + description="Hands-on step-by-step tutorials to build real applications and learn by doing." /> } @@ -28,14 +34,37 @@ This documentation is the authoritative reference for the ObjectStack Protocol. } title="Specifications" - href="/docs/specifications/data/architecture" + href="/docs/specifications" description="The Architecture Blueprints. Deep dive into ObjectQL (Data), ObjectUI (View), and ObjectOS (Control)." /> + + +## Additional Resources + + + } + title="Developer Guides" + href="/docs/guides/getting-started" + description="Comprehensive guides for building with ObjectStack. Field types, views, workflows, and more." + /> } - title="Protocol Reference" + title="API Reference" href="/docs/references/data/core/Object" - description="The Dictionary. Comprehensive reference for every Schema, Field Type, and Configuration option." + description="Complete API documentation for every schema, field type, and configuration option." + /> + } + title="FAQ" + href="/docs/faq" + description="Frequently asked questions about ObjectStack and how to use it." + /> + } + title="Troubleshooting" + href="/docs/troubleshooting" + description="Common issues and how to resolve them." /> diff --git a/content/docs/meta.cn.json b/content/docs/meta.cn.json index 42bad1455..9e6fef419 100644 --- a/content/docs/meta.cn.json +++ b/content/docs/meta.cn.json @@ -1,9 +1,13 @@ { "title": "文档", "pages": [ + "quick-start", + "tutorials", "guides", "concepts", "specifications", - "references" + "references", + "faq", + "troubleshooting" ] } diff --git a/content/docs/meta.json b/content/docs/meta.json index d2e447a28..36353aaa3 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,9 +1,13 @@ { "title": "Documentation", "pages": [ + "quick-start", + "tutorials", "guides", "concepts", "specifications", - "references" + "references", + "faq", + "troubleshooting" ] } \ No newline at end of file diff --git a/content/docs/quick-start.mdx b/content/docs/quick-start.mdx new file mode 100644 index 000000000..162419fd7 --- /dev/null +++ b/content/docs/quick-start.mdx @@ -0,0 +1,117 @@ +--- +title: Quick Start +description: Get started with ObjectStack in under 5 minutes. Choose your path based on your role and goals. +--- + +import { Code, Layers, Palette, Zap } from 'lucide-react'; + +Welcome to ObjectStack! This quick start guide will help you get up and running based on your role and what you want to accomplish. + +## Choose Your Path + + + } + title="I want to build an app" + href="/docs/quick-start/build-first-app" + description="Complete tutorial: Build a task management app in 10 minutes" + /> + } + title="I'm a backend developer" + href="/docs/quick-start/backend-developers" + description="Learn how to define Objects, Fields, and Business Logic" + /> + } + title="I'm a frontend developer" + href="/docs/quick-start/frontend-developers" + description="Understand Views, Pages, and UI Components" + /> + } + title="I'm a platform architect" + href="/docs/quick-start/architects" + description="Deep dive into the protocol architecture and design decisions" + /> + + +## 30-Second Overview + +ObjectStack is a **metadata-driven protocol** that lets you define your entire application—data models, business logic, and UI—as **type-safe JSON/TypeScript** configurations. + +```typescript +// Define a data model +export const Task = ObjectSchema.create({ + name: 'task', + label: 'Task', + fields: { + title: Field.text({ label: 'Title', required: true }), + status: Field.select({ + label: 'Status', + options: ['todo', 'in_progress', 'done'] + }), + due_date: Field.date({ label: 'Due Date' }), + } +}); +``` + +**That's it!** You've just defined a complete data model with: +- ✅ TypeScript type safety +- ✅ Runtime validation (via Zod) +- ✅ Automatic API generation +- ✅ Database schema migration +- ✅ Admin UI generation + +## What Makes ObjectStack Different? + +| Traditional Approach | ObjectStack Protocol | +| :--- | :--- | +| Write Models + Controllers + Views | **Define metadata once** | +| SQL migrations by hand | **Auto-generated from schema** | +| Build CRUD APIs manually | **REST/GraphQL auto-generated** | +| Hardcoded UI components | **Server-driven UI from JSON** | +| Scattered business logic | **Declarative rules & workflows** | + +## Next Steps + + + +### 1. Install the package + +```bash +npm install @objectstack/spec zod +``` + +### 2. Choose your learning path + +- **Quick & Practical:** [Build Your First App](/docs/quick-start/build-first-app) - Hands-on tutorial +- **Conceptual Understanding:** [Core Concepts](/docs/concepts/manifesto) - Philosophy and architecture +- **Complete Reference:** [Developer Guides](/docs/guides/getting-started) - Comprehensive documentation + +### 3. Explore examples + +- [CRM Example](https://github.com/objectstack-ai/spec/tree/main/examples/crm) - Full-featured application +- [Todo Example](https://github.com/objectstack-ai/spec/tree/main/examples/todo) - Minimal quick-start + + + +## Common Use Cases + +### Internal Tools & Admin Panels +Build CRUD applications with complex business logic in hours, not weeks. + +### CRM & ERP Systems +Replicate Salesforce-like functionality with complete customization. + +### Workflow Automation Platforms +Define approval flows, state machines, and automation rules declaratively. + +### Multi-tenant SaaS Platforms +One codebase, infinite customizations through metadata configuration. + +## Need Help? + +- **Documentation:** You're reading it! Use the search bar above. +- **GitHub Issues:** [Report bugs or request features](https://github.com/objectstack-ai/spec/issues) +- **Examples:** Browse the `/examples` directory in the repository diff --git a/content/docs/quick-start/architects.mdx b/content/docs/quick-start/architects.mdx new file mode 100644 index 000000000..825e7fb05 --- /dev/null +++ b/content/docs/quick-start/architects.mdx @@ -0,0 +1,502 @@ +--- +title: For Platform Architects +description: Deep dive into ObjectStack's architecture, design decisions, and how it compares to industry standards. +--- + +Welcome architects! If you're evaluating ObjectStack for your platform or investigating metadata-driven architectures, this guide will help you understand the design philosophy and technical decisions. + +## Architectural Overview + +ObjectStack is a **protocol-first, metadata-driven platform** that virtualizes the application stack into three declarative layers: + +``` +┌──────────────────────────────────────┐ +│ AI Protocol (Optional) │ ← Agent definitions, tools, knowledge +├──────────────────────────────────────┤ +│ API Protocol │ ← REST/GraphQL contracts +├──────────────────────────────────────┤ +│ UI Layer (ObjectUI) │ ← Server-Driven UI definitions +├──────────────────────────────────────┤ +│ Data Layer (ObjectQL) │ ← Schema, queries, business logic +├──────────────────────────────────────┤ +│ System Layer (ObjectOS) │ ← Runtime kernel, plugins, drivers +└──────────────────────────────────────┘ +``` + +## Design Philosophy + +### 1. Intent over Implementation + +**Problem:** Traditional development couples *what you want* with *how to do it*. + +**ObjectStack Solution:** Separate business intent (metadata) from technical execution (kernel). + +```typescript +// INTENT (what you want) +const Task = ObjectSchema.create({ + name: 'task', + fields: { + title: Field.text({ required: true }), + } +}); + +// EXECUTION (handled by kernel) +// ✓ SQL schema generation +// ✓ API route creation +// ✓ Validation logic +// ✓ UI rendering +``` + +### 2. Local-First, Cloud-Optional + +Inspired by: [Local-First Software Manifesto](https://www.inkandswitch.com/local-first/) + +**Benefits:** +- ✅ Offline-capable by default +- ✅ No vendor lock-in +- ✅ Data ownership +- ✅ Instant responsiveness + +### 3. Protocol, Not Framework + +Like **HTTP** or **SQL**, ObjectStack defines a protocol that multiple implementations can follow. + +``` +Protocol Definition (this repo) + ↓ +┌──────────────────────────────────────────────────────┐ +│ Implementations (bring your own) │ +├──────────────────────────────────────────────────────┤ +│ • Kernel: Node.js, Deno, Bun, Go, Python │ +│ • Driver: PostgreSQL, MongoDB, Redis, Custom │ +│ • Renderer: React, Vue, Flutter, Native │ +└──────────────────────────────────────────────────────┘ +``` + +## Industry Comparison + +### Salesforce Platform + +| Feature | Salesforce | ObjectStack | +| :--- | :--- | :--- | +| **Metadata-Driven** | ✅ Yes | ✅ Yes | +| **Custom Objects** | ✅ Yes | ✅ Yes | +| **Formula Fields** | ✅ Yes | ✅ Yes | +| **Workflows** | ✅ Yes | ✅ Yes | +| **Open Source** | ❌ No | ✅ Yes | +| **Self-Hosted** | ❌ No | ✅ Yes | +| **Type-Safe** | ❌ No | ✅ TypeScript + Zod | +| **Database Agnostic** | ❌ No | ✅ Yes (Driver Model) | + +**ObjectStack = Salesforce's metadata model + Open Source + Type Safety** + +### ServiceNow Platform + +| Feature | ServiceNow | ObjectStack | +| :--- | :--- | :--- | +| **Configuration as Code** | ✅ Yes | ✅ Yes | +| **Server-Driven UI** | ✅ Yes | ✅ Yes | +| **Business Rules Engine** | ✅ Yes | ✅ Yes | +| **Plugin Architecture** | ✅ Yes | ✅ Yes | +| **Open Protocol** | ❌ No | ✅ Yes | +| **Local-First** | ❌ No | ✅ Yes | +| **Modern DX** | ⚠️ XML-based | ✅ TypeScript + JSON | + +### Hasura / PostgREST (Auto-API) + +| Feature | Hasura | ObjectStack | +| :--- | :--- | :--- | +| **Auto-Generated API** | ✅ Yes | ✅ Yes | +| **GraphQL Support** | ✅ Yes | ✅ Yes | +| **Database First** | ✅ Yes | ⚠️ Schema-first | +| **Business Logic** | ⚠️ External | ✅ Built-in (formulas, workflows) | +| **UI Generation** | ❌ No | ✅ Yes | +| **Multi-DB Support** | ⚠️ Limited | ✅ Via drivers | + +### Strapi / Directus (Headless CMS) + +| Feature | Strapi | ObjectStack | +| :--- | :--- | :--- | +| **Schema Builder** | ✅ Yes | ✅ Yes | +| **Auto Admin Panel** | ✅ Yes | ✅ Yes | +| **API Generation** | ✅ Yes | ✅ Yes | +| **Business Logic** | ⚠️ Code-based | ✅ Declarative | +| **Type Safety** | ⚠️ Partial | ✅ Full (Zod) | +| **Enterprise Features** | ⚠️ Limited | ✅ Workflows, validation, permissions | + +## Technical Architecture + +### Layer 1: Data Protocol (ObjectQL) + +Inspired by: **SQL**, **GraphQL**, **Apache Calcite** + +**Abstraction:** Represent queries as an Abstract Syntax Tree (AST). + +```typescript +// High-level query +const query = Query.create({ + object: 'order', + filters: { total: { gt: 1000 } }, + include: ['customer'], +}); + +// Compiles to AST +const ast = { + type: 'SELECT', + from: { object: 'order' }, + where: { + type: 'BINARY_OP', + operator: 'GT', + left: { type: 'FIELD', name: 'total' }, + right: { type: 'LITERAL', value: 1000 }, + }, + joins: [ + { object: 'customer', type: 'LEFT', on: 'customer_id' }, + ], +}; + +// Driver translates AST → SQL/NoSQL/etc. +``` + +**Benefits:** +- ✅ Database agnostic (SQL, NoSQL, SaaS APIs) +- ✅ Query optimization at AST level +- ✅ Consistent semantics across backends + +### Layer 2: UI Protocol (ObjectUI) + +Inspired by: **Salesforce Lightning**, **React Server Components**, **Flutter** + +**Server-Driven UI (SDUI):** Client is a "dumb renderer" that interprets JSON configs. + +```typescript +// Server defines UI as JSON +const view = ListView.create({ + viewType: 'grid', + columns: [{ field: 'title' }], +}); + +// Client renders based on schema + +``` + +**Benefits:** +- ✅ Update UI without app rebuild +- ✅ A/B testing at configuration level +- ✅ Consistent UX across platforms +- ✅ AI can generate/modify UI + +### Layer 3: System Protocol (ObjectOS) + +Inspired by: **Kubernetes**, **OSGi**, **Eclipse RCP** + +**Plugin Architecture:** Kernel loads and orchestrates plugins. + +```typescript +interface Plugin { + name: string; + version: string; + + // Lifecycle hooks + onLoad(kernel: IKernel): void; + onUnload(): void; + + // Capabilities + provides?: { + drivers?: Driver[]; + apis?: ApiContract[]; + ui?: Component[]; + }; +} +``` + +**Benefits:** +- ✅ Modular, composable system +- ✅ Hot-swappable components +- ✅ Ecosystem of community plugins + +## Zod-First Approach + +**Decision:** All schemas are defined using Zod. + +```typescript +// Source of truth +export const TaskSchema = z.object({ + title: z.string().max(200), + status: z.enum(['todo', 'done']), +}); + +// Derived artifacts +type Task = z.infer; // TypeScript type +const jsonSchema = zodToJsonSchema(TaskSchema); // JSON Schema +const sqlSchema = zodToSql(TaskSchema); // SQL DDL +``` + +**Benefits:** +- ✅ **Runtime validation** (Zod validates at runtime) +- ✅ **Compile-time types** (TypeScript inference) +- ✅ **Single source of truth** (no drift between types and validators) +- ✅ **Tooling ecosystem** (JSON Schema for OpenAPI, IDEs, etc.) + +## Formula Engine + +**Inspired by:** Salesforce Formula Fields, Excel Formulas + +ObjectStack includes a declarative formula language: + +```typescript +Field.formula({ + expression: 'IF(discount_code != NULL, subtotal * 0.9, subtotal)', +}) +``` + +**Implementation:** +1. Parse formula → AST +2. Type-check AST +3. Compile to JavaScript (or other runtime) +4. Execute safely (sandboxed) + +**Security:** +- ✅ No arbitrary code execution +- ✅ Whitelist of allowed functions +- ✅ Type-safe by construction + +## Multi-Tenancy Strategy + +ObjectStack supports **multiple multi-tenancy models**: + +### 1. Schema-per-Tenant (PostgreSQL) + +```sql +CREATE SCHEMA tenant_acme; +CREATE SCHEMA tenant_beta; +``` + +**Pros:** Strong isolation, easy backup/restore per tenant +**Cons:** Schema proliferation, migration complexity + +### 2. Row-Level Security (RLS) + +```sql +ALTER TABLE orders ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON orders + USING (tenant_id = current_tenant_id()); +``` + +**Pros:** Efficient, single schema +**Cons:** Query performance overhead + +### 3. Database-per-Tenant + +**Pros:** Ultimate isolation +**Cons:** Resource intensive + +**ObjectStack Recommendation:** Configurable per deployment. + +## Scalability Considerations + +### Horizontal Scalability + +``` +┌─────────────────────────────────────────┐ +│ Load Balancer │ +└─────────────┬───────────────────────────┘ + │ + ┌─────────┼─────────┬─────────┐ + ▼ ▼ ▼ ▼ + [Kernel] [Kernel] [Kernel] [Kernel] ← Stateless kernels + │ │ │ │ + └─────────┴─────────┴─────────┘ + │ + ▼ + [Database] ← Centralized or sharded +``` + +**Stateless Kernel:** +- All state in database or cache +- Session in Redis/Memcached +- File uploads in S3/Minio + +### Caching Strategy + +```typescript +// Multi-layer cache +const data = await cache.get('order:123') // L1: Redis + ?? await dbCache.get('order:123') // L2: DB connection pool + ?? await database.query({ ... }); // L3: Source + +cache.set('order:123', data, { ttl: 60 }); +``` + +### Database Sharding + +ObjectStack AST allows **transparent sharding**: + +```typescript +// Driver detects shard key +const driver = new ShardedDriver({ + shardKey: 'customer_id', + shards: [db1, db2, db3], +}); + +// Query automatically routed +await driver.find({ + object: 'order', + filters: { customer_id: { eq: 'acme-corp' } }, // → shard 1 +}); +``` + +## Security Architecture + +### 1. Authentication + +**Pluggable providers:** +- OAuth 2.0 / OIDC +- SAML +- JWT +- API Keys +- Custom + +### 2. Authorization + +**Multi-level access control:** + +```typescript +// Object-level permissions +Permission.create({ + profile: 'sales_user', + object: 'opportunity', + create: true, + read: true, + update: { owned: true }, // Only own records + delete: false, +}); + +// Field-level security +FieldPermission.create({ + profile: 'sales_user', + object: 'account', + field: 'annual_revenue', + read: false, // Hidden field +}); + +// Row-level sharing +SharingRule.create({ + object: 'account', + sharedTo: 'sales_team', + accessLevel: 'read', + criteria: { region: 'US' }, +}); +``` + +### 3. Data Encryption + +**At rest:** Database-level encryption (LUKS, TDE) +**In transit:** TLS 1.3 +**Field-level:** Encrypt sensitive fields (PII) + +```typescript +Field.text({ + label: 'SSN', + encrypted: true, + encryptionKey: 'field_encryption_key', +}) +``` + +## Observability + +### Structured Logging + +```typescript +logger.info('Query executed', { + object: 'order', + duration: 45, + rowsReturned: 100, + userId: 'user-123', +}); +``` + +### Metrics (OpenTelemetry) + +- Request rate, latency, errors (RED metrics) +- Database query performance +- Cache hit rate +- Formula evaluation time + +### Tracing + +Distributed tracing across: +1. API request +2. Kernel processing +3. Driver query +4. Database execution + +## When to Use ObjectStack + +### ✅ Good Fit + +- **Internal tools** (admin panels, dashboards) +- **CRUD-heavy applications** (CRM, ERP, ticketing) +- **Multi-tenant SaaS** (need customization per tenant) +- **Rapid prototyping** (MVP in hours/days) +- **Low-code platforms** (enable non-developers) + +### ⚠️ Consider Alternatives + +- **Real-time gaming** (too much abstraction overhead) +- **Ultra-high throughput** (raw SQL might be faster) +- **Greenfield with simple needs** (might be overkill) + +## Migration Path + +### Incremental Adoption + +``` +Existing App + ↓ +1. Wrap existing DB with ObjectStack driver +2. Generate ObjectStack schemas from DB +3. Replace one module at a time +4. Gradual migration +``` + +### Coexistence Strategy + +```typescript +// Use ObjectStack for new features +const newFeature = ObjectSchema.create({ ... }); + +// Keep existing code for legacy features +app.get('/legacy', legacyController); +``` + +## Next Steps for Architects + + + + + + + + +## Resources + +- **[Architecture Diagrams](https://github.com/objectstack-ai/spec/blob/main/ARCHITECTURE.md)** - Visual reference +- **[Development Roadmap](https://github.com/objectstack-ai/spec/blob/main/DEVELOPMENT_ROADMAP.md)** - Future plans +- **[Contributing Guide](https://github.com/objectstack-ai/spec/blob/main/CONTRIBUTING.md)** - How to contribute diff --git a/content/docs/quick-start/backend-developers.mdx b/content/docs/quick-start/backend-developers.mdx new file mode 100644 index 000000000..4ea7ad44b --- /dev/null +++ b/content/docs/quick-start/backend-developers.mdx @@ -0,0 +1,396 @@ +--- +title: For Backend Developers +description: Learn ObjectStack from a backend perspective - focus on data modeling, business logic, and API generation. +--- + +Welcome backend developers! If you're familiar with ORMs (Sequelize, TypeORM, Prisma) or NoSQL ODMs (Mongoose), you'll find ObjectStack refreshingly familiar yet more powerful. + +## Core Concept + +ObjectStack replaces traditional: +``` +Model → Migration → Controller → API Routes +``` + +With a single source of truth: +```typescript +Object Definition → Everything Auto-Generated +``` + +## Quick Comparison + +### Traditional Approach (Express + Sequelize) + +```typescript +// 1. Define Model +const Task = sequelize.define('Task', { + title: { type: DataTypes.STRING, allowNull: false }, + status: { type: DataTypes.ENUM('todo', 'done') }, + dueDate: { type: DataTypes.DATE }, +}); + +// 2. Write Migration +await queryInterface.createTable('tasks', { /* ... */ }); + +// 3. Write Controller +router.post('/tasks', async (req, res) => { + const task = await Task.create(req.body); + res.json(task); +}); + +// 4. Add Validation +const validateTask = (req, res, next) => { + if (!req.body.title) return res.status(400).json({ error: 'Title required' }); + next(); +}; + +// Total: 4 files, ~150 lines of code +``` + +### ObjectStack Protocol + +```typescript +// Everything in ONE definition +export const Task = ObjectSchema.create({ + name: 'task', + label: 'Task', + fields: { + title: Field.text({ label: 'Title', required: true }), + status: Field.select({ + label: 'Status', + options: ['todo', 'in_progress', 'done'] + }), + due_date: Field.date({ label: 'Due Date' }), + } +}); + +// That's it! You get: +// ✅ TypeScript types +// ✅ Runtime validation (Zod) +// ✅ REST API (CRUD operations) +// ✅ GraphQL API (optional) +// ✅ Database schema +// ✅ Admin UI + +// Total: 1 file, ~15 lines of code +``` + +## Field Types You Know and Love + +ObjectStack provides **23+ field types** with automatic validation: + +| ObjectStack Type | Similar To | Features | +| :--- | :--- | :--- | +| `Field.text()` | `VARCHAR` / `String` | Max length, pattern validation | +| `Field.number()` | `INTEGER` / `Number` | Min, max, precision | +| `Field.boolean()` | `BOOLEAN` | True/false | +| `Field.date()` | `DATE` | Date only | +| `Field.datetime()` | `TIMESTAMP` | Date + time | +| `Field.select()` | `ENUM` | Predefined options | +| `Field.lookup()` | `FOREIGN KEY` | Relations | +| `Field.json()` | `JSON` / `JSONB` | Structured data | + +### Example: Complex Data Model + +```typescript +import { ObjectSchema, Field } from '@objectstack/spec'; + +export const Order = ObjectSchema.create({ + name: 'order', + label: 'Order', + nameField: 'order_number', + + fields: { + // Auto-generated unique ID + order_number: Field.autonumber({ + label: 'Order #', + format: 'ORD-{0000}', + }), + + // Foreign key relationship + customer: Field.lookup({ + label: 'Customer', + reference: 'customer', + displayField: 'company_name', + required: true, + }), + + // Multi-select for tags + tags: Field.multiselect({ + label: 'Tags', + options: ['urgent', 'wholesale', 'repeat_customer'], + }), + + // Decimal for currency + total_amount: Field.currency({ + label: 'Total Amount', + precision: 2, + min: 0, + }), + + // Calculated field + discount_percentage: Field.formula({ + label: 'Discount %', + returnType: 'number', + expression: '(original_amount - total_amount) / original_amount * 100', + }), + + // JSON for flexible data + metadata: Field.json({ + label: 'Metadata', + schema: z.object({ + source: z.enum(['web', 'mobile', 'api']), + utm_campaign: z.string().optional(), + }), + }), + }, +}); +``` + +## Business Logic: Validation & Workflows + +### Validation Rules + +Like database constraints, but more powerful: + +```typescript +import { ValidationRule } from '@objectstack/spec'; + +export const orderValidations = [ + // Business rule: Discount cannot exceed 50% + ValidationRule.create({ + name: 'max_discount', + object: 'order', + errorMessage: 'Discount cannot exceed 50%', + condition: 'discount_percentage > 50', + }), + + // Cross-field validation + ValidationRule.create({ + name: 'delivery_date_after_order', + object: 'order', + errorMessage: 'Delivery date must be after order date', + condition: 'delivery_date <= order_date', + }), +]; +``` + +### Workflows (Triggers) + +Like database triggers, but declarative: + +```typescript +import { Workflow, WorkflowAction } from '@objectstack/spec'; + +export const orderWorkflow = Workflow.create({ + name: 'notify_on_high_value', + object: 'order', + trigger: 'after_insert', + + // Run when total > 10,000 + condition: 'total_amount > 10000', + + actions: [ + // Send email notification + WorkflowAction.sendEmail({ + to: 'sales@company.com', + subject: 'High-value order created', + body: 'Order {order_number} for ${total_amount} created', + }), + + // Update related record + WorkflowAction.updateField({ + object: 'customer', + recordId: '{customer.id}', + fields: { + last_high_value_order: '{id}', + }, + }), + ], +}); +``` + +## API Generation + +Your ObjectStack definitions automatically generate REST APIs: + +```http +# Auto-generated endpoints +POST /api/v1/objects/order # Create +GET /api/v1/objects/order/:id # Read +PATCH /api/v1/objects/order/:id # Update +DELETE /api/v1/objects/order/:id # Delete +GET /api/v1/objects/order # List with query + +# Advanced queries +GET /api/v1/objects/order?filter[total_amount][gt]=1000 +GET /api/v1/objects/order?sort=-created_at&limit=10 +GET /api/v1/objects/order?include=customer,line_items +``` + +### Query Builder (Type-Safe) + +```typescript +import { Query } from '@objectstack/spec'; + +// Build complex queries +const query = Query.create({ + object: 'order', + + // WHERE clause + filters: { + total_amount: { gt: 1000 }, + status: { in: ['pending', 'processing'] }, + 'customer.country': { eq: 'US' }, + }, + + // JOIN / Include related records + include: ['customer', 'line_items'], + + // ORDER BY + sort: [{ field: 'created_at', direction: 'desc' }], + + // LIMIT / OFFSET + limit: 20, + offset: 0, + + // SELECT (field projection) + fields: ['order_number', 'total_amount', 'customer.company_name'], +}); +``` + +## Database Agnostic + +ObjectStack **abstracts** the database layer: + +```typescript +// Your code (driver-agnostic) +const result = await kernel.query({ + object: 'order', + filters: { status: { eq: 'pending' } }, +}); + +// Works with ANY driver: +// - PostgreSQL Driver +// - MySQL Driver +// - MongoDB Driver +// - Redis Driver +// - In-Memory Driver +// - Your Custom Driver +``` + +### Custom Driver Example + +```typescript +import { Driver, DriverCapabilities } from '@objectstack/spec'; + +export class MyCustomDriver implements Driver { + readonly capabilities: DriverCapabilities = { + queryFilters: ['eq', 'gt', 'lt', 'in'], + queryAggregations: ['count', 'sum', 'avg'], + transactions: true, + }; + + async find(query: Query): Promise { + // Your implementation + } + + async create(object: string, data: Record): Promise { + // Your implementation + } + + // ... more methods +} +``` + +## Advanced: Formula Engine + +ObjectStack includes a **SQL-like formula language**: + +```typescript +// Formulas can reference fields, perform calculations +Field.formula({ + label: 'Calculated Total', + returnType: 'number', + + // Supports: math, logic, dates, text, lookups + expression: ` + IF( + discount_code != NULL, + subtotal * (1 - discount_percentage / 100), + subtotal + ) + shipping_cost + `, +}) +``` + +### Available Formula Functions + +- **Math:** `SUM`, `AVG`, `MIN`, `MAX`, `ROUND`, `ABS` +- **Logic:** `IF`, `AND`, `OR`, `NOT`, `ISNULL` +- **Text:** `CONCAT`, `UPPER`, `LOWER`, `SUBSTRING`, `LEN` +- **Date:** `TODAY`, `NOW`, `DATEADD`, `DATEDIFF`, `YEAR`, `MONTH` +- **Lookup:** `LOOKUP`, `ROLLUP` + +## Testing Your Definitions + +ObjectStack schemas are **Zod schemas**: + +```typescript +import { Task } from './objects/task'; + +// Unit test example +describe('Task Object', () => { + it('should validate required fields', () => { + const result = Task.safeParse({ + title: 'My Task', + status: 'todo', + }); + + expect(result.success).toBe(true); + }); + + it('should reject invalid status', () => { + const result = Task.safeParse({ + title: 'My Task', + status: 'invalid_status', // Not in enum + }); + + expect(result.success).toBe(false); + }); +}); +``` + +## Next Steps for Backend Developers + + + + + + + + +## Migration Guides + +Coming from another framework? We've got you covered: + +- [Prisma → ObjectStack](/docs/migration/prisma) +- [TypeORM → ObjectStack](/docs/migration/typeorm) +- [Sequelize → ObjectStack](/docs/migration/sequelize) +- [Mongoose → ObjectStack](/docs/migration/mongoose) diff --git a/content/docs/quick-start/build-first-app.mdx b/content/docs/quick-start/build-first-app.mdx new file mode 100644 index 000000000..01f33b3bc --- /dev/null +++ b/content/docs/quick-start/build-first-app.mdx @@ -0,0 +1,367 @@ +--- +title: Build Your First App +description: Complete hands-on tutorial - Build a task management application in 10 minutes using ObjectStack Protocol. +--- + +In this tutorial, you'll build a complete task management application with: +- ✅ Task object with title, description, status, and assignee +- ✅ Validation rules +- ✅ Status workflow (Todo → In Progress → Done) +- ✅ List and form views +- ✅ Dashboard with statistics + +**Time to complete:** ~10 minutes +**Prerequisites:** Node.js 18+, basic TypeScript knowledge + +## Step 1: Project Setup + +Create a new project and install dependencies: + +```bash +mkdir task-manager +cd task-manager +npm init -y +npm install typescript zod @objectstack/spec +npx tsc --init +``` + +Create the directory structure: + +```bash +mkdir -p src/{objects,views,workflows} +``` + +## Step 2: Define the Task Object + +Create `src/objects/task.object.ts`: + +```typescript +import { ObjectSchema, Field } from '@objectstack/spec'; + +export const Task = ObjectSchema.create({ + name: 'task', + label: 'Task', + pluralLabel: 'Tasks', + icon: 'check-square', + description: 'Track work items and their status', + + // This field will be used as the record name/title + nameField: 'title', + + // Enable features + enable: { + trackHistory: true, + apiEnabled: true, + searchEnabled: true, + }, + + fields: { + // Text field - the task title + title: Field.text({ + label: 'Title', + required: true, + maxLength: 200, + helpText: 'Brief description of the task', + }), + + // Long text for detailed description + description: Field.textarea({ + label: 'Description', + maxLength: 5000, + rows: 5, + }), + + // Select field for status + status: Field.select({ + label: 'Status', + required: true, + defaultValue: 'todo', + options: [ + { value: 'todo', label: 'To Do', color: 'gray' }, + { value: 'in_progress', label: 'In Progress', color: 'blue' }, + { value: 'done', label: 'Done', color: 'green' }, + ], + }), + + // Select field for priority + priority: Field.select({ + label: 'Priority', + defaultValue: 'medium', + options: [ + { value: 'low', label: 'Low', color: 'gray' }, + { value: 'medium', label: 'Medium', color: 'yellow' }, + { value: 'high', label: 'High', color: 'red' }, + ], + }), + + // Date field for due date + due_date: Field.date({ + label: 'Due Date', + }), + + // Lookup field for assignee (references user object) + assignee: Field.lookup({ + label: 'Assignee', + reference: 'user', + displayField: 'full_name', + }), + + // Boolean field for completed status + completed: Field.boolean({ + label: 'Completed', + defaultValue: false, + }), + + // Formula field - calculates if task is overdue + is_overdue: Field.formula({ + label: 'Is Overdue', + returnType: 'boolean', + expression: 'AND(NOT(completed), due_date < TODAY())', + }), + }, +}); +``` + +## Step 3: Add Validation Rules + +Create `src/workflows/task-validation.ts`: + +```typescript +import { ValidationRule } from '@objectstack/spec'; + +export const taskValidations = [ + // Validation: Due date must be in the future for new tasks + ValidationRule.create({ + name: 'future_due_date', + object: 'task', + active: true, + errorMessage: 'Due date must be in the future', + condition: 'AND(ISNEW(), due_date < TODAY())', + }), + + // Validation: Completed tasks must have status = 'done' + ValidationRule.create({ + name: 'completed_status_match', + object: 'task', + active: true, + errorMessage: 'Completed tasks must have status "Done"', + condition: 'AND(completed, status != "done")', + }), +]; +``` + +## Step 4: Create a List View + +Create `src/views/task-list.view.ts`: + +```typescript +import { ListView } from '@objectstack/spec'; + +export const TaskListView = ListView.create({ + name: 'all_tasks', + label: 'All Tasks', + object: 'task', + + // Default view type + viewType: 'grid', + + // Columns to display + columns: [ + { field: 'title', width: 300 }, + { field: 'status', width: 150 }, + { field: 'priority', width: 120 }, + { field: 'assignee', width: 200 }, + { field: 'due_date', width: 150 }, + { field: 'is_overdue', width: 120 }, + ], + + // Default sorting + sorting: [ + { field: 'due_date', direction: 'asc' }, + ], + + // Default filter + filters: { + completed: { eq: false }, + }, + + // Enable features + enableSearch: true, + enableFilters: true, + enableBulkActions: true, +}); +``` + +## Step 5: Create a Kanban View + +Create `src/views/task-kanban.view.ts`: + +```typescript +import { ListView } from '@objectstack/spec'; + +export const TaskKanbanView = ListView.create({ + name: 'task_kanban', + label: 'Task Board', + object: 'task', + + viewType: 'kanban', + + // Group by status field + kanbanConfig: { + groupByField: 'status', + cardFields: ['title', 'priority', 'assignee', 'due_date'], + + // Define the columns + columns: [ + { value: 'todo', label: 'To Do' }, + { value: 'in_progress', label: 'In Progress' }, + { value: 'done', label: 'Done' }, + ], + }, +}); +``` + +## Step 6: Create a Form View + +Create `src/views/task-form.view.ts`: + +```typescript +import { FormView } from '@objectstack/spec'; + +export const TaskFormView = FormView.create({ + name: 'task_edit', + label: 'Task Details', + object: 'task', + + // Form layout + layout: { + sections: [ + { + label: 'Basic Information', + columns: 2, + fields: ['title', 'description'], + }, + { + label: 'Scheduling', + columns: 2, + fields: ['status', 'priority', 'due_date', 'assignee'], + }, + { + label: 'Completion', + columns: 1, + fields: ['completed', 'is_overdue'], + }, + ], + }, + + // Read-only fields (formula fields are auto read-only) + readOnlyFields: ['is_overdue'], +}); +``` + +## Step 7: Bundle Everything + +Create `src/index.ts`: + +```typescript +import { Manifest } from '@objectstack/spec'; +import { Task } from './objects/task.object'; +import { taskValidations } from './workflows/task-validation'; +import { TaskListView, TaskKanbanView } from './views/task-list.view'; +import { TaskFormView } from './views/task-form.view'; + +export const manifest = Manifest.create({ + name: 'task_manager', + version: '1.0.0', + label: 'Task Manager', + description: 'Simple task management application', + + // Register all components + objects: [Task], + validations: taskValidations, + views: { + list: [TaskListView, TaskKanbanView], + form: [TaskFormView], + }, +}); +``` + +## Step 8: Build and Validate + +Add to `package.json`: + +```json +{ + "scripts": { + "build": "tsc", + "validate": "node -e \"require('./dist/index.js')\"" + } +} +``` + +Build and validate: + +```bash +npm run build +npm run validate +``` + +✅ **Congratulations!** You've built your first ObjectStack application. + +## What You've Learned + +- ✅ How to define **Objects** with various field types +- ✅ How to add **validation rules** with formulas +- ✅ How to create **multiple view types** (Grid, Kanban, Form) +- ✅ How to use **formula fields** for calculations +- ✅ How to enable **platform features** (history tracking, search) + +## Next Steps + + + + + + + + +## Troubleshooting + +### TypeScript Errors + +Make sure your `tsconfig.json` has: + +```json +{ + "compilerOptions": { + "strict": true, + "esModuleInterop": true, + "moduleResolution": "node" + } +} +``` + +### Schema Validation Errors + +All schemas are validated at build time using Zod. Check the error message for which field failed validation. + +## Full Code + +The complete source code for this tutorial is available at: +- [GitHub: examples/task-manager](https://github.com/objectstack-ai/spec/tree/main/examples/task-manager) diff --git a/content/docs/quick-start/frontend-developers.mdx b/content/docs/quick-start/frontend-developers.mdx new file mode 100644 index 000000000..dfda9b739 --- /dev/null +++ b/content/docs/quick-start/frontend-developers.mdx @@ -0,0 +1,554 @@ +--- +title: For Frontend Developers +description: Learn ObjectStack from a frontend perspective - focus on UI configuration, server-driven UI, and component rendering. +--- + +Welcome frontend developers! If you're used to building admin panels, dashboards, or data-heavy UIs, ObjectStack will feel like a productivity superpower. + +## Core Concept + +ObjectStack uses **Server-Driven UI (SDUI)** - instead of hardcoding components, you define UI as JSON configurations that the renderer interprets. + +``` +Traditional: Code React components → Build → Deploy +ObjectStack: Define UI JSON → Instant Update (no rebuild!) +``` + +## Quick Comparison + +### Traditional React + +```tsx +// 1. Build data grid component +import { DataGrid } from '@mui/x-data-grid'; + +function TaskList() { + const [tasks, setTasks] = useState([]); + + useEffect(() => { + fetch('/api/tasks').then(r => r.json()).then(setTasks); + }, []); + + return ( + + ); +} + +// 2. Build form component +function TaskForm({ taskId }) { + const [task, setTask] = useState({}); + + const handleSubmit = async (e) => { + e.preventDefault(); + await fetch(`/api/tasks/${taskId}`, { + method: 'PATCH', + body: JSON.stringify(task), + }); + }; + + return ( +
+ setTask({ ...task, title: e.target.value })} + /> + {/* More fields... */} + +
+ ); +} + +// Total: 2 components, ~100 lines of code +``` + +### ObjectStack Protocol + +```typescript +// Define UI as JSON - Renderer handles everything +export const TaskListView = ListView.create({ + name: 'all_tasks', + label: 'All Tasks', + object: 'task', + + viewType: 'grid', + columns: [ + { field: 'title', width: 200 }, + { field: 'status', width: 150 }, + { field: 'due_date', width: 150 }, + ], + pageSize: 25, +}); + +export const TaskFormView = FormView.create({ + name: 'task_edit', + label: 'Edit Task', + object: 'task', + + layout: { + sections: [ + { + label: 'Details', + fields: ['title', 'status', 'due_date'], + }, + ], + }, +}); + +// Total: 2 definitions, ~20 lines +// ✅ Data fetching handled automatically +// ✅ State management handled automatically +// ✅ Validation handled automatically +// ✅ Loading/Error states handled automatically +``` + +## View Types + +ObjectStack provides **5 pre-built view types**: + +### 1. Grid View (Data Table) + +```typescript +const TaskGrid = ListView.create({ + name: 'task_grid', + object: 'task', + viewType: 'grid', + + columns: [ + { field: 'title', width: 300, sortable: true }, + { field: 'status', width: 120, filterable: true }, + { field: 'assignee', width: 200 }, + ], + + // Features + enableSearch: true, + enableFilters: true, + enableExport: true, + enableBulkActions: true, + + // Default state + defaultSort: [{ field: 'created_at', direction: 'desc' }], + pageSize: 50, +}); +``` + +**Rendered Output:** +- Sortable columns +- Filterable columns +- Search bar +- Pagination +- Bulk select + actions +- Export to CSV/Excel + +### 2. Kanban View (Board) + +```typescript +const TaskKanban = ListView.create({ + name: 'task_board', + object: 'task', + viewType: 'kanban', + + kanbanConfig: { + groupByField: 'status', + + columns: [ + { value: 'todo', label: 'To Do', color: 'gray' }, + { value: 'in_progress', label: 'In Progress', color: 'blue' }, + { value: 'done', label: 'Done', color: 'green' }, + ], + + cardFields: ['title', 'assignee', 'due_date'], + + // Drag & drop enabled by default + enableDragDrop: true, + }, +}); +``` + +**Rendered Output:** +- Drag & drop cards between columns +- Visual grouping +- Card customization +- Swimlanes (optional) + +### 3. Calendar View + +```typescript +const TaskCalendar = ListView.create({ + name: 'task_calendar', + object: 'task', + viewType: 'calendar', + + calendarConfig: { + dateField: 'due_date', + titleField: 'title', + + // Color-code events + colorField: 'priority', + colorMapping: { + high: 'red', + medium: 'yellow', + low: 'gray', + }, + + // Views: day, week, month + defaultView: 'month', + }, +}); +``` + +### 4. Gantt View (Timeline) + +```typescript +const ProjectGantt = ListView.create({ + name: 'project_timeline', + object: 'task', + viewType: 'gantt', + + ganttConfig: { + startDateField: 'start_date', + endDateField: 'end_date', + progressField: 'completion_percentage', + + // Dependencies + dependenciesField: 'blocked_by', + + // Grouping + groupByField: 'project', + }, +}); +``` + +### 5. Form View + +```typescript +const TaskForm = FormView.create({ + name: 'task_form', + object: 'task', + + layout: { + sections: [ + { + label: 'Basic Info', + columns: 2, // 2-column layout + fields: ['title', 'description'], + }, + { + label: 'Assignment', + columns: 2, + fields: ['assignee', 'status', 'priority', 'due_date'], + }, + { + label: 'Advanced', + collapsible: true, // Expandable section + fields: ['tags', 'metadata'], + }, + ], + }, + + // Conditional visibility + fieldVisibility: { + assignee: "status != 'todo'", // Show only when not todo + }, + + // Read-only fields + readOnlyFields: ['created_by', 'created_at'], +}); +``` + +## Dashboard & Analytics + +Build dashboards with widgets: + +```typescript +import { Dashboard, Widget } from '@objectstack/spec'; + +export const TaskDashboard = Dashboard.create({ + name: 'task_overview', + label: 'Task Overview', + + // Grid layout (12 columns) + layout: { + rows: [ + { + widgets: [ + // KPI Card - 3 columns wide + Widget.metric({ + id: 'total_tasks', + title: 'Total Tasks', + object: 'task', + aggregation: 'count', + width: 3, + }), + + // KPI Card with trend + Widget.metric({ + id: 'completed_tasks', + title: 'Completed This Month', + object: 'task', + aggregation: 'count', + filters: { + status: { eq: 'done' }, + completed_at: { gte: 'START_OF_MONTH()' }, + }, + width: 3, + showTrend: true, + }), + ], + }, + { + widgets: [ + // Chart - 6 columns + Widget.chart({ + id: 'tasks_by_status', + title: 'Tasks by Status', + chartType: 'pie', + object: 'task', + groupBy: 'status', + aggregation: 'count', + width: 6, + }), + + // Chart - 6 columns + Widget.chart({ + id: 'tasks_over_time', + title: 'Tasks Created Over Time', + chartType: 'line', + object: 'task', + xAxis: { field: 'created_at', interval: 'day' }, + yAxis: { aggregation: 'count' }, + width: 6, + }), + ], + }, + { + widgets: [ + // Embedded list view - full width + Widget.listView({ + id: 'recent_tasks', + title: 'Recent Tasks', + view: 'all_tasks', + limit: 10, + width: 12, + }), + ], + }, + ], + }, +}); +``` + +## Actions & Interactions + +Add buttons and actions to your views: + +```typescript +import { Action } from '@objectstack/spec'; + +// Custom button in list view +const exportAction = Action.url({ + name: 'export_csv', + label: 'Export to CSV', + url: '/api/export/task?format=csv', + icon: 'download', + + // Show in toolbar + displayLocation: 'toolbar', +}); + +// Quick action button +const approveAction = Action.update({ + name: 'approve_task', + label: 'Approve', + icon: 'check', + + // Update fields + updates: { + status: 'approved', + approved_by: '{$User.Id}', + approved_at: '{$Now}', + }, + + // Confirmation dialog + confirmation: { + title: 'Approve Task?', + message: 'Are you sure you want to approve this task?', + }, +}); + +// Launch a flow/modal +const assignAction = Action.flow({ + name: 'assign_task', + label: 'Assign to Me', + flowName: 'assign_task_flow', + + // Pass context + parameters: { + taskId: '{recordId}', + userId: '{$User.Id}', + }, +}); +``` + +## Theming & Styling + +Customize the look and feel: + +```typescript +import { Theme, ColorPalette } from '@objectstack/spec'; + +export const customTheme = Theme.create({ + colors: { + primary: '#3B82F6', + secondary: '#8B5CF6', + success: '#10B981', + warning: '#F59E0B', + error: '#EF4444', + }, + + typography: { + fontFamily: 'Inter, sans-serif', + fontSize: { + xs: '12px', + sm: '14px', + base: '16px', + lg: '18px', + xl: '20px', + }, + }, + + spacing: { + unit: 8, // 8px base unit + }, + + borderRadius: { + sm: '4px', + md: '8px', + lg: '12px', + }, +}); +``` + +## App Navigation + +Define your app's navigation structure: + +```typescript +import { App, NavigationItem } from '@objectstack/spec'; + +export const myApp = App.create({ + name: 'task_manager', + label: 'Task Manager', + + branding: { + logo: '/logo.svg', + primaryColor: '#3B82F6', + }, + + navigation: [ + // Dashboard link + NavigationItem.dashboard({ + label: 'Home', + icon: 'home', + dashboard: 'task_overview', + }), + + // Object link (auto-generates CRUD pages) + NavigationItem.object({ + label: 'Tasks', + icon: 'check-square', + object: 'task', + defaultView: 'all_tasks', + }), + + // Navigation group + NavigationItem.group({ + label: 'Reports', + icon: 'bar-chart', + items: [ + NavigationItem.page({ + label: 'Task Analytics', + page: 'task_analytics', + }), + ], + }), + + // External URL + NavigationItem.url({ + label: 'Help', + icon: 'help-circle', + url: 'https://docs.objectstack.dev', + openInNewTab: true, + }), + ], +}); +``` + +## Rendering the UI + +Your renderer consumes the UI definitions: + +```tsx +// Example: React Renderer (conceptual) +import { ObjectStackRenderer } from '@objectstack/react-renderer'; +import { TaskListView, TaskFormView } from './views'; + +function App() { + return ( + + ); +} +``` + +## Benefits for Frontend Developers + +✅ **No Boilerplate:** No more `useState`, `useEffect`, form handlers +✅ **Type-Safe:** Full TypeScript support +✅ **Instant Updates:** Change UI JSON, see results without rebuilding +✅ **Consistent UX:** All views follow the same design system +✅ **Responsive:** Mobile-first, works on all screen sizes +✅ **Accessible:** WCAG 2.1 AA compliant out of the box + +## Next Steps for Frontend Developers + + + + + + + diff --git a/content/docs/quick-start/meta.json b/content/docs/quick-start/meta.json new file mode 100644 index 000000000..c76c281c1 --- /dev/null +++ b/content/docs/quick-start/meta.json @@ -0,0 +1,9 @@ +{ + "title": "Quick Start", + "pages": [ + "build-first-app", + "backend-developers", + "frontend-developers", + "architects" + ] +} diff --git a/content/docs/specifications/data/index.mdx b/content/docs/specifications/data/index.mdx new file mode 100644 index 000000000..0f15f9dac --- /dev/null +++ b/content/docs/specifications/data/index.mdx @@ -0,0 +1,149 @@ +--- +title: Data Protocol (ObjectQL) +description: Comprehensive specification for the ObjectStack Data Layer - defining schemas, queries, and business logic. +--- + +import { Database, GitBranch, Shield, Zap } from 'lucide-react'; + +The **Data Protocol (ObjectQL)** is the foundation of ObjectStack. It defines how to: +- Express data structures (Objects, Fields) +- Query data (AST-based abstraction) +- Implement business logic (Formulas, Workflows, Validation) +- Secure data (Permissions, Sharing Rules) + +## Core Components + + + } + title="Architecture" + href="/docs/specifications/data/architecture" + description="High-level overview of the Data Layer design and philosophy" + /> + } + title="Schema Definition" + href="/docs/specifications/data/schema-definition" + description="How to define Objects, Fields, and Relationships" + /> + } + title="Query AST Structure" + href="/docs/specifications/data/ast-structure" + description="Abstract Syntax Tree for database-agnostic queries" + /> + } + title="Advanced Types" + href="/docs/specifications/data/advanced-types" + description="Complex field types and their implementations" + /> + + +## Specifications + +### Core Specifications + +1. **[Architecture Overview](/docs/specifications/data/architecture)** + - Design principles + - Layer responsibilities + - Driver model + +2. **[Schema Definition](/docs/specifications/data/schema-definition)** + - Object schema structure + - Field type definitions + - Relationship modeling + +3. **[Advanced Types](/docs/specifications/data/advanced-types)** + - Formula fields + - Lookup relationships + - Master-detail relationships + - Junction objects (many-to-many) + +### Query Layer + +4. **[AST Structure](/docs/specifications/data/ast-structure)** + - Query Abstract Syntax Tree + - Filter expressions + - Aggregations + - Joins and includes + +5. **[Analytics Protocol](/docs/specifications/data/analytics-protocol)** + - Grouping and aggregation + - Calculated fields + - Time-series queries + +### System Specifications + +6. **[Transaction Model](/docs/specifications/data/transaction-model)** + - ACID guarantees + - Isolation levels + - Distributed transactions + +7. **[Wire Protocol](/docs/specifications/data/wire-protocol)** + - Data serialization format + - Network protocol + - Compression and optimization + +## Quick Links + +### For Implementers + +Building a driver for ObjectStack? Start here: +- [Driver Interface](/docs/references/system/Driver) +- [Query Compiler](/docs/guides/custom-driver) +- [Test Suite](/docs/guides/driver-testing) + +### For Users + +Using ObjectStack to build applications? See: +- [Field Types Guide](/docs/guides/field-types) +- [Query Examples](/docs/guides/querying-data) +- [Business Logic](/docs/guides/workflows-validation) + +## Design Principles + +The Data Protocol follows these core principles: + +### 1. Database Agnostic + +ObjectQL queries compile to **any** backend: +``` +ObjectQL Query → AST → Driver Translates → SQL/NoSQL/API +``` + +### 2. Type-Safe + +All schemas are Zod schemas with TypeScript inference: +```typescript +export const TaskSchema = ObjectSchema.create({ ... }); +type Task = z.infer; +``` + +### 3. Declarative + +Express **what you want**, not **how to get it**: +```typescript +// Declarative query +Query.create({ + object: 'task', + filters: { status: { eq: 'open' } }, +}); + +// Driver handles: SELECT * FROM tasks WHERE status = 'open' +``` + +### 4. Composable + +Build complex queries from simple building blocks: +```typescript +const baseQuery = { object: 'task' }; +const withFilter = { ...baseQuery, filters: { ... } }; +const withSort = { ...withFilter, sort: [...] }; +``` + +## Related Documentation + +- **[UI Protocol](/docs/specifications/ui/sdui-protocol)** - How to render data +- **[System Protocol](/docs/specifications/server/kernel-architecture)** - Runtime environment +- **[API Protocol](/docs/references/api/envelopes/BaseResponse)** - REST/GraphQL contracts diff --git a/content/docs/specifications/data/meta.json b/content/docs/specifications/data/meta.json index 0fb086efa..0fde0b361 100644 --- a/content/docs/specifications/data/meta.json +++ b/content/docs/specifications/data/meta.json @@ -1,6 +1,7 @@ { "title": "ObjectQL", "pages": [ + "index", "architecture", "schema-definition", "advanced-types", diff --git a/content/docs/specifications/index.mdx b/content/docs/specifications/index.mdx new file mode 100644 index 000000000..dff498284 --- /dev/null +++ b/content/docs/specifications/index.mdx @@ -0,0 +1,245 @@ +--- +title: Protocol Specifications +description: Complete technical specifications for the ObjectStack Protocol - the "constitution" of the metadata-driven platform. +--- + +import { Database, Layout, Server } from 'lucide-react'; + +The ObjectStack Protocol is defined through three core specifications that work together to create a complete metadata-driven platform. + +## The Three-Layer Architecture + + + } + title="Data Protocol (ObjectQL)" + href="/docs/specifications/data" + description="Define data structures, queries, and business logic. Database-agnostic abstraction layer." + /> + } + title="UI Protocol (ObjectUI)" + href="/docs/specifications/ui" + description="Server-driven UI definitions. Express interfaces as JSON, not code." + /> + } + title="System Protocol (ObjectOS)" + href="/docs/specifications/server" + description="Runtime kernel, plugins, security, and integration. The platform foundation." + /> + + +## What Are Specifications? + +These documents define the **ObjectStack Protocol** - the rules and standards that all implementations must follow. + +Think of them as: +- **The SQL Specification** → Defines what SQL should do +- **The HTTP Specification** → Defines how web communication works +- **The ObjectStack Specification** → Defines how metadata-driven platforms work + +## Who Should Read These? + +### Protocol Implementers + +Building an ObjectStack implementation? + +- **Kernel Developers:** Implement the runtime engine +- **Driver Developers:** Connect new databases (PostgreSQL, MongoDB, etc.) +- **Renderer Developers:** Build UI renderers (React, Vue, Flutter) + +Start with: +1. [System Protocol - Kernel Architecture](/docs/specifications/server/kernel-architecture) +2. [Data Protocol - Architecture](/docs/specifications/data/architecture) +3. [UI Protocol - SDUI Protocol](/docs/specifications/ui/sdui-protocol) + +### Platform Architects + +Evaluating ObjectStack for your organization? + +- **CTOs:** Understand architectural decisions +- **Tech Leads:** Evaluate scalability and security +- **Solution Architects:** Design integration patterns + +Start with: +1. [Data Protocol - Architecture](/docs/specifications/data/architecture) +2. [System Protocol - Permission Governance](/docs/specifications/server/permission-governance) +3. [UI Protocol - Component Schema](/docs/specifications/ui/component-schema) + +### Advanced Users + +Building complex applications with ObjectStack? + +- **Power Users:** Understand limits and capabilities +- **Custom Plugin Developers:** Extend the platform +- **Integration Engineers:** Connect external systems + +Start with: +1. [Data Protocol - AST Structure](/docs/specifications/data/ast-structure) +2. [System Protocol - Plugin Manifest](/docs/specifications/server/plugin-manifest) +3. [UI Protocol - Action Triggers](/docs/specifications/ui/action-triggers) + +## Specification Structure + +Each specification follows a consistent structure: + +### 1. Overview + +- **Purpose:** What problem does this solve? +- **Design Principles:** What are the guiding principles? +- **Architecture Diagram:** Visual representation + +### 2. Core Concepts + +- **Schemas:** Zod definitions +- **Types:** TypeScript interfaces +- **Examples:** Real-world usage + +### 3. Implementation Notes + +- **Driver Responsibilities:** What must drivers implement? +- **Renderer Responsibilities:** What must renderers handle? +- **Kernel Integration:** How does it fit into the system? + +### 4. Reference + +- **API Documentation:** Complete type reference +- **Test Suite:** Compliance tests +- **Migration Guide:** Version upgrade paths + +## Key Design Principles + +### 1. Protocol Over Framework + +ObjectStack is a **protocol**, not a framework: + +``` +Protocol Definition (Zod schemas) + ↓ +Multiple Implementations + • Node.js Kernel + • Go Kernel + • Python Kernel + • Custom Kernel +``` + +### 2. Declarative Over Imperative + +Express **intent**, not **implementation**: + +```typescript +// What you want (declarative) +const Task = ObjectSchema.create({ + fields: { + title: Field.text({ required: true }), + } +}); + +// How to do it (handled by kernel) +// ✓ Generate SQL schema +// ✓ Create API endpoints +// ✓ Validate requests +// ✓ Render UI +``` + +### 3. Type-Safe by Default + +All schemas are Zod + TypeScript: + +```typescript +// Source: Zod schema +export const TaskSchema = z.object({ ... }); + +// Derived: TypeScript type +type Task = z.infer; + +// Derived: JSON Schema +const jsonSchema = zodToJsonSchema(TaskSchema); +``` + +### 4. Database Agnostic + +ObjectQL compiles to any backend: + +``` +ObjectQL Query → AST → Driver Translates + ↓ + SQL | NoSQL | API +``` + +### 5. Extensible by Design + +Plugin architecture for unlimited extensibility: + +```typescript +// Core is minimal +const kernel = new Kernel(); + +// Add capabilities via plugins +kernel.loadPlugin(PostgresDriver); +kernel.loadPlugin(AuthPlugin); +kernel.loadPlugin(AnalyticsPlugin); +``` + +## Versioning & Compatibility + +ObjectStack follows **Semantic Versioning** (semver): + +``` +MAJOR.MINOR.PATCH + 1 . 0 . 0 +``` + +- **MAJOR:** Breaking changes to protocol +- **MINOR:** New features (backward compatible) +- **PATCH:** Bug fixes + +### Compatibility Guarantee + +- **Same MAJOR version:** 100% compatible +- **Different MAJOR:** May require migration + +Example: +- Schema written for **v1.x.x** works on **v1.5.0** ✅ +- Schema written for **v1.x.x** may need updates for **v2.0.0** ⚠️ + +## Specification Roadmap + +### Current (v0.x) + +- ✅ Data Protocol (ObjectQL) - Core schemas +- ✅ UI Protocol (ObjectUI) - View definitions +- ✅ System Protocol (ObjectOS) - Kernel architecture +- 🚧 AI Protocol - Agent definitions +- 🚧 API Protocol - REST/GraphQL contracts + +### Future (v1.x) + +- 📋 Real-time Protocol - WebSocket/SSE specifications +- 📋 Offline Protocol - Sync and conflict resolution +- 📋 Search Protocol - Full-text search abstraction +- 📋 Analytics Protocol - Advanced reporting + +## Contributing to Specifications + +Want to propose changes or additions? + +1. **Read:** [Contributing Guide](https://github.com/objectstack-ai/spec/blob/main/CONTRIBUTING.md) +2. **Discuss:** [GitHub Discussions](https://github.com/objectstack-ai/spec/discussions) +3. **Propose:** [Submit an RFC](https://github.com/objectstack-ai/spec/issues/new?template=rfc.md) + +### RFC Process + +1. **Draft:** Write RFC document +2. **Discussion:** Community feedback (2 weeks) +3. **Review:** Core team review +4. **Decision:** Accept, Reject, or Iterate +5. **Implementation:** Update specs + reference implementation + +## Related Documentation + +- **[Concepts](/docs/concepts/architecture)** - High-level philosophy +- **[Guides](/docs/guides/getting-started)** - Practical how-to guides +- **[References](/docs/references/data/core/Object)** - Complete API documentation +- **[Examples](https://github.com/objectstack-ai/spec/tree/main/examples)** - Reference implementations diff --git a/content/docs/specifications/meta.json b/content/docs/specifications/meta.json index 042574aa1..355c7cbd0 100644 --- a/content/docs/specifications/meta.json +++ b/content/docs/specifications/meta.json @@ -2,6 +2,7 @@ "title": "Specifications", "root": true, "pages": [ + "index", "data", "ui", "server" diff --git a/content/docs/specifications/server/index.mdx b/content/docs/specifications/server/index.mdx new file mode 100644 index 000000000..e1b4c5da6 --- /dev/null +++ b/content/docs/specifications/server/index.mdx @@ -0,0 +1,382 @@ +--- +title: System Protocol (ObjectOS) +description: Comprehensive specification for the ObjectStack System Layer - kernel architecture, plugins, and runtime environment. +--- + +import { Cpu, Package, Shield, Zap } from 'lucide-react'; + +The **System Protocol (ObjectOS)** defines the runtime environment for ObjectStack applications. It specifies: +- Kernel architecture and lifecycle +- Plugin discovery and loading +- Authentication and authorization +- Integration and webhooks +- Audit and compliance + +## Core Components + + + } + title="Kernel Architecture" + href="/docs/specifications/server/kernel-architecture" + description="Core runtime engine that orchestrates all components" + /> + } + title="Plugin Manifest" + href="/docs/specifications/server/plugin-manifest" + description="Package structure and plugin loading mechanism" + /> + } + title="Permission Governance" + href="/docs/specifications/server/permission-governance" + description="Multi-layered access control and security" + /> + } + title="REST API" + href="/docs/specifications/server/rest-api" + description="Auto-generated API specification" + /> + + +## Specifications + +### Core System + +1. **[Kernel Architecture](/docs/specifications/server/kernel-architecture)** + - Kernel design and responsibilities + - Component lifecycle + - Event system + - Dependency injection + +2. **[Plugin Manifest](/docs/specifications/server/plugin-manifest)** + - Manifest structure (`objectstack.config.ts`) + - Plugin metadata + - Dependencies and versioning + +3. **[Workflow Engine](/docs/specifications/server/workflow-engine)** + - Trigger types (before/after insert/update/delete) + - Action execution + - Error handling + +### Security & Compliance + +4. **[Permission Governance](/docs/specifications/server/permission-governance)** + - Object-level permissions + - Field-level security + - Row-level sharing + - Territory management + +5. **[Audit & Compliance](/docs/specifications/server/audit-compliance)** + - Field history tracking + - Login history + - API usage logs + - Compliance reports (GDPR, SOC2) + +### Integration + +6. **[Automation Rules](/docs/specifications/server/automation-rules)** + - Field updates + - Email alerts + - Process automation + +7. **[Integration & ETL](/docs/specifications/server/integration-etl)** + - Webhook definitions + - External API calls + - Data transformation + - Batch processing + +### API Layer + +8. **[REST API](/docs/specifications/server/rest-api)** + - Endpoint structure + - Request/Response format + - Authentication + - Rate limiting + +## Kernel Architecture + +The Kernel is the central orchestrator of an ObjectStack application: + +``` +┌─────────────────────────────────────────┐ +│ Kernel │ +├─────────────────────────────────────────┤ +│ • Plugin Registry │ +│ • Driver Registry │ +│ • Event Bus │ +│ • Permission Engine │ +│ • Workflow Engine │ +└─────────────────────────────────────────┘ + ↓ ↓ ↓ + [Plugins] [Drivers] [Extensions] +``` + +### Kernel Responsibilities + +1. **Plugin Management:** + - Load and initialize plugins + - Resolve dependencies + - Hot-reload support + +2. **Request Routing:** + - API request handling + - Query execution + - Response formatting + +3. **Security:** + - Authentication verification + - Permission checking + - Data encryption + +4. **Event Coordination:** + - Publish/subscribe events + - Trigger workflow actions + - Audit logging + +## Plugin System + +ObjectStack uses a **plugin architecture** inspired by Eclipse RCP and Kubernetes Operators. + +### Plugin Structure + +```typescript +export const MyPlugin: Plugin = { + name: 'my-plugin', + version: '1.0.0', + + // Dependencies + requires: ['core-plugin@^1.0.0'], + + // Lifecycle hooks + onLoad(kernel: IKernel) { + // Register components + kernel.registerDriver('custom', new CustomDriver()); + }, + + onUnload() { + // Cleanup + }, + + // Provided capabilities + provides: { + drivers: [CustomDriver], + apis: [CustomAPI], + }, +}; +``` + +### Plugin Types + +| Plugin Type | Purpose | Examples | +| :--- | :--- | :--- | +| **Driver** | Database connectivity | PostgreSQL, MongoDB, Redis | +| **Auth Provider** | Authentication | OAuth, SAML, LDAP | +| **Renderer** | UI rendering | React, Vue, Flutter | +| **Integration** | External systems | Stripe, SendGrid, Twilio | +| **Analytics** | Reporting engines | Metabase, Superset | + +## Permission System + +Multi-layered access control: + +### Layer 1: Object Permissions + +```typescript +Permission.create({ + profile: 'sales_user', + object: 'opportunity', + create: true, + read: true, + update: { criteria: 'OwnerId = $User.Id' }, + delete: false, +}); +``` + +### Layer 2: Field Security + +```typescript +FieldPermission.create({ + profile: 'sales_user', + object: 'account', + field: 'annual_revenue', + read: false, + edit: false, +}); +``` + +### Layer 3: Record Sharing + +```typescript +SharingRule.create({ + object: 'account', + sharedTo: 'sales_team', + accessLevel: 'read', + criteria: { region: 'US' }, +}); +``` + +## Workflow Engine + +Execute business logic automatically: + +```typescript +Workflow.create({ + name: 'notify_manager', + object: 'opportunity', + trigger: 'after_insert', + + condition: 'Amount > 100000', + + actions: [ + WorkflowAction.sendEmail({ + to: '{Owner.Manager.Email}', + subject: 'Large opportunity created', + }), + + WorkflowAction.updateField({ + field: 'Status', + value: 'Requires Approval', + }), + ], +}); +``` + +### Trigger Types + +- `before_insert` - Before creating record +- `after_insert` - After creating record +- `before_update` - Before updating record +- `after_update` - After updating record +- `before_delete` - Before deleting record +- `after_delete` - After deleting record + +## REST API Structure + +Auto-generated RESTful API: + +```http +# CRUD Operations +POST /api/v1/objects/:object # Create +GET /api/v1/objects/:object/:id # Read +PATCH /api/v1/objects/:object/:id # Update +DELETE /api/v1/objects/:object/:id # Delete + +# List & Query +GET /api/v1/objects/:object + ?filter[field][operator]=value + &sort=field:direction + &limit=20 + &offset=0 + &include=related_object + +# Bulk Operations +POST /api/v1/objects/:object/bulk # Bulk create/update +DELETE /api/v1/objects/:object/bulk # Bulk delete + +# Metadata +GET /api/v1/metadata/objects # List all objects +GET /api/v1/metadata/objects/:object # Object schema +``` + +## Audit & Compliance + +### Field History Tracking + +```typescript +Object.create({ + name: 'opportunity', + enable: { + trackHistory: true, + trackedFields: ['Amount', 'Stage', 'CloseDate'], + }, +}); +``` + +**Captures:** +- Who changed the field +- When it was changed +- Old value +- New value + +### Login History + +Track user authentication events: +- Login timestamp +- IP address +- User agent +- Login status (success/failure) +- MFA verification + +### API Usage Logs + +Monitor API consumption: +- Endpoint called +- Request/response size +- Execution time +- User context +- Rate limit status + +## Design Principles + +### 1. Modularity + +Kernel is minimal. Everything else is a plugin: + +``` +Minimal Kernel + Plugins = Full Platform +``` + +### 2. Hot-Swappable + +Plugins can be loaded/unloaded at runtime: + +```typescript +kernel.loadPlugin('analytics-plugin'); +kernel.unloadPlugin('old-integration'); +``` + +### 3. Event-Driven + +Components communicate via events: + +```typescript +kernel.on('record.created', (event) => { + // React to record creation +}); +``` + +### 4. Dependency Injection + +Kernel provides services to plugins: + +```typescript +onLoad(kernel: IKernel) { + const logger = kernel.getLogger(); + const cache = kernel.getCache(); +} +``` + +## Quick Links + +### For Implementers + +Building a kernel implementation? Start here: +- [Kernel Interface](/docs/references/types/IKernel) +- [Plugin Development](/docs/guides/plugin-development) +- [Test Suite](/docs/guides/kernel-testing) + +### For Users + +Deploying ObjectStack applications? See: +- [Installation Guide](/docs/guides/installation) +- [Configuration Reference](/docs/guides/configuration) +- [Deployment Guide](/docs/guides/deployment) + +## Related Documentation + +- **[Data Protocol](/docs/specifications/data/architecture)** - Data layer +- **[UI Protocol](/docs/specifications/ui/sdui-protocol)** - UI layer +- **[System Reference](/docs/references/system/config/Manifest)** - Configuration API diff --git a/content/docs/specifications/server/meta.json b/content/docs/specifications/server/meta.json index 661a1dafe..6fc6da8d4 100644 --- a/content/docs/specifications/server/meta.json +++ b/content/docs/specifications/server/meta.json @@ -1,6 +1,7 @@ { "title": "ObjectOS", "pages": [ + "index", "kernel-architecture", "permission-governance", "workflow-engine", diff --git a/content/docs/specifications/ui/index.mdx b/content/docs/specifications/ui/index.mdx new file mode 100644 index 000000000..cf79ecce9 --- /dev/null +++ b/content/docs/specifications/ui/index.mdx @@ -0,0 +1,278 @@ +--- +title: UI Protocol (ObjectUI) +description: Comprehensive specification for the ObjectStack UI Layer - server-driven UI definitions and rendering. +--- + +import { Layout, Monitor, Palette, Zap } from 'lucide-react'; + +The **UI Protocol (ObjectUI)** defines how user interfaces are expressed as metadata. Instead of hardcoding React/Vue components, you define UI as JSON configurations that renderers interpret. + +## Core Concept: Server-Driven UI (SDUI) + +``` +Traditional: Code UI → Build → Deploy → Update Requires Rebuild +ObjectUI: Define JSON → Instant Update → No Rebuild Needed +``` + +## Core Components + + + } + title="SDUI Protocol" + href="/docs/specifications/ui/sdui-protocol" + description="Server-Driven UI architecture and philosophy" + /> + } + title="Component Schema" + href="/docs/specifications/ui/component-schema" + description="How UI components are defined and composed" + /> + } + title="View Protocol" + href="/docs/specifications/ui/view-protocol" + description="List views, forms, and data visualization" + /> + } + title="Layout System" + href="/docs/specifications/ui/layout-system" + description="Grid-based responsive layout engine" + /> + + +## Specifications + +### View Types + +1. **[SDUI Protocol](/docs/specifications/ui/sdui-protocol)** + - Server-Driven UI philosophy + - JSON-based component definitions + - Renderer architecture + +2. **[View Protocol](/docs/specifications/ui/view-protocol)** + - ListView (Grid, Kanban, Calendar, Gantt) + - FormView (Simple, Tabbed, Wizard) + - DetailView (Record pages) + +3. **[Component Schema](/docs/specifications/ui/component-schema)** + - Button, Input, Select components + - Custom component registration + - Component props and events + +### Layout & Styling + +4. **[Layout System](/docs/specifications/ui/layout-system)** + - Grid-based layouts + - Responsive breakpoints + - Flexbox patterns + +5. **[Action Triggers](/docs/specifications/ui/action-triggers)** + - Button actions + - URL navigation + - Flow launches + - Custom actions + +### Analytics & Reporting + +6. **[Report Template](/docs/specifications/ui/report-template)** + - Report types (Tabular, Summary, Matrix) + - Chart configurations + - Dashboard widgets + +## View Types Overview + +### ListView + +Display collections of records in various formats: + +```typescript +ListView.create({ + viewType: 'grid', // or 'kanban' | 'calendar' | 'gantt' + columns: [...], + filters: {...}, + sorting: [...], +}); +``` + +**Supported View Types:** +- **Grid:** Traditional table with sorting, filtering, pagination +- **Kanban:** Drag-and-drop board with swimlanes +- **Calendar:** Timeline view with date-based events +- **Gantt:** Project timeline with dependencies + +### FormView + +Edit individual records with custom layouts: + +```typescript +FormView.create({ + layout: { + sections: [ + { + label: 'Basic Info', + columns: 2, + fields: ['name', 'email'], + }, + ], + }, +}); +``` + +**Features:** +- Multi-section layouts +- Conditional field visibility +- Read-only fields +- Custom validation + +### Dashboard + +Compose widgets for analytics: + +```typescript +Dashboard.create({ + layout: { + rows: [ + { + widgets: [ + Widget.metric({ ... }), + Widget.chart({ ... }), + ], + }, + ], + }, +}); +``` + +**Widget Types:** +- Metric cards (KPIs) +- Charts (Bar, Line, Pie, etc.) +- Embedded list views +- Custom widgets + +## Theming System + +ObjectUI includes a comprehensive theming system: + +```typescript +Theme.create({ + colors: { + primary: '#3B82F6', + secondary: '#8B5CF6', + }, + typography: { + fontFamily: 'Inter, sans-serif', + }, + spacing: { + unit: 8, // 8px grid + }, +}); +``` + +**Customizable:** +- Color palettes +- Typography (fonts, sizes, weights) +- Spacing and sizing +- Border radius +- Shadows +- Z-index layers + +## Navigation + +Define app navigation structure: + +```typescript +App.create({ + navigation: [ + NavigationItem.object({ label: 'Tasks', object: 'task' }), + NavigationItem.dashboard({ label: 'Home', dashboard: 'overview' }), + NavigationItem.group({ + label: 'Reports', + items: [...], + }), + ], +}); +``` + +## Design Principles + +### 1. Declarative Over Imperative + +```typescript +// ❌ Imperative (React) +function TaskList() { + const [tasks, setTasks] = useState([]); + useEffect(() => { /* fetch */ }, []); + return ; +} + +// ✅ Declarative (ObjectUI) +ListView.create({ + object: 'task', + columns: [{ field: 'title' }], +}); +``` + +### 2. Configuration Over Code + +UI changes should not require rebuilding: + +``` +Change Config → Refresh Page → New UI ✅ +Change Code → Rebuild → Redeploy → New UI ❌ +``` + +### 3. Responsive by Default + +All layouts use a 12-column grid system that adapts to screen size: + +```typescript +Widget.metric({ + width: 12, // Mobile: Full width + // Tablet: Auto-adjust + // Desktop: 1/4 width +}); +``` + +### 4. Accessible by Default + +WCAG 2.1 AA compliance out of the box: +- Keyboard navigation +- Screen reader support +- Color contrast ratios +- Focus indicators + +## Renderer Implementations + +ObjectUI is a protocol. Multiple renderers can implement it: + +| Renderer | Status | Platform | +| :--- | :--- | :--- | +| `@objectstack/react-renderer` | 🚧 In Progress | Web (React) | +| `@objectstack/vue-renderer` | 📋 Planned | Web (Vue) | +| `@objectstack/flutter-renderer` | 📋 Planned | Mobile (Flutter) | +| `@objectstack/native-renderer` | 📋 Planned | Mobile (React Native) | + +## Quick Links + +### For Implementers + +Building a renderer for ObjectUI? Start here: +- [Renderer Interface](/docs/references/ui/Renderer) +- [Component Registry](/docs/guides/custom-components) +- [Test Suite](/docs/guides/renderer-testing) + +### For Users + +Using ObjectUI to build interfaces? See: +- [View Configuration Guide](/docs/guides/view-configuration) +- [Theming Guide](/docs/guides/theming) +- [Dashboard Examples](/docs/tutorials/dashboards) + +## Related Documentation + +- **[Data Protocol](/docs/specifications/data/architecture)** - How to query data +- **[System Protocol](/docs/specifications/server/kernel-architecture)** - Runtime environment +- **[UI Reference](/docs/references/ui/views/View)** - Complete API reference diff --git a/content/docs/specifications/ui/meta.json b/content/docs/specifications/ui/meta.json index 609d4c55b..5718e2700 100644 --- a/content/docs/specifications/ui/meta.json +++ b/content/docs/specifications/ui/meta.json @@ -1,6 +1,7 @@ { "title": "ObjectUI", "pages": [ + "index", "sdui-protocol", "component-schema", "view-protocol", diff --git a/content/docs/troubleshooting.mdx b/content/docs/troubleshooting.mdx new file mode 100644 index 000000000..e86fc0b5b --- /dev/null +++ b/content/docs/troubleshooting.mdx @@ -0,0 +1,499 @@ +--- +title: Troubleshooting +description: Common issues and how to resolve them when working with ObjectStack. +--- + +This guide covers common issues you might encounter when working with ObjectStack and how to resolve them. + +## Installation Issues + +### `npm install @objectstack/spec` fails + +**Symptoms:** +``` +npm ERR! code ERESOLVE +npm ERR! ERESOLVE unable to resolve dependency tree +``` + +**Solutions:** + +1. **Clear npm cache:** + ```bash + npm cache clean --force + rm -rf node_modules package-lock.json + npm install + ``` + +2. **Check Node.js version:** + ```bash + node --version # Should be 18.0.0 or higher + ``` + +3. **Use legacy peer deps (temporary workaround):** + ```bash + npm install --legacy-peer-deps + ``` + +### TypeScript compilation errors + +**Symptoms:** +``` +error TS2307: Cannot find module '@objectstack/spec' +``` + +**Solutions:** + +1. **Ensure correct tsconfig.json:** + ```json + { + "compilerOptions": { + "moduleResolution": "node", + "esModuleInterop": true, + "strict": true + } + } + ``` + +2. **Restart TypeScript server** (VS Code: Cmd+Shift+P → "Restart TS Server") + +## Schema Definition Issues + +### Validation errors in object definitions + +**Symptoms:** +``` +ZodError: [ + { + "code": "invalid_type", + "expected": "string", + "received": "undefined", + "path": ["name"] + } +] +``` + +**Solution:** + +Check that all required fields are provided: + +```typescript +// ❌ Wrong - missing required 'name' field +const Task = ObjectSchema.create({ + label: 'Task', + fields: { ... } +}); + +// ✅ Correct +const Task = ObjectSchema.create({ + name: 'task', // ← Required + label: 'Task', + fields: { ... } +}); +``` + +### Field type errors + +**Symptoms:** +``` +Type 'string' is not assignable to type 'FieldType' +``` + +**Solution:** + +Use Field helper functions, not raw strings: + +```typescript +// ❌ Wrong +fields: { + title: { type: 'text', label: 'Title' } +} + +// ✅ Correct +fields: { + title: Field.text({ label: 'Title' }) +} +``` + +### Circular dependency in lookups + +**Symptoms:** +``` +ReferenceError: Cannot access 'Contact' before initialization +``` + +**Solution:** + +Use lazy imports for circular references: + +```typescript +// File: account.object.ts +export const Account = ObjectSchema.create({ + fields: { + primary_contact: Field.lookup({ + reference: 'contact', // ← String reference, not import + }) + } +}); + +// File: contact.object.ts +export const Contact = ObjectSchema.create({ + fields: { + account: Field.lookup({ + reference: 'account', // ← String reference + }) + } +}); +``` + +## Runtime Issues + +### "Driver not registered" + +**Symptoms:** +``` +Error: Driver 'postgres' not registered +``` + +**Solution:** + +Register the driver before using it: + +```typescript +import { Kernel } from '@objectstack/kernel'; +import { PostgresDriver } from '@objectstack/driver-postgres'; + +const kernel = new Kernel(); + +// Register driver BEFORE creating queries +kernel.registerDriver('postgres', new PostgresDriver({ + host: 'localhost', + database: 'mydb', +})); +``` + +### Query execution fails + +**Symptoms:** +``` +Error: Query failed: syntax error near "SELECT" +``` + +**Solutions:** + +1. **Enable query logging to see generated SQL:** + ```typescript + const kernel = new Kernel({ + logging: { + level: 'debug', + logQueries: true, + }, + }); + ``` + +2. **Check driver capabilities:** + ```typescript + const driver = kernel.getDriver('postgres'); + console.log(driver.capabilities); + + // Ensure your query uses supported features + ``` + +3. **Simplify the query to isolate the issue:** + ```typescript + // Start simple + const simple = await kernel.query({ + object: 'task', + }); + + // Add complexity step by step + const withFilter = await kernel.query({ + object: 'task', + filters: { status: { eq: 'open' } }, + }); + ``` + +### Formula evaluation errors + +**Symptoms:** +``` +Error: Formula evaluation failed: Unknown function 'INVALID' +``` + +**Solutions:** + +1. **Check formula syntax:** + ```typescript + // ❌ Wrong - invalid function + expression: 'INVALID(field)' + + // ✅ Correct - use supported functions + expression: 'IF(field > 0, field * 2, 0)' + ``` + +2. **Verify field references:** + ```typescript + // ❌ Wrong - field doesn't exist + expression: 'nonexistent_field + 10' + + // ✅ Correct - reference actual fields + expression: 'quantity * unit_price' + ``` + +3. **Check return type compatibility:** + ```typescript + Field.formula({ + returnType: 'number', + // ❌ Wrong - returns string + expression: 'CONCAT(first_name, last_name)', + + // ✅ Correct - returns number + expression: 'quantity * unit_price', + }) + ``` + +## UI Rendering Issues + +### Views not displaying correctly + +**Symptoms:** +- Blank screen +- Missing columns +- Incorrect data + +**Solutions:** + +1. **Verify view is registered:** + ```typescript + const manifest = Manifest.create({ + views: { + list: [TaskListView], // ← Must include your view + }, + }); + ``` + +2. **Check field references in columns:** + ```typescript + // ❌ Wrong - field doesn't exist on object + columns: [ + { field: 'nonexistent_field' } + ] + + // ✅ Correct - use actual field names + columns: [ + { field: 'title' }, // ← Must match field in object + { field: 'status' }, + ] + ``` + +3. **Inspect browser console for errors** + +### Form validation not working + +**Symptoms:** +- Form submits invalid data +- No validation errors shown + +**Solutions:** + +1. **Ensure validation rules are registered:** + ```typescript + const manifest = Manifest.create({ + validations: [ + taskValidations, // ← Include validation rules + ], + }); + ``` + +2. **Check validation rule conditions:** + ```typescript + ValidationRule.create({ + // ❌ Wrong - inverted logic + condition: 'due_date < TODAY()', // Triggers when date is in past + + // ✅ Correct - fixed logic + condition: 'due_date < TODAY()', + errorMessage: 'Due date cannot be in the past', + }) + ``` + +## Performance Issues + +### Slow query execution + +**Symptoms:** +- Queries take several seconds +- UI feels sluggish + +**Solutions:** + +1. **Add indexes to frequently queried fields:** + ```typescript + Field.text({ + label: 'Email', + indexed: true, // ← Creates database index + }) + ``` + +2. **Use pagination for large datasets:** + ```typescript + const query = Query.create({ + object: 'task', + limit: 50, // ← Limit results + offset: 0, + }); + ``` + +3. **Optimize formula fields:** + ```typescript + // ❌ Slow - complex nested formulas + expression: 'IF(IF(IF(...), ...), ...)' + + // ✅ Fast - simpler logic + expression: 'amount * (1 - discount / 100)' + ``` + +4. **Enable query result caching:** + ```typescript + const kernel = new Kernel({ + cache: { + enabled: true, + ttl: 60, // seconds + }, + }); + ``` + +### Large bundle size + +**Symptoms:** +- Slow initial page load +- Large JavaScript bundle + +**Solutions:** + +1. **Use tree-shaking:** + ```typescript + // ❌ Imports everything + import * as ObjectStack from '@objectstack/spec'; + + // ✅ Import only what you need + import { ObjectSchema, Field } from '@objectstack/spec'; + ``` + +2. **Code-split views:** + ```typescript + // Lazy-load views + const TaskView = lazy(() => import('./views/task-view')); + ``` + +## Development Issues + +### Hot reload not working + +**Symptoms:** +- Changes not reflected in browser +- Need to manually refresh + +**Solutions:** + +1. **Check Next.js dev server is running:** + ```bash + pnpm docs:dev + ``` + +2. **Clear Next.js cache:** + ```bash + rm -rf .next + pnpm docs:dev + ``` + +### TypeScript autocomplete not working + +**Symptoms:** +- No IntelliSense suggestions +- Type errors not shown + +**Solutions:** + +1. **Restart TypeScript server** (VS Code: Cmd+Shift+P → "Restart TS Server") + +2. **Check tsconfig.json includes source files:** + ```json + { + "include": ["src/**/*", "*.ts"] + } + ``` + +3. **Ensure @objectstack/spec is installed:** + ```bash + npm list @objectstack/spec + ``` + +## Debugging Tips + +### Enable debug logging + +```typescript +const kernel = new Kernel({ + logging: { + level: 'debug', // 'error' | 'warn' | 'info' | 'debug' + logQueries: true, + logValidation: true, + }, +}); +``` + +### Inspect generated schemas + +```typescript +import { zodToJsonSchema } from 'zod-to-json-schema'; + +const jsonSchema = zodToJsonSchema(TaskSchema); +console.log(JSON.stringify(jsonSchema, null, 2)); +``` + +### Test schemas in isolation + +```typescript +import { Task } from './objects/task'; + +// Test valid data +const validResult = Task.safeParse({ + title: 'Test Task', + status: 'todo', +}); +console.log(validResult); // { success: true, data: {...} } + +// Test invalid data +const invalidResult = Task.safeParse({ + title: '', // Empty string (might be invalid) + status: 'invalid_status', +}); +console.log(invalidResult); // { success: false, error: {...} } +``` + +### Use browser DevTools + +1. **Network tab:** Inspect API requests/responses +2. **Console tab:** View runtime errors +3. **React DevTools:** Inspect component props (if using React renderer) + +## Getting Help + +If you're still stuck after trying these solutions: + +1. **Search existing issues:** + - [GitHub Issues](https://github.com/objectstack-ai/spec/issues) + +2. **Ask the community:** + - [GitHub Discussions](https://github.com/objectstack-ai/spec/discussions) + +3. **Report a bug:** + - [Create a new issue](https://github.com/objectstack-ai/spec/issues/new) + - Include: + - ObjectStack version + - Node.js version + - Error message and stack trace + - Minimal reproduction example + +4. **Check the FAQ:** + - [Frequently Asked Questions](/docs/faq) diff --git a/content/docs/tutorials.mdx b/content/docs/tutorials.mdx new file mode 100644 index 000000000..754ded1a7 --- /dev/null +++ b/content/docs/tutorials.mdx @@ -0,0 +1,137 @@ +--- +title: Tutorials +description: Step-by-step hands-on tutorials to learn ObjectStack by building real applications. +--- + +Learn ObjectStack through practical, hands-on tutorials. Each tutorial is designed to teach specific concepts while building a complete, working application. + +## Getting Started Tutorials + + + + + + + +## Feature-Focused Tutorials + +### Data & Business Logic + + + + + + + + +### UI & User Experience + + + + + + + +### Advanced Topics + + + + + + + +## Video Tutorials + +Coming soon! Subscribe to our [YouTube channel](#) for video tutorials. + +## Tutorial Prerequisites + +All tutorials assume you have: +- Node.js 18+ installed +- Basic TypeScript knowledge +- Text editor or IDE (VS Code recommended) +- Terminal/command line familiarity + +## Learning Path + +Not sure where to start? Follow this recommended path: + + + +### 1. Start with Quick Start +Complete [Build Your First App](/docs/quick-start/build-first-app) (10 minutes) + +### 2. Choose Your Path +- **Backend Focus:** [Field Types](/docs/tutorials/field-types) → [Formulas](/docs/tutorials/formulas) → [Workflows](/docs/tutorials/workflows) +- **Frontend Focus:** [Custom Views](/docs/tutorials/custom-views) → [Forms](/docs/tutorials/forms) → [Dashboards](/docs/tutorials/dashboards) +- **Full-Stack:** [CRM System](/docs/tutorials/crm-system) → [Multi-Tenancy](/docs/tutorials/multi-tenancy) + +### 3. Build Your Own +Apply what you've learned to build your own application! + + + +## Community Examples + +Check out community-contributed examples: +- [GitHub Discussions](https://github.com/objectstack-ai/spec/discussions) +- [Example Gallery](https://github.com/objectstack-ai/spec/tree/main/examples) + +## Get Help + +Stuck on a tutorial? +- Check the [Troubleshooting Guide](/docs/guides/troubleshooting) +- Ask in [GitHub Discussions](https://github.com/objectstack-ai/spec/discussions) +- Review the [FAQ](/docs/guides/faq) diff --git a/content/docs/tutorials/meta.json b/content/docs/tutorials/meta.json new file mode 100644 index 000000000..cfabbef3f --- /dev/null +++ b/content/docs/tutorials/meta.json @@ -0,0 +1,3 @@ +{ + "title": "Tutorials" +}