Internals

Boot Sequence

When arcway start (or arcway dev) runs, the framework boots in a fixed, dependency-safe order so that config, plugins, infrastructure, and routing come up consistently:

Load environment — .env → .env.local → .env.{mode} → .env.{mode}.local.
Build the config (makeConfig) — load arcway.config.js and run the config resolvers, including secrets (derive the infrastructure secrets from ARCWAY_MASTER_SECRET) and plugins (resolve plugins.enabled/dirs/enablements).
Create the plugin manager — discover plugins, validate manifests, and build the capability graph (topological ordering, provides/requires resolution). Plugin lifecycle hooks are deferred until infrastructure exists.
Merge plugin migrations — plugin-owned migrations are added to the application migration set.
Create infrastructure — connect the database and run migrations (app + plugin), connect Redis (if configured), and initialize the drivers (queue, cache, files, mail) and the event bus.
Collect runtime metadata (ctx.meta) and start the file watcher (dev mode).
Assemble the app context — a single mutable appContext (db, redis, events, queue, cache, files, mail, log, meta, plugins) handed to every subsystem and to the lifecycle hooks.
Run plugin lifecycle — onLoad/onEnable for each enabled plugin.
Run the init hook (hooks/init.js) — your earliest app-level setup; mutations to appContext (e.g. wrapping appContext.db) persist for the process lifetime.
Initialize routers and runners — the MCP runtime (dev), event listeners, the job runner (plus worker pool; app and plugin jobs), the API router (routes from api/ and plugin routes/, middleware, and injection of required capabilities into each request ctx), the pages router, and the WebSocket router.
Start the HTTP server (listen) and attach WebSocket.
Start the job runner (cron + continuous).
Run the ready hook (hooks/ready.js) — once the server is accepting connections.

Shutdown (SIGINT/SIGTERM) unwinds in reverse: the shutdown hook, then the job runner and worker pool, the HTTP server (with a timeout), the routers and file watcher, the event bus, Redis, and finally the database.

MCP Debug Tools

Arcway includes a built-in MCP (Model Context Protocol) server that exposes debugging, logging, and project introspection tools for AI coding agents. MCP tools are development-mode only and never run in production.

Configuration

// arcway.config.js
export default {
  mcp: {
    enabled: true, // Default: true. Set false to disable.
    secret: 'my-debug-token', // Optional. Require token for debug API access.
    logBufferSize: 2000, // Max log entries in memory ring buffer.
  },
};

When secret is set, all /_mcp/* requests must include the token via Authorization: Bearer <token> header or ?token=<token> query parameter. Requests without valid tokens receive a 401 response.

Starting the MCP Server

# Start the MCP stdio server (for AI agent integration)
arcway mcp

The MCP server communicates over stdio using the Model Context Protocol. AI coding agents (Claude Code, Cursor, etc.) connect to it automatically when configured.

Architecture

Arcway uses a two-process architecture for MCP:

Dev server (arcway dev) — Runs the app with MCP runtime instrumentation enabled. Exposes an internal debug HTTP API at /_mcp/*. Writes .build/dev.json with port/pid info.
MCP server (arcway mcp) — A separate stdio process that reads .build/dev.json to discover the running dev server. Introspection tools work standalone (filesystem only). Runtime tools query the debug HTTP API.

Available Tools

Introspection Tools (no running server needed)

Tool	Description
`arcway_project_overview`	Full project topology: routes, events, jobs, config.
`arcway_db_schema`	Introspect the database schema: tables, columns, types, indexes.

Runtime Debugging Tools (require `arcway dev` running)

Tool	Description
`arcway_logs`	Query recent log entries. Filter by level, time range, and limit.
`arcway_errors`	Get recent error log entries only.
`arcway_request_trace`	Query HTTP request traces: method, path, status, duration, middleware.
`arcway_event_trace`	Query event emission traces: event name, listener results, timing.
`arcway_job_status`	Get job queue size and runner status.
`arcway_queue_inspect`	Inspect queue info.
`arcway_health`	Server health: uptime, port, mode, route count, buffer sizes.

Debug HTTP API

When arcway dev runs with MCP enabled, internal debug endpoints are mounted at /_mcp/*:

Endpoint	Query Parameters
`GET /_mcp/logs`	`level`, `since`, `limit`
`GET /_mcp/errors`	`limit`, `since`
`GET /_mcp/traces`	`method`, `path`, `status`, `minDurationMs`, `since`, `limit`
`GET /_mcp/traces/get`	`id` (required)
`GET /_mcp/events`	`eventName`, `since`, `limit`
`GET /_mcp/jobs`	(none)
`GET /_mcp/queue`	(none)
`GET /_mcp/health`	(none)

These endpoints are for internal use by the MCP server. They are not mounted in production.

Runtime Instrumentation

When MCP is enabled in dev mode, Arcway instruments the boot process:

Log buffer — All log entries (info, warn, error) are captured in a ring buffer. Default capacity: 2000 entries.
Trace collector — HTTP request lifecycle traces capture middleware execution, route matching, events emitted, timing, and errors.
Event trace collector — Event emission traces capture listener results, timing, and errors.

Server Discovery

The dev server writes .build/dev.json on startup:

{
  "port": 3000,
  "pid": 12345,
  "bootedAt": "2026-01-01T00:00:00.000Z"
}

The MCP server reads this file to locate the running dev server. The file is cleaned up on shutdown. Add .build/ to your .gitignore.

Dev Mode Hot-Reload

When running arcway dev, the framework watches for file changes and automatically reloads:

Pages (pages/ directory):

Watched for .jsx and .css changes
Rebuilt incrementally without server restart
Browser is notified via SSE live-reload

API Routes (api/ directory):

Watched for .js changes
Routes and middleware are re-discovered and hot-swapped in-place
No server restart needed -- the request handler immediately uses updated routes
New files, modified files, and deleted files are all detected

On this page