|
| 1 | +--- |
| 2 | +title: ObjectOS - The Platform |
| 3 | +description: Runtime platform that binds data and UI together with Local-First architecture |
| 4 | +--- |
| 5 | + |
| 6 | +# ObjectOS - The Platform |
| 7 | + |
| 8 | +ObjectOS is the runtime platform that brings ObjectQL (data) and ObjectUI (interface) together, providing a complete application environment with identity management, access control, and flexible deployment options. |
| 9 | + |
| 10 | +## What is ObjectOS? |
| 11 | + |
| 12 | +ObjectOS is the **runtime platform** that orchestrates the entire ObjectStack. It binds the data layer (ObjectQL) with the presentation layer (ObjectUI) while providing essential platform services like user management, security, and deployment capabilities. |
| 13 | + |
| 14 | +### Key Capabilities |
| 15 | + |
| 16 | +- 🔗 **QL-UI Binding** - Seamlessly connects data engine with UI framework |
| 17 | +- 🏠 **Local-First Architecture** - Run applications entirely on local devices |
| 18 | +- 👥 **Identity & Access Management** - Built-in user system with RBAC |
| 19 | +- 🔒 **Field-Level Security** - Fine-grained data access control |
| 20 | +- 🚀 **Flexible Deployment** - Standalone .oos files or Docker containers |
| 21 | +- 🏢 **Multi-Tenant Ready** - SaaS-ready with tenant isolation |
| 22 | + |
| 23 | +## How It Works |
| 24 | + |
| 25 | +ObjectOS operates as the runtime environment that: |
| 26 | + |
| 27 | +### 1. Binds Data and UI |
| 28 | + |
| 29 | +ObjectOS creates a bidirectional bridge between ObjectQL and ObjectUI: |
| 30 | + |
| 31 | +```typescript |
| 32 | +// ObjectOS automatically wires up data and UI |
| 33 | +const app = new ObjectOS({ |
| 34 | + schema: './schema', // ObjectQL schemas |
| 35 | + pages: './pages', // ObjectUI components |
| 36 | + storage: './data' // Local-First storage |
| 37 | +}) |
| 38 | + |
| 39 | +await app.start() |
| 40 | +``` |
| 41 | + |
| 42 | +### 2. Manages Platform Services |
| 43 | + |
| 44 | +Provides essential platform capabilities: |
| 45 | + |
| 46 | +- **User System** - Authentication and user profiles in `_users` object |
| 47 | +- **Role Management** - Flexible role definitions in `_roles` object |
| 48 | +- **Permission Control** - RBAC with field-level security |
| 49 | +- **Data Isolation** - Multi-tenant data segregation |
| 50 | + |
| 51 | +### 3. Enables Flexible Deployment |
| 52 | + |
| 53 | +Deploy applications in multiple modes: |
| 54 | + |
| 55 | +```bash |
| 56 | +# Standalone mode - single .oos file |
| 57 | +./myapp.oos |
| 58 | + |
| 59 | +# Server mode - Docker container |
| 60 | +docker run -p 3000:3000 myapp:latest |
| 61 | + |
| 62 | +# Multi-tenant SaaS mode |
| 63 | +docker run -e MULTI_TENANT=true myapp:latest |
| 64 | +``` |
| 65 | + |
| 66 | +## Platform Architecture |
| 67 | + |
| 68 | +``` |
| 69 | +┌─────────────────────────────────────────────────────┐ |
| 70 | +│ Application Layer │ |
| 71 | +│ (Your Business Logic) │ |
| 72 | +└──────────────────────┬──────────────────────────────┘ |
| 73 | + │ |
| 74 | +┌──────────────────────▼──────────────────────────────┐ |
| 75 | +│ ObjectOS Platform │ |
| 76 | +│ ┌──────────────────────────────────────────────┐ │ |
| 77 | +│ │ Identity & Access Layer │ │ |
| 78 | +│ │ ┌────────┬────────┬──────────────────┐ │ │ |
| 79 | +│ │ │ Users │ Roles │ Permissions (FLS)│ │ │ |
| 80 | +│ │ └────────┴────────┴──────────────────┘ │ │ |
| 81 | +│ └──────────────────────────────────────────────┘ │ |
| 82 | +│ ┌──────────────────────────────────────────────┐ │ |
| 83 | +│ │ QL-UI Binding Layer │ │ |
| 84 | +│ │ ┌──────────────────┬──────────────────┐ │ │ |
| 85 | +│ │ │ ObjectUI │ ObjectQL │ │ │ |
| 86 | +│ │ │ (Presentation) │ (Data Engine) │ │ │ |
| 87 | +│ │ └──────────────────┴──────────────────┘ │ │ |
| 88 | +│ └──────────────────────────────────────────────┘ │ |
| 89 | +│ ┌──────────────────────────────────────────────┐ │ |
| 90 | +│ │ Storage Abstraction │ │ |
| 91 | +│ │ ┌─────────┬──────────┬──────────────────┐ │ │ |
| 92 | +│ │ │ SQLite │ MySQL │ PostgreSQL │ │ │ |
| 93 | +│ │ │ (Local) │ (Server) │ (Server) │ │ │ |
| 94 | +│ │ └─────────┴──────────┴──────────────────┘ │ │ |
| 95 | +│ └──────────────────────────────────────────────┘ │ |
| 96 | +└─────────────────────────────────────────────────────┘ |
| 97 | +``` |
| 98 | + |
| 99 | +## Use Cases |
| 100 | + |
| 101 | +### Personal Productivity Apps |
| 102 | + |
| 103 | +Build Local-First applications that run entirely offline: |
| 104 | + |
| 105 | +```typescript |
| 106 | +const app = new ObjectOS({ |
| 107 | + mode: 'standalone', |
| 108 | + storage: '~/.myapp/data.db' |
| 109 | +}) |
| 110 | +``` |
| 111 | + |
| 112 | +### Team Collaboration Tools |
| 113 | + |
| 114 | +Deploy server-based applications with user management: |
| 115 | + |
| 116 | +```typescript |
| 117 | +const app = new ObjectOS({ |
| 118 | + mode: 'server', |
| 119 | + database: 'mysql://localhost/myapp', |
| 120 | + auth: { |
| 121 | + providers: ['email', 'oauth'] |
| 122 | + } |
| 123 | +}) |
| 124 | +``` |
| 125 | + |
| 126 | +### Multi-Tenant SaaS Platforms |
| 127 | + |
| 128 | +Build SaaS applications with complete tenant isolation: |
| 129 | + |
| 130 | +```typescript |
| 131 | +const app = new ObjectOS({ |
| 132 | + mode: 'multi-tenant', |
| 133 | + tenantStrategy: 'virtualCity', |
| 134 | + database: 'postgresql://localhost/saas' |
| 135 | +}) |
| 136 | +``` |
| 137 | + |
| 138 | +## What You'll Learn |
| 139 | + |
| 140 | +In this section, you will discover: |
| 141 | + |
| 142 | +- ✅ **Platform Architecture** - How ObjectOS binds QL and UI together |
| 143 | +- ✅ **Identity & Access** - User system, RBAC, and field-level security |
| 144 | +- ✅ **Deployment & Operations** - Standalone, server, and multi-tenant modes |
| 145 | +- ✅ **Best Practices** - Security configurations and optimization techniques |
| 146 | + |
| 147 | +## Getting Started |
| 148 | + |
| 149 | +Ready to dive in? Start with: |
| 150 | + |
| 151 | +1. **[Platform Architecture](./platform-architecture)** - Understand how ObjectOS works |
| 152 | +2. **[Identity & Access](./identity-access)** - Set up users and permissions |
| 153 | +3. **[Deployment](./deployment)** - Deploy your application |
| 154 | + |
| 155 | +## Quick Example |
| 156 | + |
| 157 | +Here's a complete example to get you started: |
| 158 | + |
| 159 | +```typescript |
| 160 | +import { ObjectOS } from '@objectstack/os' |
| 161 | + |
| 162 | +// 1. Initialize ObjectOS with schema and UI |
| 163 | +const app = new ObjectOS({ |
| 164 | + mode: 'standalone', |
| 165 | + storage: './myapp.db', |
| 166 | + schema: { |
| 167 | + objects: { |
| 168 | + tasks: { |
| 169 | + fields: { |
| 170 | + name: { type: 'text', required: true }, |
| 171 | + owner: { type: 'lookup', reference_to: '_users' } |
| 172 | + }, |
| 173 | + permission_set: { |
| 174 | + user_permission: { |
| 175 | + allowCreate: true, |
| 176 | + allowRead: true, |
| 177 | + allowEdit: "owner eq $user.id", |
| 178 | + allowDelete: "owner eq $user.id" |
| 179 | + } |
| 180 | + } |
| 181 | + } |
| 182 | + } |
| 183 | + }, |
| 184 | + pages: { |
| 185 | + home: { |
| 186 | + type: 'list', |
| 187 | + object: 'tasks' |
| 188 | + } |
| 189 | + } |
| 190 | +}) |
| 191 | + |
| 192 | +// 2. Start the application |
| 193 | +await app.start() |
| 194 | + |
| 195 | +console.log('ObjectOS running at http://localhost:3000') |
| 196 | +``` |
| 197 | + |
| 198 | +## Local-First Architecture |
| 199 | + |
| 200 | +ObjectOS is designed with Local-First principles: |
| 201 | + |
| 202 | +- **Offline-First** - Applications work without network connectivity |
| 203 | +- **User Ownership** - Data stays on user's device in standalone mode |
| 204 | +- **Sync When Ready** - Optional synchronization with cloud services |
| 205 | +- **Fast Performance** - SQLite-powered local storage |
| 206 | + |
| 207 | +```typescript |
| 208 | +// Local-First configuration |
| 209 | +const app = new ObjectOS({ |
| 210 | + mode: 'standalone', |
| 211 | + storage: './local-data.db', |
| 212 | + sync: { |
| 213 | + enabled: false, // Fully offline |
| 214 | + // Or enable sync: |
| 215 | + // remote: 'https://sync.example.com', |
| 216 | + // strategy: 'manual' |
| 217 | + } |
| 218 | +}) |
| 219 | +``` |
| 220 | + |
| 221 | +## Next Steps |
| 222 | + |
| 223 | +Begin your ObjectOS journey: |
| 224 | + |
| 225 | +- **New to ObjectOS?** Start with [Platform Architecture](./platform-architecture) |
| 226 | +- **Setting up security?** Jump to [Identity & Access](./identity-access) |
| 227 | +- **Ready to deploy?** Check [Deployment & Operations](./deployment) |
0 commit comments