@dboio/cli 0.20.4 → 0.20.5

package/plugins/claude/dbo/docs/_audit_required/dbo-white-paper.md

@@ -1,125 +0,0 @@
-# DBO.io: Your Schema Is Your Application
-
-## The Problem
-
-Most software asks you to accept someone else's idea of how your data should be organized. A CRM gives you their definition of a "contact." A project management tool gives you their definition of a "task." A SaaS platform gives you their schema, and you reshape your business to fit it.
-
-The alternative — custom development — solves the data model problem but introduces an engineering problem. A custom application requires a full technology stack: an object-relational mapper to translate between the database and the programming language, a business logic layer to enforce rules, controllers to handle requests, views to render output, and migration scripts to evolve the schema over time. This middle tier — the code that sits between the database and the user — is where most of the complexity, cost, and ongoing maintenance lives. It is the reason custom software is expensive and slow to change.
-
-The irony is that the relational database already knows the structure of the data. The tables, columns, types, constraints, and relationships are all defined in the schema. But conventional application development ignores this knowledge and restates it — painstakingly, redundantly — in application code. Every column becomes a property in a model class. Every table becomes a set of controller actions. Every relationship becomes a join written by hand. The database knows what the data looks like, but the application pretends it doesn't.
-
-## The Core Insight
-
-DBO.io begins with a simple premise: if the database already describes the structure of the data, the platform should be able to derive the application from that description. Define your tables and columns, and the platform provides the API, the rendering, the security, and the messaging — automatically. The schema is not an implementation detail hidden behind code. It is the application definition itself.
-
-This eliminates the middle tier entirely. There is no object-relational mapper because there are no model classes. There is no business logic layer because the rules are expressed as metadata on the schema. There is no controller code because the API is generated from the entity definitions. The path from database to user-facing output is direct: a query executes, a template renders the result, and tokens resolve dynamic values — all without a line of application code.
-
-The result is a platform where the people who understand the data — the domain experts, the analysts, the business owners — can define and modify applications by working with the schema and templates, not by writing or commissioning software.
-
-## Five Pillars of the Architecture
-
-### Pillar 1: The Entity System — Schema as Configuration
-
-At the center of DBO.io is the entity, a metadata wrapper around a database table or view. An entity is not a class definition or a code artifact. It is a database record that describes a table: its name, its data source, its columns, and the behaviors associated with it.
-
-Each column in an entity carries rich metadata beyond what the database schema alone provides. A column definition includes its data type and constraints, but also its display title, default value, validation rules, encryption behavior, whether it is read-only or computed, and its relationships to other entities. This metadata is the configuration that would traditionally be scattered across model classes, validation logic, form definitions, and migration scripts. In DBO.io, it lives in one place: the column record.
-
-Because entities and columns are themselves data — rows in tables — adding a new entity or modifying a column is a data operation, not a code change. There is no deployment, no recompilation, no migration script. The schema evolves through the same mechanisms used to manage any other data in the system.
-
-The entity system is database-agnostic. A data source abstraction layer handles the differences between database engines — identifier quoting, date formatting, type conversion, identity retrieval — so that entities can be backed by different databases without any change to the entity definition or the application behavior. A single application can query across multiple databases transparently.
-
-### Pillar 2: The Eliminated Middle Tier — Database to API
-
-In a conventional application, a request from the user passes through a controller, which calls a service, which calls a repository, which calls the database, and then the result travels back through the same layers in reverse. Each layer exists to translate between the one above it and the one below it. Each layer must be written, tested, and maintained.
-
-DBO.io collapses this stack. REST endpoints map directly to data operations. An input endpoint handles creates, updates, and deletes. An output endpoint executes a query and returns results. A content endpoint renders a template. A message endpoint sends a communication. The platform provides these endpoints automatically for every entity. There is no controller to write, no service layer to maintain, no repository pattern to implement.
-
-Validation, transactions, and error handling are enforced by the platform based on the entity and column metadata. A column marked as required will reject null values. A column marked as encrypted will encrypt on write and decrypt on read. A column with a maximum length will enforce it. These are not rules written in application code — they are properties of the column definition.
-
-The API supports the full spectrum of data operations through a uniform syntax. A single request can create, update, or delete records across multiple entities, all within a transaction. Filtering, sorting, pagination, and search are URL parameters, not code. The format of the response — HTML, JSON, XML, CSV — is a parameter, not a separate endpoint or serialization layer.
-
-### Pillar 3: Template Composition — Rendering Without Code
-
-Query results, by themselves, are just data. Turning data into something a user can see and interact with is the job of templates. In DBO.io, a template defines how a set of query results becomes a rendered output — an HTML page, a JSON response, an email, a PDF.
-
-A template is organized into structural sections: a header rendered once at the top, a row section rendered for each record, a footer rendered at the end, and an empty section rendered when there are no results. Within these sections, tokens resolve dynamic values. A value token pulls a column from the current row. A session token pulls a value from the current user's session. A request token pulls a URL parameter. A site token pulls a property of the current domain. Tokens can carry modifiers — to decrypt a value, escape it for HTML, truncate it, or format a date.
-
-The composition model is what elevates templates from simple formatting to application assembly. An embed token nests one piece of rendered content inside another. An output can embed another output, a content record, an input form, or a message — and each embedded element resolves its own tokens from its own data context. A page is not a monolithic view; it is a composition of independently defined, independently queryable components. Each component can be reused across multiple pages, and changes to a component propagate everywhere it appears.
-
-User-defined template tags extend the system without code changes. A template author can define custom named sections and reference them throughout the template. The platform distinguishes between system tags, which have fixed semantic meaning, and user-defined tags, which are arbitrary extensions. This allows template authors to create reusable patterns and conditional structures within the template language itself.
-
-### Pillar 4: Cell-Level Security — Granular by Design
-
-Security in DBO.io is not an afterthought bolted onto the application layer. It is intrinsic to the entity and column model, enforced at the data level before results ever reach a template or an API response.
-
-Access control operates at three levels of granularity. At the entity level, a security rule grants or denies a user or group the ability to view, add, edit, delete, or execute operations on an entire entity. At the column level, a separate security rule can restrict access to individual columns — hiding sensitive fields from users who should not see them, or making certain columns read-only for certain roles. At the row level, a security rule can restrict access to specific records, identified by their primary key values.
-
-These security rules are data. They are rows in security tables, not code in middleware or annotations on classes. Adding a security rule is a data operation. Changing who can see what is a data operation. The security model is as dynamic and configurable as the schema itself.
-
-When a query executes, the platform automatically generates additional constraints based on the requesting user's security profile. If a user can only see certain rows, the query is filtered before execution. If a user cannot see certain columns, those columns are excluded from the result set. The template never has an opportunity to render data the user is not authorized to see, because that data is never retrieved in the first place.
-
-This approach means that security is consistent regardless of how data is accessed. Whether a user requests data through the API, through a template, through an embed, or through a message, the same rules apply. There is no surface area where an application developer can accidentally expose data by forgetting to check permissions — the platform enforces it universally.
-
-### Pillar 5: Multi-Tenancy and Instance Architecture
-
-DBO.io is designed from the ground up to serve many organizations from a single platform, with each organization owning its own data model.
-
-The tenancy model has two levels. An account represents an organization — a company, a department, a client. An instance represents a discrete application environment within that account — production, staging, development, or entirely separate applications. Each instance gets its own database with its own schema. There is no shared-schema multi-tenancy where tenants' data is commingled in the same tables. Each tenant's data is physically isolated.
-
-A shared control plane manages cross-cutting concerns: account records, user authentication, instance metadata, and domain routing. When a request arrives, the platform identifies the account and instance from the domain or request parameters, establishes a connection to the appropriate instance database, and all subsequent operations — queries, security checks, template rendering, caching — execute within that tenant's context.
-
-Applications are portable. Because entities, columns, templates, security rules, and configuration are all data records, an entire application can be exported from one instance and imported into another. This enables a workflow where applications are developed in a staging instance, tested, and then deployed to production — or packaged and deployed across entirely separate organizations.
-
-The caching architecture respects tenant boundaries. Cache keys are prefixed with account and instance identifiers, preventing any possibility of data leaking across tenants. Each level of the cache hierarchy — system-wide, account-scoped, session-scoped, and request-scoped — maintains strict isolation.
-
-## How the Pieces Compose
-
-Consider a practical example. An organization needs to track projects and the people assigned to them.
-
-An administrator defines two entities — one for projects and one for assignments — by creating records in the entity table. For each entity, they define columns: project name, status, start date, assigned person, role. Each column record specifies its data type, display title, validation rules, and any default values. The moment these records exist, the platform exposes REST API endpoints for creating, reading, updating, and deleting records in both entities. No code has been written.
-
-Next, the administrator creates an output — a saved query definition — that joins projects with their assignments. They create a template for this output with a header showing column titles, a row section displaying each project with its assigned personnel, and a footer showing the total count. Tokens in the template resolve column values, and the output is immediately available as an API endpoint that returns rendered HTML or raw JSON, depending on the requested format.
-
-To build a full page, the administrator creates a content record that embeds the project output alongside a separate output showing summary statistics and an input form for adding new assignments. Each embedded element resolves independently — the statistics query runs, the project list query runs, the input form renders — and the results compose into a single page. If the summary statistics are needed on other pages, that output is simply embedded again elsewhere.
-
-Security rules ensure that each user sees only the projects they are authorized to view. A project manager sees all projects; a team member sees only their assignments. These rules are data records, and the platform enforces them transparently — the template and the API never need to check permissions, because the query results are already filtered.
-
-Finally, the administrator creates a message template that sends an email notification when a new assignment is created. The email template uses the same token system as the page templates, pulling the project name, assignee, and role from the data context. The message is queued and delivered by a background process.
-
-The entire application — data model, API, rendered pages, security, and notifications — was created by defining data records. No application code was written. No deployment was performed. The schema became the application.
-
-## The Content Execution Layer
-
-Configuration covers the vast majority of application behavior, but there are cases where custom logic is genuinely required — a complex calculation, a data transformation, an integration with an external service. For these cases, DBO.io provides a content execution layer.
-
-Dynamic code can be authored as a content record and executed at runtime. The platform compiles the code, caches the compiled result for performance, and executes it within a controlled environment that provides access to data sources, the current user context, and structured input and output objects. The compiled code is cached by its content hash, so identical code is never recompiled.
-
-This layer sits alongside templates, not in place of them. It is an escape hatch for the minority of cases where declarative configuration is insufficient — not a general-purpose programming model that replaces the template and token system. The design philosophy is that most application behavior should be expressible through schema, templates, and metadata, with dynamic code reserved for genuine exceptions.
-
-## The Messaging Subsystem
-
-Communication is a first-class capability, not an external integration. The platform supports email, SMS, and AI-powered chatbot conversations through a unified messaging abstraction.
-
-Message templates use the same token and template system as content rendering. An email template defines its recipients, subject, and body using the same tokens that resolve data values, session information, and request parameters in any other template. This means that any data accessible through the platform can be included in a message without writing integration code.
-
-Messages are queued for background delivery with scheduling support. A message can be sent immediately or deferred to a future time. The background processing system handles retries and batch delivery. Chatbot conversations support multi-turn threading, where the platform tracks conversation history and manages function calling — allowing an AI assistant to query data and perform operations through the same API that serves human users.
-
-## The Caching Architecture
-
-Performance at scale requires caching, and DBO.io provides a multi-level cache designed for multi-tenant isolation. The cache operates at five tiers: system-wide for data shared across all tenants, account-scoped for data shared across an organization's instances, instance-scoped for data within a single application, session-scoped for data tied to a user's session, and request-scoped for data that lives only for the duration of a single request.
-
-Entity metadata, query results, rendered content, and compiled code are each cached independently and at the appropriate tier. The cache supports pluggable storage backends — an in-process cache for single-server deployments and a distributed cache for scaled environments. Selective invalidation allows refreshing specific cached items without flushing the entire cache.
-
-## What This Makes Possible
-
-DBO.io inverts the traditional relationship between database and application. Instead of the database serving the application, the database defines the application. This inversion has practical consequences.
-
-Application development is measured in hours, not months. Defining entities, creating templates, and configuring security rules are all data operations that take effect immediately. There is no build step, no deployment pipeline, no waiting for code review. The people closest to the business problem — who understand the data and the workflows — can build and modify applications directly.
-
-Every customer gets a data model that fits their actual business. There is no compromise between "our schema" and "your needs." The schema is yours. It reflects your entities, your relationships, your terminology. When the business changes, the schema changes, and the application changes with it — instantly, without a development cycle.
-
-The eliminated middle tier means there is dramatically less code to write, test, debug, and maintain. The platform handles the concerns that traditionally consume the majority of development effort: API routing, data validation, security enforcement, output formatting, and cache management. What remains is the schema, the templates, and the metadata that configures them — all of which are data, all of which are versioned and portable, and none of which require a compiler.
-
-The platform scales across organizations through physical database isolation, tenant-aware caching, and a shared control plane. Each organization operates as if they have their own platform, because at the data level, they do.
-
-DBO.io is the thesis that for the vast majority of data-driven applications, the relational database already contains everything the application needs to know. The platform's job is to stop ignoring that knowledge and start deriving the application from it.