arcway 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,6 @@
 # Arcway
 
-A convention-based TypeScript framework for building modular monoliths with strict domain boundaries.
-
-Arcway uses file-system conventions to discover routes, services, jobs, events, and middleware — no manual wiring required. Each domain is isolated with its own database scope, event emitter, queue, cache, and file storage.
+A convention-based JavaScript framework for building full-stack applications. File-system conventions discover routes, jobs, events, and middleware automatically — no manual wiring required.
 
 ## Quick Start
 
@@ -14,55 +12,47 @@ Create a project:
 
 ```
 my-app/
-├── arcway.config.ts
-├── domains/
+├── arcway.config.js
+├── api/
 │   └── users/
-│       ├── config.ts
-│       └── api/
-│           └── index.ts
-└── db/
-    └── migrations/
+│       └── index.js
+└── migrations/
+    └── 20260101000000-create-users.js
 ```
 
-**arcway.config.ts**
-
-```typescript
-import type { FrameworkConfig } from 'arcway';
+**arcway.config.js**
 
+```js
 export default {
   database: {
     client: 'sqlite',
     connection: './dev.db',
   },
-} satisfies FrameworkConfig;
-```
-
-**domains/users/config.ts**
-
-```typescript
-import type { DomainConfig } from 'arcway';
-
-export default {
-  name: 'users',
-  tables: ['users'],
-} satisfies DomainConfig;
+};
 ```
 
-**domains/users/api/index.ts**
+**api/users/index.js**
 
-```typescript
-import type { RouteMethodConfig } from 'arcway';
+```js
+import { type } from 'arcway';
 
-export const GET: RouteMethodConfig = {
+export const GET = {
   handler: async (ctx) => {
     const users = await ctx.db('users').select('*');
     return { data: users };
   },
 };
 
-export const POST: RouteMethodConfig = {
+export const POST = {
+  schema: {
+    body: type({
+      name: 'string >= 1',
+      email: 'string.email',
+    }),
+  },
   handler: async (ctx) => {
-    const [id] = await ctx.db('users').insert(ctx.body);
+    const [id] = await ctx.db('users').insert(ctx.req.body);
+    await ctx.events.emit('users/created', { userId: id });
     return { status: 201, data: { id } };
   },
 };
@@ -80,58 +70,52 @@ This boots the full stack: database, migrations, route discovery, event bus, job
 
 | Command                         | Description                                                        |
 | ------------------------------- | ------------------------------------------------------------------ |
-| `arcway dev`                      | Start development server (console logging, CORS enabled)           |
-| `arcway start`                    | Start production server (JSON logging, health check at `/health`)  |
-| `arcway build [outDir]`           | Compile TypeScript to production bundle (default: `dist`)          |
-| `arcway seed`                     | Run database seed files from `db/seeds/`                           |
-| `arcway docs [outFile]`           | Generate OpenAPI spec from route schemas (default: `openapi.json`) |
-| `arcway test [--watch] [pattern]` | Run domain tests (`domains/*/tests/**/*.test.ts`)                  |
-| `arcway lint`                     | Check for domain boundary violations                               |
+| `arcway dev`                    | Start development server (console logging, CORS enabled)           |
+| `arcway start`                  | Start production server (JSON logging, health check at `/health`)  |
+| `arcway build [outDir]`         | Build pages for production                                         |
+| `arcway seed`                   | Run database seed files from `seeds/`                              |
+| `arcway docs [outFile]`         | Generate OpenAPI spec from route schemas (default: `openapi.json`) |
+| `arcway test [--watch] [pattern]` | Run tests                                                        |
+| `arcway lint`                   | Check for boundary violations                                      |
+| `arcway migrate`                | Run database migrations                                            |
+| `arcway schema`                 | Inspect database schema                                            |
 
 ## Project Structure
 
 ```
 project-root/
-├── arcway.config.ts              # Framework configuration
-├── domains/
+├── arcway.config.js              # Framework configuration
+├── api/                          # HTTP route handlers (file-based routing)
 │   ├── users/
-│   │   ├── config.ts                # Domain name, owned tables, events, hooks
-│   │   ├── services/index.ts        # Exported service functions
-│   │   ├── api/                     # HTTP route handlers
-│   │   │   ├── index.ts             # GET /users, POST /users
-│   │   │   ├── [id].ts             # GET /users/:id, PUT /users/:id
-│   │   │   ├── [id]/projects.ts    # GET /users/:id/projects
-│   │   │   ├── admin/settings.ts   # GET /users/admin/settings
-│   │   │   ├── _middleware.ts       # Middleware for all /users/* routes
-│   │   │   └── admin/
-│   │   │       └── _middleware.ts   # Middleware for /users/admin/* only
-│   │   ├── jobs/                    # Background job definitions
-│   │   │   └── send-welcome.ts
-│   │   ├── listeners/               # Event subscribers
-│   │   │   └── on-signup.ts
-│   │   └── tests/                   # Domain unit tests
-│   │       └── users.test.ts
-│   └── billing/
-│       ├── config.ts
-│       ├── services/index.ts
-│       └── listeners/
-│           └── on-user-created.ts
-└── db/
-    ├── migrations/              # Knex migration files
-    │   └── 001_create_tables.js
-    └── seeds/                   # Database seed files
-        └── 001_users.ts
-```
-
-Files starting with `_` (except `_middleware.ts`) are excluded from route/job/listener discovery.
+│   │   ├── index.js              # GET /users, POST /users
+│   │   ├── [id].js               # GET /users/:id, PUT /users/:id, DELETE /users/:id
+│   │   └── _middleware.js         # Middleware for all /users/* routes
+│   └── projects/
+│       ├── index.js              # GET /projects, POST /projects
+│       └── [id].js               # GET /projects/:id, PUT /projects/:id
+├── listeners/                    # Event subscribers (folder path = event name)
+│   └── users/
+│       └── created.js            # Handles 'users/created' event
+├── jobs/                         # Background job definitions
+│   └── send-welcome-email.js
+├── migrations/                   # Database migrations (timestamp-ordered)
+│   └── 20260101000000-create-users.js
+├── seeds/                        # Database seed files
+│   └── 001_users.js
+├── pages/                        # SSR pages (optional)
+│   ├── _layout.jsx               # Root layout
+│   ├── index.jsx                 # Home page
+│   └── about.jsx                 # About page
+└── lib/                          # Shared logic (no framework magic)
+    └── users.js
+```
+
+Files starting with `_` (except `_middleware.js` and `_layout.jsx`) are excluded from route/job/listener discovery.
 
 ## Configuration
 
-### Framework Config
-
-```typescript
-import type { FrameworkConfig } from 'arcway';
-
+```js
+// arcway.config.js
 export default {
   server: {
     port: 3000,
@@ -139,42 +123,58 @@ export default {
     maxBodySize: 1_048_576, // 1 MB
   },
   api: {
+    pathPrefix: '',        // Prefix all API routes (e.g., '/api')
     cors: {
-      // Or true/false
       origin: ['https://app.com'],
       methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
       allowedHeaders: ['Content-Type', 'Authorization'],
-      exposedHeaders: ['X-Request-Id'],
       credentials: true,
       maxAge: 86400,
     },
   },
   database: {
-    client: 'postgres',
+    client: 'postgres',     // 'sqlite', 'postgres', 'mysql'
     connection: 'postgres://user:pass@localhost/mydb',
   },
+  session: {
+    password: 'at-least-32-character-secret-here!!',
+    cookieName: 'arcway.session',
+    ttl: 86400,
+  },
   queue: {
-    driver: 'redis', // 'knex' (default) or 'redis'
-    lockCooldownMs: 300_000,
+    driver: 'redis',       // 'knex' (default) or 'redis'
     redis: { url: 'redis://localhost:6379' },
   },
   cache: {
-    driver: 'redis',
+    driver: 'redis',       // 'memory' (default) or 'redis'
     defaultTtlMs: 60_000,
     redis: { url: 'redis://localhost:6379' },
   },
   events: {
-    driver: 'redis', // 'memory' (default) or 'redis'
+    driver: 'redis',       // 'memory' (default) or 'redis'
     redis: { url: 'redis://localhost:6379' },
   },
   files: {
-    driver: 's3', // 'local' (default) or 's3'
+    driver: 's3',          // 'local' (default) or 's3'
     s3: {
       bucket: 'my-bucket',
       region: 'us-east-1',
     },
   },
-} satisfies FrameworkConfig;
+  mail: {
+    driver: 'smtp',        // 'smtp' or 'console'
+    from: 'noreply@example.com',
+    host: 'smtp.example.com',
+    port: 587,
+    auth: { user: 'user', pass: 'pass' },
+  },
+  jobs: {
+    pollIntervalMs: 60_000,
+  },
+  logger: {
+    level: 'info',         // 'debug', 'info', 'warn', 'error'
+  },
+};
 ```
 
 ### CORS
@@ -188,79 +188,64 @@ Configure with `api.cors`:
 
 - `true` — enable permissive CORS in any mode.
 - `false` — disable CORS entirely.
-- `CorsConfig` object — use specific settings.
+- Object — use specific settings.
 
-### Domain Config
+### Subsystem Toggles
 
-```typescript
-import type { DomainConfig } from 'arcway';
-import { z } from 'zod';
+Any subsystem can be disabled:
 
+```js
 export default {
-  name: 'users',
-  tables: ['users', 'sessions'],
-  events: [
-    { name: 'users/created', schema: z.object({ userId: z.number() }) },
-    { name: 'users/deleted' },
-  ],
-  hooks: {
-    onInit: async (ctx) => {
-      /* Before server starts */
-    },
-    onReady: async (ctx) => {
-      /* After server is listening */
-    },
-    onShutdown: async (ctx) => {
-      /* Graceful shutdown */
-    },
-  },
-} satisfies DomainConfig;
+  api: { enabled: false },
+  pages: { enabled: false },
+  jobs: { enabled: false },
+  events: { enabled: false },
+  mcp: { enabled: false },
+  websocket: { enabled: false },
+  mail: { enabled: false },
+};
 ```
 
 ## Routes
 
-Route files live in `domains/<name>/api/` and map to URL patterns by file path:
+Route files live in `api/` and map to URL patterns by file path:
 
-| File                    | URL Pattern                |
-| ----------------------- | -------------------------- |
-| `api/index.ts`          | `/<domain>`                |
-| `api/[id].ts`           | `/<domain>/:id`            |
-| `api/[id]/projects.ts`  | `/<domain>/:id/projects`   |
-| `api/admin/settings.ts` | `/<domain>/admin/settings` |
+| File                        | URL Pattern             |
+| --------------------------- | ----------------------- |
+| `api/users/index.js`       | `/users`                |
+| `api/users/[id].js`        | `/users/:id`            |
+| `api/users/[id]/posts.js`  | `/users/:id/posts`      |
+| `api/admin/settings.js`    | `/admin/settings`       |
 
 Export named constants for each HTTP method:
 
-```typescript
-import { z } from 'zod';
-import type { RouteMethodConfig } from 'arcway';
+```js
+import { type } from 'arcway';
 
-export const GET: RouteMethodConfig = {
+export const GET = {
   schema: {
-    query: z.object({ page: z.coerce.number().default(1) }),
+    query: type({ 'page?': 'number' }),
   },
   meta: {
     summary: 'List users',
     tags: ['users'],
   },
   handler: async (ctx) => {
-    const users = await ctx
-      .db('users')
-      .select('*')
-      .limit(20)
-      .offset((ctx.query.page - 1) * 20);
+    const page = ctx.req.query.page ?? 1;
+    const users = await ctx.db('users').select('*').limit(20).offset((page - 1) * 20);
     return { data: users };
   },
 };
 
-export const POST: RouteMethodConfig = {
+export const POST = {
   schema: {
-    body: z.object({
-      name: z.string().min(1),
-      email: z.string().email(),
+    body: type({
+      name: 'string >= 1',
+      email: 'string.email',
     }),
   },
   handler: async (ctx) => {
-    const { name, email } = ctx.body as { name: string; email: string };
+    const { name, email } = ctx.req.body;
     const [id] = await ctx.db('users').insert({ name, email });
     await ctx.events.emit('users/created', { userId: id });
     return { status: 201, data: { id } };
@@ -268,197 +253,223 @@ export const POST: RouteMethodConfig = {
 };
 ```
 
-### Route Context
-
-Every handler receives a `RouteContext`:
-
-```typescript
-interface RouteContext {
-  domain: string; // Domain name
-  db: Knex; // Scoped database connection
-  services: ServicesProxy; // Cross-domain service calls
-  events: DomainEvents; // Event emission
-  queue: DomainQueue; // Persistent queue
-  cache: DomainCache; // Key-value cache
-  files: DomainFiles; // File storage
-  params: Record<string, string>; // URL parameters (:id)
-  query: Record<string, string>; // Query string (?key=value)
-  body: unknown; // Parsed request body
-  headers: Record<string, string>; // Request headers
+### Handler Context
+
+Every route handler receives a `ctx` object with infrastructure and request data:
+
+```js
+// ctx contains:
+{
+  db,       // Knex database connection
+  events,   // Event emitter (emit, subscribe)
+  queue,    // Persistent queue (push, pop, remove)
+  cache,    // Key-value cache (get, set, delete, wrap)
+  files,    // File storage (write, read, delete, list, exists)
+  mail,     // Email (send, queue)
+  log,      // Logger (debug, info, warn, error)
+  req: {
+    requestId,  // Unique request ID
+    method,     // HTTP method
+    path,       // URL path
+    query,      // Validated query params (includes URL params like :id)
+    body,       // Validated request body
+    headers,    // Request headers
+    cookies,    // Parsed cookies
+    session,    // Session data (if configured)
+  },
 }
 ```
 
 ### Route Response
 
-```typescript
-interface RouteResponse {
-  status?: number; // Default: 200 (or 400 if error)
-  data?: unknown; // Wrapped in { data: ... }
-  error?: {
-    code: string;
-    message: string;
-    details?: unknown;
-  };
-  headers?: Record<string, string>;
+Handlers return a response object:
+
+```js
+{
+  status: 200,              // HTTP status (default: 200, or 400 if error)
+  data: { ... },            // Wrapped in { data: ... }
+  error: {                  // Wrapped in { error: ... }
+    code: 'NOT_FOUND',
+    message: 'User not found',
+  },
+  headers: { ... },         // Custom response headers
+  session: { userId: 42 },  // Set session (requires session config)
+  // session: null           // Clear session
 }
 ```
 
-## Middleware
+### Validation with ArkType
 
-Place `_middleware.ts` files in `api/` directories. Middleware applies to all routes at that level and below.
+Arcway uses [ArkType](https://arktype.io) for schema validation:
 
-```typescript
-// domains/users/api/_middleware.ts — applies to all /users/* routes
-import type { MiddlewareFn } from 'arcway';
+```js
+import { type } from 'arcway';
 
-const logger: MiddlewareFn = async (ctx, next) => {
-  const start = Date.now();
-  const response = await next();
-  console.log(`${ctx.headers['method']} took ${Date.now() - start}ms`);
-  return response;
+export const POST = {
+  schema: {
+    body: type({
+      name: 'string >= 1',
+      email: 'string.email',
+      'age?': 'number > 0',
+    }),
+  },
+  handler: async (ctx) => {
+    // ctx.req.body is validated and coerced
+    const { name, email, age } = ctx.req.body;
+    // ...
+  },
 };
-
-export default logger;
 ```
 
-```typescript
-// domains/users/api/admin/_middleware.ts — applies to /users/admin/* only
-import type { MiddlewareFn } from 'arcway';
+Invalid requests automatically return `400` with a `VALIDATION_ERROR` code and field-level error details.
 
-const auth: MiddlewareFn = async (ctx, next) => {
-  if (ctx.headers['authorization'] !== 'Bearer valid-token') {
-    return {
-      status: 401,
-      error: { code: 'UNAUTHORIZED', message: 'Invalid token' },
-    };
-  }
-  return next();
-};
+## Middleware
 
-export default auth;
-```
+Place `_middleware.js` files in `api/` directories. Middleware applies to all routes at that level and below.
 
-Middleware can also export an array of functions:
+Middleware must export an object (or array of objects) with a `handler` function:
 
-```typescript
-export default [loggerMiddleware, authMiddleware];
+```js
+// api/_middleware.js — applies to all routes
+export default {
+  handler: async (ctx) => {
+    const start = Date.now();
+    console.log(`${ctx.req.method} ${ctx.req.path} (${Date.now() - start}ms)`);
+    // return undefined to continue to next middleware/handler
+  },
+};
 ```
 
-Middleware chains execute outermost-first. A request to `/users/admin/settings` runs:
-
-1. `/users/api/_middleware.ts` (root)
-2. `/users/api/admin/_middleware.ts` (admin)
-3. Route handler
-
-Return without calling `next()` to short-circuit (e.g., return 401).
-
-## Services
-
-Services enable cross-domain function calls with automatic context injection.
-
-```typescript
-// domains/users/services/index.ts
-import type { DomainContext } from 'arcway';
-
+```js
+// api/admin/_middleware.js — applies to /admin/* only
 export default {
-  getById: async (ctx: DomainContext, id: string) => {
-    return ctx.db('users').where({ id }).first();
-  },
-  list: async (ctx: DomainContext) => {
-    return ctx.db('users').select('*');
+  handler: async (ctx) => {
+    if (ctx.req.headers['authorization'] !== 'Bearer valid-token') {
+      // Return a response to short-circuit the chain
+      return {
+        status: 401,
+        error: { code: 'UNAUTHORIZED', message: 'Invalid token' },
+      };
+    }
+    // return undefined to continue
   },
 };
 ```
 
-Call from another domain — `ctx` is injected automatically:
+Middleware can also have schemas and export an array:
 
-```typescript
-// In a billing route handler
-const user = await ctx.services.users.getById(userId);
+```js
+import { type } from 'arcway';
+
+export default [
+  {
+    schema: { query: type({ 'apiKey': 'string' }) },
+    handler: async (ctx) => {
+      if (!isValidKey(ctx.req.query.apiKey)) {
+        return { status: 403, error: { code: 'FORBIDDEN', message: 'Bad API key' } };
+      }
+    },
+  },
+  { handler: async (ctx) => { /* logging */ } },
+];
 ```
 
+Middleware chains execute outermost-first. Return a response to short-circuit; return `undefined` to continue.
+
 ## Events
 
-Domains declare events they can emit in `config.ts`:
+Emit events from any handler, listener, or job via `ctx.events`:
 
-```typescript
-events: [
-  { name: 'users/created', schema: z.object({ userId: z.number() }) },
-],
+```js
+await ctx.events.emit('users/created', { userId: 42 });
 ```
 
-Emit from any handler, service, or job:
+### Listeners
 
-```typescript
-const results = await ctx.events.emit('users/created', { userId: 42 });
-```
+Listener files live in `listeners/`. The folder path maps to the event name:
 
-Always `await` the emit call — immediate handlers run in-process during emit and their results are returned as an array of `EventResult`.
+| File                           | Event           |
+| ------------------------------ | --------------- |
+| `listeners/users/created.js`   | `users/created` |
+| `listeners/orders/updated.js`  | `orders/updated` |
 
-### Listeners
+Listeners export a default function that receives a context object:
 
-Listeners define how they handle events via two handler functions:
+```js
+// listeners/users/created.js
+export default async (ctx) => {
+  const { event, db } = ctx;
+  // event.name = 'users/created'
+  // event.payload = { userId: 42 }
+  await db('billing_accounts').insert({
+    user_id: event.payload.userId,
+    plan: 'free',
+  });
+};
+```
 
-- **`handler`** — dispatched via the event bus (eventually consistent, fire-and-forget)
-- **`handlerImmediate`** — runs in-process during `emit()`, before bus dispatch
+The listener context includes all infrastructure (`db`, `events`, `cache`, `queue`, `files`, `mail`, `log`) plus `event: { name, payload }`.
 
-At least one must be defined. Both can be defined on the same listener.
+### System Lifecycle Events
 
-```typescript
-// domains/billing/listeners/on-user-created.ts (async — via bus)
-import type { ListenerDefinition } from 'arcway';
+Special listeners in `listeners/system/` handle lifecycle events:
 
-export default {
-  event: 'users/created',
-  handler: async (ctx, payload) => {
-    const { userId } = payload as { userId: number };
-    await ctx.db('billing_accounts').insert({ user_id: userId, balance: 0 });
-  },
-} satisfies ListenerDefinition;
-```
+```js
+// listeners/system/init.js — runs before server starts
+export default async (ctx) => { /* setup */ };
 
-```typescript
-// domains/orgs/listeners/on-user-created.ts (immediate — in-process)
-import type { ListenerDefinition } from 'arcway';
+// listeners/system/ready.js — runs after server is listening
+export default async (ctx) => { /* post-boot */ };
 
-export default {
-  event: 'users/created',
-  handlerImmediate: async (ctx, payload) => {
-    const { userId } = payload as { userId: number };
-    const [org] = await ctx.db('orgs').insert({ owner_id: userId, name: 'My Org' });
-    if (!org) {
-      return { error: { code: 'ORG_CREATE_FAILED', message: 'Failed to create org' } };
-    }
-  },
-} satisfies ListenerDefinition;
+// listeners/system/shutdown.js — runs during graceful shutdown
+export default async (ctx) => { /* cleanup */ };
 ```
 
-Event patterns support wildcards: `'users/*'` matches all events from the users domain.
-
 ## Jobs
 
 Background jobs support one-off queuing and cron scheduling.
 
-```typescript
-// domains/billing/jobs/generate-invoice.ts
-import { z } from 'zod';
-import type { JobDefinition } from 'arcway';
+```js
+// jobs/generate-invoice.js
+import { type } from 'arcway';
 
 export default {
   name: 'generate-invoice',
-  schema: z.object({ userId: z.number(), month: z.string() }),
+  schema: type({ userId: 'number', month: 'string' }),
   retries: 3,
-  schedule: '0 0 1 * *', // First of each month
-  handler: async (ctx, payload) => {
-    const { userId, month } = payload as { userId: number; month: string };
+  schedule: '0 0 1 * *',  // First of each month (cron)
+  handler: async (ctx) => {
+    const { userId, month } = ctx.payload;
     // Generate invoice...
   },
-} satisfies JobDefinition;
+};
+```
+
+Job handlers receive a context object with all infrastructure plus `payload`:
+
+```js
+// ctx contains: { db, events, cache, queue, files, mail, log, payload }
+```
+
+### Continuous Jobs
+
+Jobs with `schedule: 'continuous'` run in a loop until stopped:
+
+```js
+export default {
+  name: 'process-queue',
+  schedule: 'continuous',
+  handler: async (ctx) => {
+    // Runs repeatedly. Backoff is applied on errors.
+  },
+};
 ```
 
-Queue a job from any handler:
+### Enqueue Jobs Programmatically
+
+From any route handler or listener:
 
-```typescript
+```js
 await ctx.queue.push('generate-invoice', { userId: 42, month: '2025-01' });
 ```
 
@@ -466,9 +477,9 @@ Failed jobs retry with exponential backoff (1s, 2s, 4s, 8s...).
 
 ## Queue
 
-Domain-scoped persistent queue for background processing:
+Persistent queue for background processing:
 
-```typescript
+```js
 // Push work
 await ctx.queue.push('email-send', { to: 'user@example.com', body: '...' });
 
@@ -484,9 +495,9 @@ Drivers: `knex` (default, database-backed) or `redis`.
 
 ## Cache
 
-Domain-scoped key-value cache with TTL support:
+Key-value cache with TTL support:
 
-```typescript
+```js
 // Set with TTL
 await ctx.cache.set('user:42', userData, 60_000);
 
@@ -496,9 +507,7 @@ const cached = await ctx.cache.get('user:42');
 // Cache-aside pattern
 const user = await ctx.cache.wrap(
   'user:42',
-  async () => {
-    return ctx.db('users').where({ id: 42 }).first();
-  },
+  async () => ctx.db('users').where({ id: 42 }).first(),
   60_000,
 );
 
@@ -506,13 +515,13 @@ const user = await ctx.cache.wrap(
 await ctx.cache.delete('user:42');
 ```
 
-Drivers: `knex` (default) or `redis`.
+Drivers: `memory` (default) or `redis`.
 
 ## File Storage
 
-Domain-scoped file operations:
+File operations via `ctx.files`:
 
-```typescript
+```js
 // Write
 await ctx.files.write('avatars/user-42.png', imageBuffer);
 
@@ -531,22 +540,41 @@ await ctx.files.delete('avatars/user-42.png');
 
 Drivers: `local` (default, filesystem) or `s3`.
 
+## Mail
+
+Send email via `ctx.mail`:
+
+```js
+await ctx.mail.send({
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<h1>Hello</h1>',
+});
+
+// Or queue for background sending
+await ctx.mail.queue({
+  to: 'user@example.com',
+  subject: 'Invoice',
+  html: '<p>Your invoice is attached.</p>',
+});
+```
+
+Drivers: `smtp` or `console` (logs to stdout).
+
 ## Rate Limiting
 
-Rate limiting is available as a middleware factory with pluggable backends:
+Rate limiting is available as a middleware factory:
 
-```typescript
-// domains/api-gateway/api/_middleware.ts
+```js
+// api/_middleware.js
 import { createRateLimitMiddleware, MemoryRateLimitStore } from 'arcway';
 
 const store = new MemoryRateLimitStore();
 
 export default createRateLimitMiddleware(
   {
-    max: 100, // 100 requests
-    windowMs: 60_000, // per minute
-    // keyFn: (ctx) => ctx.headers['x-api-key'] ?? 'anonymous',
-    // message: 'Rate limit exceeded',
+    max: 100,          // 100 requests
+    windowMs: 60_000,  // per minute
   },
   store,
 );
@@ -561,86 +589,115 @@ Response headers are added automatically:
 - `X-RateLimit-Reset` — Unix timestamp when window resets
 - `Retry-After` — seconds until retry (on 429 responses only)
 
-Implement `RateLimitStore` for custom backends (Redis, etc.):
-
-```typescript
-interface RateLimitStore {
-  check(key: string, max: number, windowMs: number): Promise<RateLimitResult>;
-  destroy(): void;
-}
-```
+Stores: `MemoryRateLimitStore` (built-in) or `RedisRateLimitStore`.
 
-## Database Access Control
+## Sessions
 
-Domains can only write to tables listed in their `config.ts`. Attempting to write to another domain's table throws `DomainAccessViolation`:
+Configure sessions in `arcway.config.js`:
 
-```typescript
-// In users domain (tables: ['users', 'sessions'])
-await ctx.db('users').insert({ name: 'Alice' }); // OK
-await ctx.db('billing').insert({ amount: 100 }); // Throws DomainAccessViolation
+```js
+export default {
+  session: {
+    password: 'at-least-32-characters-long-secret!',
+    cookieName: 'arcway.session',
+    ttl: 86400,
+  },
+};
 ```
 
-Read access is unrestricted. Cross-domain writes go through services.
-
-## Domain Boundary Linting
-
-`arcway lint` statically checks for illegal imports between domains:
-
-```bash
-$ arcway lint
-Checking domain boundaries...
-  Domains: users, billing, projects
-  Files scanned: 24
+Set session data from a route handler by returning `session`:
 
-1 violation(s) found:
-
-  domains/billing/services/index.ts:3
-    Domain 'billing' imports directly from domain 'users'
-    Import: ../../users/services/index.ts
+```js
+export const POST = {
+  handler: async (ctx) => {
+    const user = await authenticate(ctx.req.body);
+    return {
+      data: user,
+      session: { userId: user.id, role: user.role },
+    };
+  },
+};
 ```
 
-Domains must communicate through `ctx.services`, `ctx.events`, or `ctx.queue` — never by importing each other's files directly.
+Read session in subsequent requests via `ctx.req.session`. Clear by returning `session: null`.
 
 ## Testing
 
-Arcway provides test utilities that create isolated domain contexts with in-memory SQLite:
+Arcway provides `Arcway.test()` for integration testing with an in-memory SQLite database:
 
-```typescript
+```js
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { createTestContext, type TestContext } from 'arcway';
+import { Arcway } from 'arcway';
 
-describe('users service', () => {
-  let t: TestContext;
+describe('users API', () => {
+  let app;
 
   beforeAll(async () => {
-    t = await createTestContext({
-      domain: 'users',
-      tables: ['users'],
-      migrationsDir: 'db/migrations',
-    });
+    app = await Arcway.test({ rootDir: './my-app' });
   });
 
-  afterAll(() => t.cleanup());
+  afterAll(() => app.shutdown());
 
   it('creates a user', async () => {
-    const [id] = await t.ctx.db('users').insert({ name: 'Alice' });
-    const user = await t.ctx.db('users').where({ id }).first();
-    expect(user.name).toBe('Alice');
+    const res = await app.request('POST', '/users', {
+      body: { name: 'Alice', email: 'alice@test.com' },
+    });
+    expect(res.status).toBe(201);
+    expect(res.body.data.name).toBe('Alice');
+  });
+
+  it('lists users', async () => {
+    const res = await app.request('GET', '/users');
+    expect(res.status).toBe(200);
+    expect(res.body.data).toHaveLength(1);
   });
 });
 ```
 
-The test context stubs all infrastructure (events, queue, cache, files) so tests run fast and in isolation.
+`Arcway.test()` boots the full application with SQLite in-memory, random port, and MCP disabled. It returns:
 
-## Seeds
+- `app.request(method, path, opts)` — make HTTP requests
+- `app.db` — direct database access for setup/assertions
+- `app.run(fn)` — execute a function with infrastructure context
+- `app.shutdown()` — clean up
+
+### Unit Test Stubs
 
-Seed files live in `db/seeds/` and run in alphabetical order:
+For unit testing without booting the full app:
 
-```typescript
-// db/seeds/001_users.ts
-import type { Knex } from 'knex';
+```js
+import { createTestContext } from 'arcway';
 
-export default async function seed(db: Knex): Promise<void> {
+const { ctx, db, cleanup } = await createTestContext('mytest', {
+  migrationsDir: './migrations',
+});
+
+// ctx has: { db, events, queue, cache, files, mail, log }
+// All infrastructure is stubbed in-memory
+
+await cleanup();
+```
+
+Individual stubs are also available:
+
+```js
+import {
+  createEventStub,
+  createQueueStub,
+  createCacheStub,
+  createFilesStub,
+  createMailStub,
+  createLoggerStub,
+} from 'arcway';
+```
+
+## Seeds
+
+Seed files live in `seeds/` and run in alphabetical order:
+
+```js
+// seeds/001_users.js
+export default async function seed(db) {
   await db('users')
     .insert([
       { id: 1, name: 'Alice', email: 'alice@test.com' },
@@ -663,49 +720,51 @@ arcway docs openapi.json
 
 Routes with `meta` and `schema` fields produce documented endpoints:
 
-```typescript
-export const GET: RouteMethodConfig = {
+```js
+export const GET = {
   schema: {
-    params: z.object({ id: z.string() }),
-    query: z.object({ fields: z.string().optional() }),
+    query: type({ id: /^\d+$/ }),
   },
   meta: {
     summary: 'Get user by ID',
     description: 'Returns a single user record.',
     tags: ['users'],
   },
-  handler: async (ctx) => {
-    /* ... */
-  },
+  handler: async (ctx) => { /* ... */ },
 };
 ```
 
-## Production Build
+## Pages (SSR)
 
-```bash
-arcway build           # Compile to dist/
-cd dist && arcway start
+Arcway supports server-side rendered React pages with file-based routing:
+
+```
+pages/
+├── _layout.jsx        # Root layout (wraps all pages)
+├── index.jsx          # / route
+├── about.jsx          # /about route
+├── blog/
+│   ├── _layout.jsx    # Blog layout (wraps blog pages)
+│   ├── index.jsx      # /blog route
+│   └── [slug].jsx     # /blog/:slug route
+└── _404.jsx           # Custom 404 page
 ```
 
-The build step compiles TypeScript with esbuild, copies non-TS files (migrations, JSON), and preserves the directory structure. The production server uses native `import()` — no tsx required at runtime.
+Pages are React components with automatic hydration, layout nesting, and client-side navigation.
 
 ## Boot Sequence
 
 When `arcway dev` or `arcway start` runs, the framework:
 
-1. Loads `arcway.config.ts`
-2. Discovers all domains in `domains/`
+1. Loads environment files (`.env`, `.env.local`, `.env.{mode}`)
+2. Loads `arcway.config.js`
 3. Connects to the database and runs migrations
-4. Initializes queue, cache, and file drivers
-5. Creates scoped domain contexts
-6. Discovers services and wires cross-domain proxies
-7. Creates event bus and registers listeners
-8. Discovers and registers jobs
-9. Runs `onInit` hooks
-10. Discovers routes and middleware
-11. Resolves CORS configuration
-12. Creates and starts HTTP server
-13. Runs `onReady` hooks
-14. Starts job runner (cron scheduler)
-
-Graceful shutdown reverses the process: stops the job runner, runs `onShutdown` hooks, drains connections, and closes the server.
+4. Initializes Redis, queue, cache, file, and mail drivers
+5. Creates event bus and registers listeners
+6. Discovers and registers jobs
+7. Discovers routes and middleware
+8. Builds pages (if `pages/` exists)
+9. Creates and starts HTTP server
+10. Starts job runner (cron scheduler + continuous jobs)
+
+Graceful shutdown reverses the process: stops the job runner, drains connections, and closes the server.

package/client/ws.js

@@ -1,5 +1,3 @@
-import { io } from 'socket.io-client';
-
 class WsManager {
   socket = null;
   socketId = null;
@@ -25,10 +23,11 @@ class WsManager {
     return !!this.socket?.connected && this.socketId !== null;
   }
 
-  connect() {
+  async connect() {
     if (this.socket) return;
 
     try {
+      const { io } = await import('socket.io-client');
       const parsed = new URL(this.url);
       this.socket = io(parsed.origin, {
         path: this.wsPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",