# The Short Version — One Mental Model to Keep

> A plain-English recap of InsForge: the core idea in one sentence, the single analogy worth keeping (InsForge is a universal power strip that plugs an AI coding agent into every backend service at once), the three things that move (requests from agent, config changes to primitives, state events back via realtime), and pointers to where to look next.

- Repository: InsForge/InsForge
- GitHub: https://github.com/InsForge/InsForge
- Human wiki: https://grok-wiki.com/public/wiki/insforge-insforge-357039661319
- Complete Markdown: https://grok-wiki.com/public/wiki/insforge-insforge-357039661319/llms-full.txt

## Source Files

- `README.md`
- `docs/introduction.mdx`
- `docs/quickstart.mdx`
- `CHANGELOG.md`

---

<details>
<summary>Relevant source files</summary>
The following files were used as context for generating this wiki page:

- [README.md](README.md)
- [docs/introduction.mdx](docs/introduction.mdx)
- [docs/quickstart.mdx](docs/quickstart.mdx)
- [docs/mcp-setup.mdx](docs/mcp-setup.mdx)
- [docs/core-concepts/realtime/architecture.mdx](docs/core-concepts/realtime/architecture.mdx)
- [docs/core-concepts/database/architecture.mdx](docs/core-concepts/database/architecture.mdx)
- [docs/core-concepts/functions/architecture.mdx](docs/core-concepts/functions/architecture.mdx)
- [docs/sdks/typescript/overview.mdx](docs/sdks/typescript/overview.mdx)
- [CHANGELOG.md](CHANGELOG.md)
</details>

# The Short Version — One Mental Model to Keep

This page distills InsForge down to its single core idea. If you read no other page in this wiki, read this one. Everything else — database migrations, edge functions, realtime channels, the MCP server — is just a consequence of this idea working in practice.

Whether you are evaluating InsForge for a new project or trying to explain it to a teammate in one sentence, the mental model here is the one that sticks.

---

## The One Sentence

> **InsForge is the all-in-one, open-source backend platform for agentic coding.** It gives your AI coding agent a single connection point for database, auth, storage, compute, hosting, and AI — so the agent can build and operate full-stack apps end-to-end.

Sources: [README.md:42]()

---

## The Analogy Worth Keeping

Think of a **universal power strip** that sits between your AI coding agent and every backend service your app needs. Without the power strip, the agent has to find, wire up, and manage each appliance individually — database credentials here, storage keys there, auth config somewhere else. With the power strip, the agent plugs in once and every socket is immediately live.

InsForge is that power strip. The agent connects to InsForge via one protocol (MCP or CLI), and from that moment it can reach PostgreSQL, JWT auth, S3-compatible storage, serverless edge functions, a model gateway, compute containers, and site deployment — all through consistent, predictable tool calls.

The analogy maps directly to the code:

```text
AI Coding Agent
      │
      │  (MCP tools / CLI skills)
      ▼
   InsForge
      │
      ├── Authentication
      ├── Database (PostgreSQL + PostgREST)
      ├── Storage (S3-compatible)
      ├── Edge Functions (Deno)
      ├── Model Gateway (OpenAI-compatible)
      ├── Compute (long-running containers)
      └── Site Deployment
```

Sources: [README.md:58-89](), [docs/introduction.mdx:23-25]()

---

## The Two Interfaces

An AI agent reaches InsForge through exactly two doors:

| Interface | Where it runs | How the agent uses it |
|-----------|---------------|----------------------|
| **MCP Server** | Self-hosted (`localhost:7130`) or cloud (`mcp.insforge.dev/mcp`) | Agent calls named MCP tools (e.g. `fetch-docs`) from any MCP-compatible assistant (Cursor, Claude Code, GitHub Copilot, Windsurf, Codex, and more) |
| **CLI + Skills** | Cloud only | Agent runs `npx @insforge/cli` commands from the terminal, after linking a project with `npx @insforge/cli link --project-id <id>` |

Both interfaces let the agent act like a backend engineer: read documentation and schema, deploy functions, run migrations, configure auth providers, inspect storage, and more — without a human in the loop.

Sources: [README.md:48-56](), [docs/mcp-setup.mdx:7-9](), [docs/quickstart.mdx:34-46]()

---

## The Three Things That Move

Everything in InsForge reduces to three flows. Once you see them, the whole system makes sense.

### 1. Requests from the agent → InsForge primitives

The agent sends tool calls (via MCP) or CLI commands. InsForge translates those into backend operations: SQL migrations, function deployments, bucket creation, auth provider configuration. The agent never touches infrastructure directly; it describes *what* to do and InsForge executes it.

```
Agent: "run this migration"
  → MCP tool call / CLI command
  → InsForge API
  → PostgreSQL ALTER TABLE
```

Sources: [README.md:53-56](), [docs/core-concepts/database/architecture.mdx:49-60]()

### 2. Config changes to primitives

When the agent deploys a function, creates a storage bucket, or registers an OAuth provider, InsForge updates its internal primitives: PostgREST auto-generates new REST endpoints for any newly created table, Deno Subhosting receives the function code and makes it live at a URL, S3-compatible storage activates the bucket. State changes are durable and immediately usable by the app.

```
Agent deploys edge function
  → InsForge pushes to Deno Subhosting
  → Live URL: {appKey}.functions.insforge.app/{slug}
```

Sources: [docs/core-concepts/functions/architecture.mdx:1-10](), [docs/core-concepts/database/architecture.mdx:50-60]()

### 3. State events back via Realtime

When data changes in PostgreSQL — an order is created, a record is updated — database triggers fire `realtime.publish()`. That function writes to `realtime.messages`, emits a `pg_notify`, and the Realtime Manager fans the event out to connected WebSocket clients via Socket.IO and to configured webhook URLs via HTTP POST.

```
INSERT into orders
  → Trigger fires realtime.publish('order:123', 'INSERT_order', {...})
  → pg_notify → Realtime Manager
  → Socket.IO → SDK clients  (low latency, ~10–50 ms)
  → HTTP POST → webhook endpoints  (external services)
```

This loop means the app's UI and external integrations stay in sync with the database automatically, without polling.

Sources: [docs/core-concepts/realtime/architecture.mdx:12-41](), [docs/core-concepts/realtime/architecture.mdx:151-171]()

---

## A Sequence View of All Three Flows Together

```mermaid
sequenceDiagram
    participant Agent as AI Coding Agent
    participant IF as InsForge (MCP / CLI)
    participant PG as PostgreSQL
    participant RT as Realtime Manager
    participant App as Client App (SDK)

    Agent->>IF: deploy migration / create function / configure auth
    IF->>PG: ALTER TABLE / INSERT config / register provider
    PG-->>IF: ack
    IF-->>Agent: success + metadata

    Note over App,PG: Later, app writes data...
    App->>IF: INSERT into orders
    IF->>PG: SQL INSERT
    PG->>RT: pg_notify (realtime.publish trigger)
    RT->>App: Socket.IO event "INSERT_order"
    RT->>App: HTTP POST webhook (if configured)
```

Sources: [docs/core-concepts/realtime/architecture.mdx:153-172](), [docs/core-concepts/database/architecture.mdx:12-60]()

---

## What Each Primitive Does (in one line)

| Primitive | What it is | What an agent can do with it |
|-----------|-----------|------------------------------|
| **Database** | PostgreSQL 15 + PostgREST auto-API | Create tables, run migrations, query records, set RLS policies |
| **Authentication** | JWT-based user management + OAuth | Configure providers, manage users, read auth state |
| **Storage** | S3-compatible file storage | Create buckets, upload/download files |
| **Edge Functions** | Deno-based serverless compute | Deploy JS/TS functions, invoke them via URL |
| **Model Gateway** | OpenAI-compatible multi-provider API | Route LLM calls across providers |
| **Compute** | Long-running container services (private preview) | Run persistent workloads |
| **Site Deployment** | Build + host static/server sites | Deploy frontends alongside the backend |
| **Realtime** | PostgreSQL-trigger → WebSocket pub/sub | Subscribe to channels, receive DB-change events |

Sources: [README.md:91-99](), [docs/introduction.mdx:39-63]()

---

## Where to Look Next

| Question | File to read |
|----------|-------------|
| How do I connect my agent to InsForge? | [`docs/mcp-setup.mdx`](docs/mcp-setup.mdx) (remote MCP) or [`docs/quickstart.mdx`](docs/quickstart.mdx) (CLI) |
| How does the database API work? | [`docs/core-concepts/database/architecture.mdx`](docs/core-concepts/database/architecture.mdx) |
| How does realtime event delivery work? | [`docs/core-concepts/realtime/architecture.mdx`](docs/core-concepts/realtime/architecture.mdx) |
| How do edge functions deploy? | [`docs/core-concepts/functions/architecture.mdx`](docs/core-concepts/functions/architecture.mdx) |
| How do I use the TypeScript client? | [`docs/sdks/typescript/overview.mdx`](docs/sdks/typescript/overview.mdx) |
| What changed recently? | [`CHANGELOG.md`](CHANGELOG.md) |

---

The mental model holds at any scale: InsForge is the single plug that connects an AI coding agent to a complete backend. The agent sends requests, config changes propagate to live primitives, and state events flow back in realtime. Everything else in the codebase is the implementation of those three arrows.

Sources: [README.md:41-43](), [docs/introduction.mdx:23-28]()