---
title: "Introduction"
description: "What is IOServer and when should you use it?"
canonical_url: "https://docs.circle-cyber.com/docs/getting-started/introduction"
---
# Introduction

**IOServer** is a TypeScript framework for building real-time backends. It wraps [Fastify](https://fastify.dev/) (HTTP) and [Socket.IO](https://socket.io/) (WebSocket) behind a structured component model that encourages clear separation of concerns.

## What it does

- Combines HTTP and WebSocket in a single server instance
- Provides five component types — Services, Controllers, Managers, Watchers, and Middlewares — each with a well-defined role
- Wires components together through a typed **AppHandle** that gives every component access to shared state (managers) and the `send` / `log` utilities
- Auto-discovers WebSocket event handlers from public methods on Services
- Maps HTTP routes to Controller methods via JSON route files
- Ships with production-ready defaults: CORS, sensible error responses, optional SPA fallback

## What it does NOT do

- It does not prescribe your storage layer — bring your own database manager
- It does not replace Socket.IO or Fastify — you get the full power of both, exposed via `appHandle.send` and `this.appHandle` in controllers

## Component model at a glance

```text
┌──────────────────────────────────────────────────────────────┐
│                         IOServer                             │
│                                                              │
│   ┌───────────┐   ┌────────────┐   ┌──────────────────────┐ │
│   │  Manager  │   │  Manager   │   │  …                   │ │
│   │ (shared)  │   │ (shared)   │   │                      │ │
│   └─────┬─────┘   └─────┬──────┘   └──────────────────────┘ │
│         │               │                                    │
│         └───────────────┴──── AppHandle ────────────────┐   │
│                                                         │   │
│   ┌──────────────────────┐   ┌──────────────────────┐   │   │
│   │       Service        │   │     Controller       │   │   │
│   │  (WebSocket events)  │   │   (HTTP routes)      │◄──┘   │
│   └──────────────────────┘   └──────────────────────┘       │
│                                                              │
│   ┌──────────────────────┐   ┌──────────────────────┐       │
│   │       Watcher        │   │     Middleware        │       │
│   │  (background tasks)  │   │  (HTTP / WS hooks)   │       │
│   └──────────────────────┘   └──────────────────────┘       │
└──────────────────────────────────────────────────────────────┘
```

<table>
<thead>
  <tr>
    <th>
      Component
    </th>
    
    <th>
      Transport
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        Service
      </strong>
    </td>
    
    <td>
      WebSocket
    </td>
    
    <td>
      Handles Socket.IO events (one method = one event)
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Controller
      </strong>
    </td>
    
    <td>
      HTTP
    </td>
    
    <td>
      Handles Fastify routes (declared in JSON files)
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Manager
      </strong>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Shared singleton available to all other components
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Watcher
      </strong>
    </td>
    
    <td>
      —
    </td>
    
    <td>
      Long-running background tasks (intervals, polling)
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Middleware
      </strong>
    </td>
    
    <td>
      Both
    </td>
    
    <td>
      Request/namespace guards, token validation, logging
    </td>
  </tr>
</tbody>
</table>

## Technology stack

<table>
<thead>
  <tr>
    <th>
      Layer
    </th>
    
    <th>
      Library
    </th>
    
    <th>
      Version
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      HTTP server
    </td>
    
    <td>
      <a href="https://fastify.dev/" rel="nofollow">
        Fastify
      </a>
    </td>
    
    <td>
      v5
    </td>
  </tr>
  
  <tr>
    <td>
      WebSocket
    </td>
    
    <td>
      <a href="https://socket.io/" rel="nofollow">
        Socket.IO
      </a>
    </td>
    
    <td>
      v4
    </td>
  </tr>
  
  <tr>
    <td>
      CORS
    </td>
    
    <td>
      @fastify/cors
    </td>
    
    <td>
      v11
    </td>
  </tr>
  
  <tr>
    <td>
      Static files
    </td>
    
    <td>
      @fastify/static
    </td>
    
    <td>
      v10
    </td>
  </tr>
  
  <tr>
    <td>
      Language
    </td>
    
    <td>
      TypeScript
    </td>
    
    <td>
      ≥ 6.0
    </td>
  </tr>
  
  <tr>
    <td>
      Runtime
    </td>
    
    <td>
      Node.js
    </td>
    
    <td>
      ≥ 22
    </td>
  </tr>
</tbody>
</table>

## Related resources

- [GitHub repository](https://github.com/x42en/IOServer)
- [npm package](https://www.npmjs.com/package/ioserver)
- [Quick-start example](../getting-started/quick-start)
- [Complete chat application guide](../guides/chat-application)


## Sitemap

See the full [sitemap](https://docs.circle-cyber.com/sitemap.md) for all pages.