@classytic/arc 1.1.0 → 2.1.2

package/README.md

@@ -1,162 +1,45 @@
 # @classytic/arc
 
-**Database-agnostic resource framework for Fastify**
+Database-agnostic resource framework for Fastify. Define resources, get CRUD routes, permissions, presets, caching, events, and OpenAPI — without boilerplate.
 
-*Think Rails conventions, Django REST Framework patterns, Laravel's Eloquent — but for Fastify.*
+**Requires:** Fastify 5+ | Node.js 22+ | ESM only
 
-Arc provides routing, permissions, and resource patterns. **You choose the database:**
-- **MongoDB** → `npm install @classytic/mongokit`
-- **PostgreSQL/MySQL/SQLite** → `@classytic/prismakit` (coming soon)
-
-> **⚠️ ESM Only**: Arc requires Node.js 18+ with ES modules (`"type": "module"` in package.json). CommonJS is not supported. [Migration guide →](https://nodejs.org/api/esm.html)
-
----
-
-## Why Arc?
-
-Building REST APIs in Node.js often means making hundreds of small decisions: How do I structure routes? Where does validation go? How do I handle soft deletes consistently? What about multi-tenant isolation?
-
-**Arc gives you conventions so you can focus on your domain, not boilerplate.**
-
-| Without Arc | With Arc |
-|-------------|----------|
-| Write CRUD routes for every model | `defineResource()` generates them |
-| Manually wire controllers to routes | Convention-based auto-wiring |
-| Copy-paste soft delete logic | `presets: ['softDelete']` |
-| Manually filter by tenant on every query | `presets: ['multiTenant']` auto-filters |
-| Hand-roll OpenAPI specs | Auto-generated from resources |
-
-**Arc is opinionated where it matters, flexible where you need it.**
-
----
-
-## Installation
+## Install
 
 ```bash
-# Core framework
-npm install @classytic/arc
-
-# Choose your database kit:
-npm install @classytic/mongokit     # MongoDB/Mongoose
-# npm install @classytic/prismakit  # PostgreSQL/MySQL/SQLite (coming soon)
+npm install @classytic/arc fastify
+npm install @classytic/mongokit mongoose   # MongoDB adapter
 ```
 
-### Optional Dependencies
-
-Arc's security and utility plugins are opt-in via peer dependencies. Install only what you need:
-
-```bash
-# Security plugins (recommended for production)
-npm install @fastify/helmet @fastify/cors @fastify/rate-limit
-
-# Performance plugins
-npm install @fastify/under-pressure
-
-# Utility plugins
-npm install @fastify/sensible @fastify/multipart fastify-raw-body
-
-# Development logging
-npm install pino-pretty
-```
-
-Or disable plugins you don't need:
-```typescript
-createApp({
-  helmet: false,      // Disable if not needed
-  rateLimit: false,   // Disable if not needed
-  // ...
-})
-```
-
-## Key Features
-
-- **Resource-First Architecture** — Define your API as resources with `defineResource()`, not scattered route handlers
-- **Presets System** — Composable behaviors like `softDelete`, `slugLookup`, `tree`, `ownedByUser`, `multiTenant`
-- **Auto-Generated OpenAPI** — Documentation that stays in sync with your code
-- **Database-Agnostic Core** — Works with any database via adapters. MongoDB/Mongoose optimized out of the box, extensible to Prisma, Drizzle, TypeORM, etc.
-- **Production Defaults** — Helmet, CORS, rate limiting enabled by default
-- **CLI Tooling** — `arc generate resource` scaffolds new resources instantly
-- **Environment Presets** — Development, production, and testing configs built-in
-- **Type-Safe Presets** — TypeScript interfaces ensure controller methods match preset requirements
-- **Ultra-Fast Testing** — In-memory MongoDB support for 10x faster tests
-
 ## Quick Start
 
-### Using ArcFactory (Recommended)
-
 ```typescript
 import mongoose from 'mongoose';
 import { createApp } from '@classytic/arc/factory';
-import { productResource } from './resources/product.js';
-import config from './config/index.js';
 
-// 1. Connect your database (Arc is database-agnostic)
-await mongoose.connect(config.db.uri);
+await mongoose.connect(process.env.DB_URI);
 
-// 2. Create Arc app
 const app = await createApp({
-  preset: 'production', // or 'development', 'testing'
-  auth: { jwt: { secret: config.app.jwtSecret } },
-  cors: { origin: config.cors.origin },
-
-  // Opt-out security (all enabled by default)
-  helmet: true,           // Set false to disable
-  rateLimit: true,        // Set false to disable
-  underPressure: true,    // Set false to disable
+  preset: 'production',
+  auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET } },
+  cors: { origin: process.env.ALLOWED_ORIGINS?.split(',') },
 });
 
-// 3. Register your resources
 await app.register(productResource.toPlugin());
-
 await app.listen({ port: 8040, host: '0.0.0.0' });
 ```
 
-### Multiple Databases
+## defineResource
 
-Arc's adapter pattern lets you connect to multiple databases:
+Single API for a full REST resource with routes, permissions, and behaviors:
 
 ```typescript
-import mongoose from 'mongoose';
-
-// Connect to multiple databases
-const primaryDb = await mongoose.connect(process.env.PRIMARY_DB);
-const analyticsDb = mongoose.createConnection(process.env.ANALYTICS_DB);
-
-// Each resource uses its own adapter
-const orderResource = defineResource({
-  name: 'order',
-  adapter: createMongooseAdapter({ model: OrderModel, repository: orderRepo }),
-});
-
-const analyticsResource = defineResource({
-  name: 'analytics',
-  adapter: createMongooseAdapter({ model: AnalyticsModel, repository: analyticsRepo }),
-});
-```
-
-### Manual Setup
-
-```typescript
-import Fastify from 'fastify';
-import mongoose from 'mongoose';
-import { defineResource, createMongooseAdapter } from '@classytic/arc';
-
-// Connect your database
-await mongoose.connect('mongodb://localhost:27017/myapp');
-
-const fastify = Fastify();
-
-// Define and register resources
-import { allowPublic, requireRoles } from '@classytic/arc';
+import { defineResource, createMongooseAdapter, allowPublic, requireRoles } from '@classytic/arc';
 
 const productResource = defineResource({
   name: 'product',
-  adapter: createMongooseAdapter({
-    model: ProductModel,
-    repository: productRepository,
-  }),
-  controller: productController, // optional; auto-created if omitted
-  presets: ['softDelete', 'slugLookup'],
+  adapter: createMongooseAdapter({ model: ProductModel, repository: productRepo }),
+  presets: ['softDelete', 'slugLookup', { name: 'multiTenant', tenantField: 'orgId' }],
   permissions: {
     list: allowPublic(),
     get: allowPublic(),
@@ -164,766 +47,336 @@ const productResource = defineResource({
     update: requireRoles(['admin']),
     delete: requireRoles(['admin']),
   },
-});
-
-await fastify.register(productResource.toPlugin());
-```
-
-## Core Concepts
-
-### Authentication
-
-Arc provides **optional** built-in JWT authentication. You can:
-
-1. **Use Arc's JWT auth** (default) - Simple, production-ready
-2. **Replace with OAuth** - Google, Facebook, GitHub, etc.
-3. **Use Passport.js** - 500+ authentication strategies
-4. **Create custom auth** - Full control over authentication logic
-5. **Mix multiple strategies** - JWT + API keys + OAuth
-
-**Arc's auth is NOT mandatory.** Disable it and use any Fastify auth plugin:
-
-```typescript
-import { createApp } from '@classytic/arc';
-
-// Disable Arc's JWT auth
-const app = await createApp({
-  auth: false, // Use your own auth strategy
-});
-
-// Use @fastify/oauth2 for Google login
-await app.register(require('@fastify/oauth2'), {
-  name: 'googleOAuth',
-  credentials: {
-    client: {
-      id: process.env.GOOGLE_CLIENT_ID,
-      secret: process.env.GOOGLE_CLIENT_SECRET,
-    },
-    auth: {
-      authorizeHost: 'https://accounts.google.com',
-      authorizePath: '/o/oauth2/v2/auth',
-      tokenHost: 'https://www.googleapis.com',
-      tokenPath: '/oauth2/v4/token',
-    },
-  },
-  startRedirectPath: '/auth/google',
-  callbackUri: 'http://localhost:8080/auth/google/callback',
-  scope: ['profile', 'email'],
-});
-
-// OAuth callback - issue JWT
-app.get('/auth/google/callback', async (request, reply) => {
-  const { token } = await app.googleOAuth.getAccessTokenFromAuthorizationCodeFlow(request);
-
-  // Fetch user info from Google
-  const userInfo = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
-    headers: { Authorization: `Bearer ${token.access_token}` },
-  }).then(r => r.json());
-
-  // Create user in your database
-  const user = await User.findOneAndUpdate(
-    { email: userInfo.email },
-    { email: userInfo.email, name: userInfo.name, googleId: userInfo.id },
-    { upsert: true, new: true }
-  );
-
-  // Issue JWT using Arc's auth (or use sessions/cookies)
-  const jwtToken = app.jwt.sign({ _id: user._id, email: user.email });
-
-  return reply.send({ token: jwtToken, user });
-});
-```
-
-**See [examples/custom-auth-providers.ts](examples/custom-auth-providers.ts) for:**
-- OAuth (Google, Facebook)
-- Passport.js integration
-- Custom authentication strategies
-- SAML/SSO for enterprise
-- Hybrid auth (JWT + API keys)
-
-### Resources
-
-A resource encapsulates model, repository, controller, and routes:
-
-```typescript
-import { defineResource, createMongooseAdapter, allowPublic, requireRoles } from '@classytic/arc';
-
-export default defineResource({
-  name: 'product',
-  adapter: createMongooseAdapter({
-    model: ProductModel,
-    repository: productRepository,
-  }),
-  controller: productController,
-
-  // Presets add common functionality
-  presets: [
-    'softDelete',      // deletedAt field, restore endpoint
-    'slugLookup',      // GET /products/:slug
-    'ownedByUser',     // createdBy ownership checks
-    'multiTenant',     // organizationId isolation
-    'tree',            // Hierarchical data support
-  ],
-
-  // Permission functions (NOT string arrays)
-  permissions: {
-    list: allowPublic(),                     // Public
-    get: allowPublic(),                      // Public
-    create: requireRoles(['admin', 'editor']), // Restricted
-    update: requireRoles(['admin', 'editor']),
-    delete: requireRoles(['admin']),
-  },
-
-  // Custom routes beyond CRUD
+  cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] }, // QueryCache (opt-in)
   additionalRoutes: [
-    {
-      method: 'GET',
-      path: '/featured',
-      handler: 'getFeatured',        // Controller method name
-      permissions: allowPublic(),    // Permission function
-      wrapHandler: true,             // Arc context pattern (IRequestContext)
-    },
-    {
-      method: 'GET',
-      path: '/:id/download',
-      handler: 'downloadFile',       // Fastify native handler
-      permissions: requireAuth(),
-      wrapHandler: false,            // Native Fastify (request, reply)
-    },
+    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic(), wrapHandler: true },
   ],
 });
-```
-
-### Controllers
-
-Extend BaseController for built-in security and CRUD:
-
-```typescript
-import { BaseController } from '@classytic/arc';
-import type { IRequestContext, IControllerResponse } from '@classytic/arc';
-import type { ISoftDeleteController, ISlugLookupController } from '@classytic/arc/presets';
-
-// Type-safe controller with preset interfaces
-class ProductController
-  extends BaseController<Product>
-  implements ISoftDeleteController<Product>, ISlugLookupController<Product>
-{
-  constructor() {
-    super(productRepository);
-  }
-
-  // Custom method - Arc context pattern
-  async getFeatured(req: IRequestContext): Promise<IControllerResponse> {
-    const { organizationId } = req;
-
-    const products = await this.repository.findAll({
-      filter: { isFeatured: true, organizationId },
-    });
 
-    return { success: true, data: products };
-  }
-
-  // Preset methods
-  async getBySlug(req: IRequestContext): Promise<IControllerResponse> {
-    const { slug } = req.params;
-    const product = await this.repository.getBySlug(slug);
-
-    if (!product) {
-      return { success: false, error: 'Product not found', status: 404 };
-    }
-
-    return { success: true, data: product };
-  }
-}
-```
-
-**Preset Type Interfaces:** Arc exports TypeScript interfaces for each preset that requires controller methods:
-
-- `ISoftDeleteController` - requires `getDeleted()` and `restore()`
-- `ISlugLookupController` - requires `getBySlug()`
-- `ITreeController` - requires `getTree()` and `getChildren()`
-
-**Note:** Presets like `multiTenant`, `ownedByUser`, and `audited` don't require controller methods—they work via middleware.
-
-### Request Context API
-
-Controller methods receive `req: IRequestContext`:
-
-```typescript
-interface IRequestContext {
-  params: Record<string, string>;           // Route params: /users/:id
-  query: Record<string, unknown>;           // Query string: ?page=1
-  body: unknown;                            // Request body
-  user: UserBase | null;                    // Authenticated user
-  headers: Record<string, string | undefined>; // Request headers
-  organizationId?: string;                  // Multi-tenant org ID
-  metadata?: Record<string, unknown>;       // Custom data, _policyFilters, middleware context
-}
+// Auto-generates: GET /, GET /:id, POST /, PATCH /:id, DELETE /:id
+// Plus preset routes: GET /deleted, POST /:id/restore, GET /slug/:slug
 ```
 
-**Key Fields:**
-- `req.metadata` - Custom data from hooks, policies, or middleware
-- `req.organizationId` - Set by `multiTenant` preset or org scope plugin
-- `req.user` - Set by auth plugin, preserves original auth structure
-
-### TypeScript Strict Mode
+## Authentication
 
-For maximum type safety:
+Auth uses a discriminated union — pick a `type`:
 
 ```typescript
-import { BaseController, IRequestContext, IControllerResponse } from '@classytic/arc';
-import type { ISoftDeleteController, ISlugLookupController } from '@classytic/arc/presets';
-
-interface Product {
-  _id: string;
-  name: string;
-  slug: string;
-  price: number;
-  deletedAt?: Date;
-}
-
-class ProductController
-  extends BaseController<Product>
-  implements ISoftDeleteController<Product>, ISlugLookupController<Product>
-{
-  async getBySlug(req: IRequestContext): Promise<IControllerResponse<Product>> {
-    const { slug } = req.params;
-    const product = await this.repository.getBySlug(slug);
+// Arc JWT
+auth: { type: 'jwt', jwt: { secret: process.env.JWT_SECRET, expiresIn: '15m' } }
 
-    if (!product) {
-      return { success: false, error: 'Product not found', status: 404 };
-    }
+// Better Auth (recommended for SaaS with orgs)
+import { createBetterAuthAdapter } from '@classytic/arc/auth';
+auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth, orgContext: true }) }
 
-    return { success: true, data: product };
-  }
+// Custom plugin
+auth: { type: 'custom', plugin: myAuthPlugin }
 
-  async getDeleted(req: IRequestContext): Promise<IControllerResponse<Product[]>> {
-    const products = await this.repository.findDeleted();
-    return { success: true, data: products };
-  }
+// Custom function
+auth: { type: 'authenticator', authenticate: async (req, reply) => { ... } }
 
-  async restore(req: IRequestContext): Promise<IControllerResponse<Product>> {
-    const { id } = req.params;
-    const product = await this.repository.restore(id);
-    return { success: true, data: product };
-  }
-}
+// Disabled
+auth: false
 ```
 
-**Benefits:**
-- Compile-time type checking
-- IntelliSense autocomplete
-- Safe refactoring
+**Decorates:** `app.authenticate`, `app.optionalAuthenticate`, `app.authorize`
 
-### Repositories
+## Permissions
 
-Repositories come from your chosen database kit (Arc is database-agnostic):
+Function-based, composable:
 
-**MongoDB with MongoKit:**
 ```typescript
-import { Repository, softDeletePlugin } from '@classytic/mongokit';
-
-class ProductRepository extends Repository {
-  constructor() {
-    super(ProductModel, [softDeletePlugin()]);
-  }
-
-  async getBySlug(slug) {
-    return this.Model.findOne({ slug }).lean();
-  }
+import {
+  allowPublic, requireAuth, requireRoles, requireOwnership,
+  requireOrgMembership, requireOrgRole, allOf, anyOf, denyAll,
+  createDynamicPermissionMatrix,
+} from '@classytic/arc';
+
+permissions: {
+  list: allowPublic(),
+  get: requireAuth(),
+  create: requireRoles(['admin', 'editor']),
+  update: anyOf(requireOwnership('userId'), requireRoles(['admin'])),
+  delete: allOf(requireAuth(), requireRoles(['admin'])),
 }
 ```
 
-**Prisma (coming soon):**
-```typescript
-import { PrismaRepository } from '@classytic/prismakit';
-
-class ProductRepository extends PrismaRepository {
-  // Same interface, different database
-}
-```
-
-## CLI Commands
-
-```bash
-# Generate resource scaffold
-arc generate resource product --module catalog --presets softDelete,slugLookup
-
-# Show all registered resources (loads from entry file)
-arc introspect --entry ./src/index.js
-
-# Export OpenAPI spec (loads from entry file)
-arc docs ./docs/openapi.json --entry ./src/index.js
-
-# Note: --entry flag loads your resource definitions into the registry
-# Point it to the file that imports all your resources
-```
-
-## Environment Presets
-
-### Production
-- Info-level logging
-- Strict CORS (must configure origin)
-- Rate limiting: **100 req/min/IP** (configurable via `rateLimit.max` option)
-- Helmet with CSP
-- Health monitoring (under-pressure)
-- All security plugins enabled
-
-> **💡 Tip**: Default rate limit (100 req/min) may be conservative for high-traffic APIs. Adjust via:
-> ```typescript
-> createApp({ rateLimit: { max: 300, timeWindow: '1 minute' } })
-> ```
-
-> **Note**: Compression is not included due to known Fastify 5 stream issues. Use a reverse proxy (Nginx, Caddy) or CDN for response compression.
-
-### Development
-- Debug logging
-- Permissive CORS
-- Rate limiting: 1000 req/min (development-friendly)
-- Relaxed security
-
-### Testing
-- Silent logging
-- No CORS restrictions
-- Rate limiting: disabled (test performance)
-- Minimal security overhead
-
-## Serverless Deployment
-
-### AWS Lambda
-
-```typescript
-import { createLambdaHandler } from './index.factory.js';
-
-export const handler = await createLambdaHandler();
-```
-
-### Google Cloud Run
+**Field-level permissions:**
 
 ```typescript
-import { cloudRunHandler } from './index.factory.js';
-import { createServer } from 'http';
-
-createServer(cloudRunHandler).listen(process.env.PORT || 8080);
-```
+import { fields } from '@classytic/arc';
 
-### Vercel
-
-```typescript
-import { vercelHandler } from './index.factory.js';
-
-export default vercelHandler;
+fields: {
+  password: fields.hidden(),
+  salary: fields.visibleTo(['admin', 'hr']),
+  role: fields.writableBy(['admin']),
+  email: fields.redactFor(['viewer'], '***'),
+}
 ```
 
-## Testing Utilities
-
-### Test App Creation with In-Memory MongoDB
-
-Arc's testing utilities now include **in-memory MongoDB by default** for 10x faster tests.
+**Dynamic ACL (DB-managed):**
 
 ```typescript
-import { createTestApp } from '@classytic/arc/testing';
-import type { TestAppResult } from '@classytic/arc/testing';
-
-describe('API Tests', () => {
-  let testApp: TestAppResult;
-
-  beforeAll(async () => {
-    // Creates app + starts in-memory MongoDB automatically
-    testApp = await createTestApp({
-      auth: { jwt: { secret: 'test-secret-32-chars-minimum-len' } },
-    });
-
-    // Connect your models to the in-memory DB
-    await mongoose.connect(testApp.mongoUri);
-  });
-
-  afterAll(async () => {
-    // Cleans up DB and closes app
-    await testApp.close();
-  });
-
-  test('GET /products', async () => {
-    const response = await testApp.app.inject({
-      method: 'GET',
-      url: '/products',
-    });
-    expect(response.statusCode).toBe(200);
-  });
+const acl = createDynamicPermissionMatrix({
+  resolveRolePermissions: async (ctx) => aclService.getRoleMatrix(orgId),
+  cacheStore: new RedisCacheStore({ client: redis, prefix: 'acl:' }),
 });
-```
 
-**Performance:** In-memory MongoDB requires `mongodb-memory-server` (dev dependency). Tests run 10x faster than external MongoDB.
-
-```bash
-npm install -D mongodb-memory-server
-```
-
-**Using External MongoDB:**
-
-```typescript
-const testApp = await createTestApp({
-  auth: { jwt: { secret: 'test-secret-32-chars-minimum-len' } },
-  useInMemoryDb: false,
-  mongoUri: 'mongodb://localhost:27017/test-db',
-});
+permissions: {
+  list: acl.canAction('product', 'read'),
+  create: acl.canAction('product', 'create'),
+}
 ```
 
-**Note:** Arc's testing preset disables security plugins for faster tests.
-
-### Mock Factories
-
-```typescript
-import { createMockRepository, createDataFactory } from '@classytic/arc/testing';
-
-// Mock repository
-const mockRepo = createMockRepository({
-  findById: jest.fn().mockResolvedValue({ _id: '123', name: 'Test' }),
-});
-
-// Data factory
-const productFactory = createDataFactory({
-  name: (i) => `Product ${i}`,
-  price: (i) => 100 + i * 10,
-  isActive: () => true,
-});
+## Presets
 
-const products = productFactory.buildMany(5);
-```
+Composable resource behaviors:
 
-### Database Helpers
+| Preset | Effect | Config |
+|--------|--------|--------|
+| `softDelete` | `GET /deleted`, `POST /:id/restore`, `deletedAt` field | `{ deletedField }` |
+| `slugLookup` | `GET /slug/:slug` | `{ slugField }` |
+| `tree` | `GET /tree`, `GET /:parent/children` | `{ parentField }` |
+| `ownedByUser` | Auto-checks `createdBy` on update/delete | `{ ownerField }` |
+| `multiTenant` | Auto-filters all queries by tenant | `{ tenantField }` |
+| `audited` | Sets `createdBy`/`updatedBy` from user | — |
 
 ```typescript
-import { withTestDb } from '@classytic/arc/testing';
-
-describe('Product Repository', () => {
-  withTestDb((db) => {
-    it('should create product', async () => {
-      const product = await Product.create({ name: 'Test' });
-      expect(product.name).toBe('Test');
-    });
-  });
-});
+presets: ['softDelete', { name: 'multiTenant', tenantField: 'organizationId' }]
 ```
 
-## State Machine
+## QueryCache
 
-```typescript
-import { createStateMachine } from '@classytic/arc/utils';
-
-const orderStateMachine = createStateMachine('order', {
-  submit: {
-    from: ['draft'],
-    to: 'pending',
-    guard: ({ data }) => data.items.length > 0,
-    after: async ({ from, to, data }) => {
-      await sendNotification(data.userId, 'Order submitted');
-    },
-  },
-  approve: {
-    from: ['pending'],
-    to: 'approved',
-  },
-  ship: {
-    from: ['approved'],
-    to: 'shipped',
-  },
-  cancel: {
-    from: ['draft', 'pending'],
-    to: 'cancelled',
-  },
-}, { trackHistory: true });
-
-// Usage
-orderStateMachine.can('submit', 'draft'); // true
-orderStateMachine.assert('submit', 'draft'); // throws if invalid
-orderStateMachine.getAvailableActions('pending'); // ['approve', 'cancel']
-orderStateMachine.getHistory(); // Array of transitions
-```
-
-## Hooks System
+TanStack Query-inspired server cache with stale-while-revalidate and auto-invalidation:
 
 ```typescript
-import { hookRegistry } from '@classytic/arc/hooks';
-
-// Register hook
-hookRegistry.register('product', 'beforeCreate', async (context) => {
-  context.data.slug = slugify(context.data.name);
+// Enable globally
+const app = await createApp({
+  arcPlugins: { queryCache: true },  // Memory store by default
 });
 
-// Available hooks
-// beforeCreate, afterCreate
-// beforeUpdate, afterUpdate
-// beforeDelete, afterDelete
-// beforeList, afterList
-```
-
-## Policies
-
-```typescript
-import { definePolicy } from '@classytic/arc/policies';
-
-const ownedByUserPolicy = definePolicy({
-  name: 'ownedByUser',
-  apply: async (query, req) => {
-    if (!req.user) throw new Error('Unauthorized');
-    query.filter.createdBy = req.user._id;
-    return query;
+// Per-resource config
+defineResource({
+  name: 'product',
+  cache: {
+    staleTime: 30,    // seconds fresh
+    gcTime: 300,      // seconds stale data kept (SWR window)
+    tags: ['catalog'],
+    invalidateOn: { 'category.*': ['catalog'] }, // cross-resource
   },
 });
-
-// Apply in resource
-export default defineResource({
-  name: 'document',
-  policies: [ownedByUserPolicy],
-  // ...
-});
 ```
 
-## Events
+**How it works:**
+- `GET` requests: cached with `x-cache: HIT | STALE | MISS` header
+- `POST/PATCH/DELETE`: auto-bumps resource version, invalidating all cached queries
+- Cross-resource: category mutation bumps `catalog` tag, invalidates product cache
+- Multi-tenant safe: cache keys scoped by userId + orgId
 
-```typescript
-import { eventPlugin } from '@classytic/arc/events';
+**Runtime modes:**
 
-await fastify.register(eventPlugin);
+| Mode | Store | Config |
+|------|-------|--------|
+| `memory` (default) | `MemoryCacheStore` (50 MiB budget) | Zero config |
+| `distributed` | `RedisCacheStore` | `stores: { queryCache: new RedisCacheStore({ client: redis }) }` |
 
-// Emit event
-await fastify.events.publish('order.created', { orderId: '123', userId: '456' });
+## BaseController
 
-// Subscribe
-const unsubscribe = await fastify.events.subscribe('order.created', async (event) => {
-  await sendConfirmationEmail(event.payload.userId);
-});
-
-// Unsubscribe
-unsubscribe();
-```
-
-## Introspection
+Override only what you need:
 
 ```typescript
-import { resourceRegistry } from '@classytic/arc/registry';
-
-// Get all resources
-const resources = resourceRegistry.getAll();
+import { BaseController } from '@classytic/arc';
+import type { IRequestContext, IControllerResponse } from '@classytic/arc';
 
-// Get specific resource
-const product = resourceRegistry.get('product');
+class ProductController extends BaseController<Product> {
+  constructor() { super(productRepo); }
 
-// Get stats
-const stats = resourceRegistry.getStats();
-// { total: 15, withPresets: 8, withPolicies: 5 }
+  async getFeatured(req: IRequestContext): Promise<IControllerResponse> {
+    const products = await this.repository.getAll({ filters: { isFeatured: true } });
+    return { success: true, data: products };
+  }
+}
 ```
 
-## Production Features (Meta/Stripe Tier)
-
-### OpenTelemetry Distributed Tracing
-
-```typescript
-import { tracingPlugin } from '@classytic/arc/plugins';
-
-await fastify.register(tracingPlugin, {
-  serviceName: 'my-api',
-  exporterUrl: 'http://localhost:4318/v1/traces',
-  sampleRate: 0.1, // Trace 10% of requests
-});
-
-// Custom spans
-import { createSpan } from '@classytic/arc/plugins';
-
-return createSpan(req, 'expensiveOperation', async (span) => {
-  span.setAttribute('userId', req.user._id);
-  return await processData();
-});
-```
+## Events
 
-### Enhanced Health Checks
+Domain event pub/sub with pluggable transports. The factory auto-registers `eventPlugin` — no manual setup needed:
 
 ```typescript
-import { healthPlugin } from '@classytic/arc/plugins';
-
-await fastify.register(healthPlugin, {
-  metrics: true, // Prometheus metrics
-  checks: [
-    {
-      name: 'mongodb',
-      check: async () => mongoose.connection.readyState === 1,
-      critical: true,
-    },
-    {
-      name: 'redis',
-      check: async () => redisClient.ping() === 'PONG',
-      critical: true,
+// createApp() registers eventPlugin automatically (default: MemoryEventTransport)
+// Transport is sourced from stores.events if provided
+const app = await createApp({
+  stores: { events: new RedisEventTransport(redis) },  // optional, defaults to memory
+  arcPlugins: {
+    events: {                     // event plugin config (default: true)
+      logEvents: true,
+      retry: { maxRetries: 3, backoffMs: 1000 },
     },
-  ],
+  },
 });
 
-// Endpoints: /_health/live, /_health/ready, /_health/metrics
+await app.events.publish('order.created', { orderId: '123' });
+await app.events.subscribe('order.*', async (event) => { ... });
 ```
 
-### Circuit Breaker
-
-```typescript
-import { CircuitBreaker } from '@classytic/arc/utils';
-
-const stripeBreaker = new CircuitBreaker(
-  async (amount) => stripe.charges.create({ amount }),
-  {
-    failureThreshold: 5,
-    resetTimeout: 30000,
-    fallback: async (amount) => queuePayment(amount),
-  }
-);
-
-const charge = await stripeBreaker.call(1000);
-```
+CRUD events (`product.created`, `product.updated`, `product.deleted`) emit automatically.
 
-### Schema Versioning & Migrations
+## Factory — createApp()
 
 ```typescript
-import { defineMigration, MigrationRunner } from '@classytic/arc/migrations';
-
-const productV2 = defineMigration({
-  version: 2,
-  resource: 'product',
-  up: async (db) => {
-    await db.collection('products').updateMany(
-      {},
-      { $rename: { oldField: 'newField' } }
-    );
+const app = await createApp({
+  preset: 'production',           // production | development | testing | edge
+  runtime: 'memory',             // memory (default) | distributed (requires Redis)
+  auth: { type: 'jwt', jwt: { secret } },
+  cors: { origin: ['https://myapp.com'] },
+  helmet: true,                   // false to disable
+  rateLimit: { max: 100 },        // false to disable
+  arcPlugins: {
+    events: true,                 // event plugin (default: true, false to disable)
+    emitEvents: true,             // CRUD event emission (default: true)
+    queryCache: true,             // server cache (default: false)
+    sse: true,                    // server-sent events (default: false)
+    caching: true,                // ETag + Cache-Control (default: false)
   },
-  down: async (db) => {
-    await db.collection('products').updateMany(
-      {},
-      { $rename: { 'newField': 'oldField' } }
-    );
+  stores: {                       // required when runtime: 'distributed'
+    events: new RedisEventTransport({ client: redis }),
+    cache: new RedisCacheStore({ client: redis }),
+    queryCache: new RedisCacheStore({ client: redis, prefix: 'arc:qc:' }),
   },
 });
-
-const runner = new MigrationRunner(mongoose.connection.db);
-await runner.up([productV2]);
 ```
 
-**See [PRODUCTION_FEATURES.md](../../PRODUCTION_FEATURES.md) for complete guides.**
-
-## Battle-Tested Deployments
+**Arc plugins defaults:**
 
-Arc has been validated in multiple production environments:
+| Plugin | Default | Status |
+|--------|---------|--------|
+| `events` | `true` | opt-out — registers `eventPlugin` (provides `fastify.events`) |
+| `emitEvents` | `true` | opt-out — CRUD operations emit domain events |
+| `requestId` | `true` | opt-out |
+| `health` | `true` | opt-out |
+| `gracefulShutdown` | `true` | opt-out |
+| `caching` | `false` | opt-in — ETag + Cache-Control headers |
+| `queryCache` | `false` | opt-in — TanStack Query-inspired server cache |
+| `sse` | `false` | opt-in — Server-Sent Events streaming |
 
-### Environment Compatibility
+| Preset | Logging | Rate Limit | Security |
+|--------|---------|------------|----------|
+| production | info | 100/min | full |
+| development | debug | 1000/min | relaxed |
+| testing | silent | disabled | minimal |
+| edge | warn | disabled | none (API GW handles) |
 
-| Environment | Status | Notes |
-|-------------|--------|-------|
-| Docker | ✅ Tested | Use Node 18+ Alpine images |
-| Kubernetes | ✅ Tested | Health checks + graceful shutdown built-in |
-| AWS Lambda | ✅ Tested | Use `@fastify/aws-lambda` adapter |
-| Google Cloud Run | ✅ Tested | Auto-scales, health checks work OOTB |
-| Vercel Serverless | ✅ Tested | Use serverless functions adapter |
-| Bare Metal / VPS | ✅ Tested | PM2 or systemd recommended |
-| Railway / Render | ✅ Tested | Works with zero config |
+## Real-Time
 
-### Production Checklist
-
-Before deploying to production:
+SSE and WebSocket with fail-closed auth (throws at registration if auth missing):
 
 ```typescript
-import { createApp, validateEnv } from '@classytic/arc';
-
-// 1. Validate environment variables at startup
-validateEnv({
-  JWT_SECRET: { required: true, min: 32 },
-  DATABASE_URL: { required: true },
-  NODE_ENV: { required: true, values: ['production', 'staging'] },
-});
-
-// 2. Use production environment preset
+// SSE — via factory
 const app = await createApp({
-  environment: 'production',
-
-  // 3. Configure CORS properly (never use origin: true)
-  cors: {
-    origin: process.env.ALLOWED_ORIGINS?.split(',') || [],
-    credentials: true,
-  },
-
-  // 4. Adjust rate limits for your traffic
-  rateLimit: {
-    max: 300,              // Requests per window
-    timeWindow: '1 minute',
-    ban: 10,               // Ban after 10 violations
-  },
-
-  // 5. Enable health checks
-  healthCheck: true,
+  arcPlugins: { sse: { path: '/events', requireAuth: true, orgScoped: true } },
+});
 
-  // 6. Configure logging
-  logger: {
-    level: 'info',
-    redact: ['req.headers.authorization'],
-  },
+// WebSocket — separate plugin
+import { websocketPlugin } from '@classytic/arc/integrations/websocket';
+await app.register(websocketPlugin, {
+  auth: true,                       // fail-closed: throws if authenticate not registered
+  resources: ['product', 'order'],
+  roomPolicy: (client, room) => ['product', 'order'].includes(room),
+  maxMessageBytes: 16384,           // 16KB message size cap
+  maxSubscriptionsPerClient: 100,   // prevent resource exhaustion
 });
 
-// 7. Graceful shutdown
-process.on('SIGTERM', () => app.close());
-process.on('SIGINT', () => app.close());
+// EventGateway — unified SSE + WebSocket with shared config
+import { eventGatewayPlugin } from '@classytic/arc/integrations/event-gateway';
+await app.register(eventGatewayPlugin, {
+  auth: true, orgScoped: true,
+  roomPolicy: (client, room) => allowedRooms.includes(room),
+  sse: { path: '/api/events', patterns: ['order.*'] },
+  ws: { path: '/ws', resources: ['product', 'order'] },
+});
 ```
 
-### Multi-Region Deployment
+## Integrations
 
-For globally distributed apps:
+All separate subpath imports — only loaded when used:
 
 ```typescript
-// Use read replicas
-const app = await createApp({
-  mongodb: {
-    primary: process.env.MONGODB_PRIMARY,
-    replicas: process.env.MONGODB_REPLICAS?.split(','),
-    readPreference: 'nearest',
-  },
+// Job Queue (BullMQ)
+import { jobsPlugin, defineJob } from '@classytic/arc/integrations/jobs';
 
-  // Distributed tracing for multi-region debugging
-  tracing: {
-    enabled: true,
-    serviceName: `api-${process.env.REGION}`,
-    exporter: 'zipkin',
-  },
-});
-```
+// WebSocket (room-based, CRUD auto-broadcast)
+import { websocketPlugin } from '@classytic/arc/integrations/websocket';
 
-### Load Testing Results
+// EventGateway (unified SSE + WebSocket)
+import { eventGatewayPlugin } from '@classytic/arc/integrations/event-gateway';
 
-Arc has been load tested with the following results:
+// Streamline Workflows
+import { streamlinePlugin } from '@classytic/arc/integrations/streamline';
 
-- **Throughput**: 10,000+ req/s (single instance, 4 CPU cores)
-- **Latency**: P50: 8ms, P95: 45ms, P99: 120ms
-- **Memory**: ~50MB base + ~0.5MB per 1000 requests
-- **Connections**: Handles 10,000+ concurrent connections
-- **Database**: Tested with 1M+ documents, sub-10ms queries with proper indexes
+// Audit Trail
+import { auditPlugin } from '@classytic/arc/audit';
 
-*Results vary based on hardware, database, and business logic complexity.*
+// Idempotency (exactly-once mutations)
+import { idempotencyPlugin } from '@classytic/arc/idempotency';
 
-## Performance Tips
-
-1. **Use Proxy Compression** - Use Nginx/Caddy or CDN for Brotli/gzip compression
-2. **Enable Memory Monitoring** - Detect leaks early in production
-3. **Use Testing Preset** - Minimal overhead for test suites
-4. **Apply Indexes** - Always index query fields in models
-5. **Use Lean Queries** - Repository returns plain objects by default
-6. **Rate Limiting** - Protect endpoints from abuse
-7. **Validate Early** - Use environment validator at startup
-8. **Distributed Tracing** - Track requests across services (5ms overhead)
-9. **Circuit Breakers** - Prevent cascading failures (<1ms overhead)
-10. **Health Checks** - K8s-compatible liveness/readiness probes
+// OpenTelemetry Tracing
+import { tracingPlugin } from '@classytic/arc/plugins/tracing';
+```
 
-## Security Best Practices
+## CLI
 
-1. **Opt-out Security** - All plugins enabled by default in production
-2. **Strong Secrets** - Minimum 32 characters for JWT/session secrets
-3. **CORS Configuration** - Never use `origin: true` in production
-4. **Permission Checks** - Always define permissions per operation
-5. **Multi-tenant Isolation** - Use `multiTenant` preset for SaaS apps
-6. **Ownership Checks** - Use `ownedByUser` preset for user data
-7. **Audit Logging** - Track all changes with audit plugin
+```bash
+arc init my-api --mongokit --better-auth --ts   # Scaffold project
+arc generate resource product                    # Generate resource files
+arc docs ./openapi.json --entry ./dist/index.js  # Export OpenAPI
+arc introspect --entry ./dist/index.js           # Show resources
+arc doctor                                        # Health check
+```
+
+## Subpath Imports
+
+| Import | Purpose |
+|--------|---------|
+| `@classytic/arc` | Core: `defineResource`, `BaseController`, permissions, errors |
+| `@classytic/arc/factory` | `createApp()`, presets |
+| `@classytic/arc/cache` | `MemoryCacheStore`, `RedisCacheStore`, `QueryCache` |
+| `@classytic/arc/auth` | Auth plugin, Better Auth adapter, session manager |
+| `@classytic/arc/events` | Event plugin, memory transport |
+| `@classytic/arc/events/redis` | Redis event transport |
+| `@classytic/arc/events/redis-stream` | Redis Streams transport |
+| `@classytic/arc/plugins` | Health, graceful shutdown, request ID, SSE, caching |
+| `@classytic/arc/plugins/tracing` | OpenTelemetry |
+| `@classytic/arc/permissions` | All permission functions |
+| `@classytic/arc/scope` | Request scope helpers (`isMember`, `isElevated`, `getOrgId`) |
+| `@classytic/arc/org` | Organization module |
+| `@classytic/arc/hooks` | Lifecycle hooks |
+| `@classytic/arc/presets` | Preset functions + interfaces |
+| `@classytic/arc/audit` | Audit trail |
+| `@classytic/arc/idempotency` | Idempotency |
+| `@classytic/arc/policies` | Policy engine |
+| `@classytic/arc/schemas` | TypeBox helpers |
+| `@classytic/arc/utils` | Errors, circuit breaker, state machine, query parser |
+| `@classytic/arc/testing` | Test utilities, mocks, in-memory DB |
+| `@classytic/arc/migrations` | Schema migrations |
+| `@classytic/arc/integrations/jobs` | BullMQ job queue |
+| `@classytic/arc/integrations/websocket` | WebSocket |
+| `@classytic/arc/integrations/event-gateway` | Unified SSE + WebSocket gateway |
+| `@classytic/arc/integrations/streamline` | Workflow orchestration |
+| `@classytic/arc/docs` | OpenAPI generation |
+| `@classytic/arc/cli` | CLI commands |
+
+## Documentation
+
+- [Setup](docs/getting-started/setup.md) — Project setup
+- [Core Concepts](docs/getting-started/core.md) — Resources, controllers, adapters
+- [Authentication](docs/getting-started/auth.md) — JWT, Better Auth, custom auth
+- [Permissions](docs/getting-started/permissions.md) — RBAC, ABAC, field-level
+- [Presets](docs/getting-started/presets.md) — softDelete, multiTenant, tree, etc.
+- [Organizations](docs/getting-started/org.md) — Multi-tenant SaaS
+- [Factory](docs/production-ops/factory.md) — createApp() and environment presets
+- [Events](docs/production-ops/events.md) — Domain events and transports
+- [Plugins](docs/production-ops/plugins.md) — Health, caching, SSE, tracing
+- [Hooks](docs/framework-extension/hooks.md) — Lifecycle hooks
 
 ## License