spine-framework 0.3.17 → 0.3.18

package/docs/README.md

@@ -0,0 +1,170 @@
+# Spine Framework
+
+**A multi-tenant, modular application platform for modern SaaS systems.**
+
+Spine Framework provides the operational backbone — identity, data modeling, permissions, real-time sync, and extensibility — so you can build vertical applications faster.
+
+## What Spine Provides
+
+| Primitive | Purpose |
+|-----------|---------|
+| **Accounts** | Multi-tenant organizations with RLS isolation |
+| **People** | Users with cross-account identities |
+| **Items** | Typed records (deals, tickets, posts, custom entities) |
+| **Types** | Runtime-defined schemas with permissions |
+| **Apps** | Modular feature packages |
+| **Realtime** | Live subscriptions to data changes |
+| **RLS Security** | Row-level security with role-based access |
+
+## Quick Start
+
+```bash
+# Create new project
+npm init spine-framework@next
+
+# Or add to existing project
+npm install spine-framework@next
+
+# Start development
+npm run dev
+```
+
+## Installation
+
+See [INSTALL.md](INSTALL.md) for detailed setup instructions.
+
+## Architecture
+
+Spine Framework is built on:
+
+- **Frontend**: React 18 + TypeScript + Tailwind CSS + Vite
+- **Backend**: Supabase (PostgreSQL + Auth + Realtime)
+- **Edge**: Netlify/Vercel Edge Functions
+- **Extension**: Custom workspace pattern
+
+Read [ARCHITECTURE.md](ARCHITECTURE.md) for the full technical overview.
+
+## Project Structure
+
+```
+my-spine-app/
+├── .framework/          # Framework core (read-only)
+│   ├── src/            # React components & pages
+│   ├── migrations/     # Database migrations
+│   └── scripts/        # CLI & build tools
+├── custom/             # Your custom code
+│   ├── apps/          # Installed apps (portal, cortex, etc.)
+│   ├── components/    # Shared components
+│   ├── functions/     # Edge functions
+│   └── migrations/    # Custom migrations
+├── docs/              # Documentation
+└── package.json
+```
+
+## Core Principles
+
+1. **Framework-Agnostic Core** — Base platform knows nothing of specific apps
+2. **App-Defined Data** — Types, roles, and schemas defined by apps
+3. **Custom Workspace** — Extensions in `custom/` without modifying core
+4. **RLS-First Security** — All permissions enforced at database level
+
+## Apps
+
+Spine Framework is extended through apps:
+
+- **portal** — Customer portal with courses, community, support
+- **cortex** — AI-powered CRM, knowledge base, and support
+- **Your App** — Build and install custom apps
+
+See [APPS.md](APPS.md) for app development guide.
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- PostgreSQL 14+ (or Supabase account)
+- npm or yarn
+
+### Local Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Configure environment
+cp .framework/.env.example .env
+# Edit .env with your Supabase credentials
+
+# Apply database migrations
+npx spine-cli db:migrate
+
+# Start dev server
+npm run dev
+```
+
+### Installing Apps
+
+```bash
+# From npm
+npm install spine-framework-cortex@next
+npx spine-cli app:install cortex
+
+# From local package
+npx spine-cli app:install ./custom/npm/my-app
+```
+
+### Creating Custom Apps
+
+```bash
+# Scaffold new app
+npx spine-cli app:create my-app
+
+# Define types in custom/apps/my-app/seed/types.json
+# Create pages in custom/apps/my-app/pages/
+# Wire up routes in custom/apps/my-app/index.tsx
+
+# Install and test
+npx spine-cli app:install ./custom/apps/my-app
+npm run dev
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [INSTALL.md](INSTALL.md) | Installation guide |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture |
+| [APPS.md](APPS.md) | App development |
+| [spine-core--api-reference.md](spine-core--api-reference.md) | API reference |
+| [dev-guides/](dev-guides/) | Step-by-step tutorials |
+
+## CLI Commands
+
+```bash
+npx spine-cli init              # Initialize new project
+npx spine-cli db:migrate        # Apply migrations
+npx spine-cli db:seed           # Apply seed data
+npx spine-cli app:install <name> # Install an app
+npx spine-cli app:create <name>  # Create new app scaffold
+```
+
+## npm Packages
+
+| Package | Description |
+|---------|-------------|
+| `spine-framework` | Core framework |
+| `spine-framework-portal` | Customer portal app |
+| `spine-framework-cortex` | CRM & support app |
+
+All packages use the `@next` tag for pre-release versions.
+
+## License
+
+MIT License — see LICENSE file for details.
+
+## Support
+
+- Documentation: `docs/`
+- Issues: https://github.com/spine-framework/spine/issues
+- Discussions: https://github.com/spine-framework/spine/discussions