Synapse

AI-Native TypeScript Framework for Autonomous Agents

Synapse treats AI agents as first-class citizens. It maximizes "Locality of Behavior" and provides structured, compiler-driven feedback loops for self-healing code generation.

Features

• Contract-First Development - Every route requires Zod schemas for input/output
• Single-File Architecture - Route, Schema, Handler, and Tests in one file
• Auto-Generated Manifest - synapse.manifest.json with full JSON schemas
• Auto-Generated SDK - Type-safe client.ts for API consumption
• AI Diagnostics - Structured error prompts with fix_instruction
• Guard System - Explicit, visible security requirements
• Middleware Pipeline - Composable request/response processing
• WebSocket Support - Real-time communication with same guard system
• OpenAPI/Swagger - Auto-generated API documentation
• Plugin Architecture - Extensible plugin system
• Testing Utilities - Built-in test client and assertions

Quick Start

# Install dependencies
bun install

# Start development server
bun run dev

# Create a new feature
bun run create products

# Seed database
bun run seed

# List all routes
bun run routes

# Check project health
bun run doctor

Define a Route

import { z } from "zod";
import { Synapse } from "./synapse";

const app = new Synapse({ port: 3000 });

// Using convenience methods
app.post("/users", {
    description: "Create a new user",
    input: z.object({
        name: z.string().min(1),
        email: z.string().email(),
    }),
    output: z.object({
        id: z.string(),
        name: z.string(),
        email: z.string(),
    }),
    handler: async ({ input }) => ({
        id: crypto.randomUUID(),
        name: input.name,
        email: input.email,
    }),
});

app.serve();

Middleware

import { cors, requestId, loggerMiddleware } from "./middleware";

const app = new Synapse({ port: 3000 });

// Add middleware
app.use(requestId());
app.use(loggerMiddleware());
app.use(cors({ origin: "*" }));

// Custom middleware
app.use(async (ctx, next) => {
    console.log(`[${ctx.method}] ${ctx.path}`);
    return next();
});

WebSocket

import { z } from "zod";
import { AuthGuard } from "./guards";

app.ws.route({
    path: "/chat/:room",
    guards: [AuthGuard],
    messageSchema: z.object({ text: z.string() }),
    onOpen: (ctx) => {
        ctx.socket.subscribe(ctx.data.path);
    },
    onMessage: (ctx, message) => {
        ctx.socket.publish(ctx.data.path, JSON.stringify(message));
    },
});

Plugins

import { healthCheckPlugin, definePlugin } from "./plugin";

// Use built-in plugin
await app.register(healthCheckPlugin);

// Define custom plugin
const myPlugin = definePlugin("my-plugin", "1.0.0")
    .description("My custom plugin")
    .routes(myRoutes)
    .middleware(myMiddleware)
    .build();

await app.register(myPlugin);

API Documentation

After starting the server, access:

• Swagger UI: http://localhost:3000/synapse/docs
• OpenAPI JSON: http://localhost:3000/synapse/openapi.json
• Manifest: http://localhost:3000/synapse/manifest

Project Structure

synapse.ts       # Core framework
index.ts         # Entry point
env.ts           # Environment validation
synapse.db.ts    # Drizzle ORM setup
schema.ts        # Database tables
guards.ts        # Auth guards
middleware.ts    # Request/response middleware
websocket.ts     # WebSocket support
openapi.ts       # OpenAPI generation
plugin.ts        # Plugin system
testing.ts       # Test utilities
logger.ts        # Structured logging
response.ts      # Response helpers
diagnostics.ts   # Error-to-prompt engine
cli.ts           # CLI tools
features/        # Single-file features
docs/            # Documentation

CLI Commands

| Command | Description | |---------|-------------| | bun run dev | Start dev server with hot reload | | bun run start | Start production server | | bun run create <name> | Scaffold a new feature | | bun run seed | Run database seeders | | bun run routes | List all registered routes | | bun run doctor | Check project health | | bun run test | Run tests |

Documentation

See docs/llm-handbook.md for token-efficient AI reference.

License

MIT