# System Architecture

## Overview Diagram

```
┌─────────────────────────────────────────────────────────────────────┐
│                          XMPP Clients                                │
│  (Gajim, Pidgin, Conversations, Web Clients, Bots, etc.)           │
└────┬─────────────┬──────────────┬──────────────┬────────────────────┘
     │             │              │              │
     │ TCP/TLS     │ HTTP         │ WebSocket    │ Components
     │ :5222       │ :5280        │ :5281        │ :5347
     │             │              │              │
┌────▼─────────────▼──────────────▼──────────────▼────────────────────┐
│                      Network Layer                                   │
├────────────────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌───────────┐  ┌────────────┐  ┌─────────────────┐│
│  │ C2S      │  │ BOSH      │  │ WebSocket  │  │ Component       ││
│  │ Server   │  │ Server    │  │ Server     │  │ Server          ││
│  └────┬─────┘  └─────┬─────┘  └──────┬─────┘  └────────┬────────┘│
└───────┼──────────────┼────────────────┼─────────────────┼─────────┘
        │              │                │                 │
        └──────────────┴────────────────┴─────────────────┘
                              │
┌─────────────────────────────▼─────────────────────────────────────┐
│                      XMPP Stream Handler                           │
│  • Stream Negotiation  • SASL Auth  • Resource Binding            │
└─────────────────────────────┬─────────────────────────────────────┘
                              │
┌─────────────────────────────▼─────────────────────────────────────┐
│                     Session Manager                                │
│  • Session Creation    • JID Mapping    • Authentication          │
│  • Priority Handling   • Presence       • Cleanup                 │
└─────────────────────────────┬─────────────────────────────────────┘
                              │
┌─────────────────────────────▼─────────────────────────────────────┐
│                      Stanza Router                                 │
│  • Message Routing    • Presence Broadcasting    • IQ Handling    │
│  • Filtering          • Event Hooks              • Error Handling │
└──────┬──────────────────────┬──────────────────────┬──────────────┘
       │                      │                      │
       │                      │                      │
┌──────▼──────┐    ┌─────────▼────────┐   ┌────────▼──────────┐
│   Module    │    │   Host          │   │   Storage        │
│   Manager   │    │   Manager       │   │   Manager        │
│             │    │                 │   │                  │
│ • Dynamic   │    │ • Virtual Hosts │   │ • Backends       │
│   Loading   │    │ • Multi-domain  │   │ • Per-host       │
│ • Hooks     │    │ • Config        │   │ • Abstraction    │
└──────┬──────┘    └─────────┬────────┘   └────────┬─────────┘
       │                     │                      │
       └─────────────────────┴──────────────────────┘
                             │
            ┌────────────────┴────────────────┐
            │                                 │
┌───────────▼──────────┐          ┌──────────▼──────────┐
│   Modules (Plugins)  │          │   Storage Backends  │
├──────────────────────┤          ├─────────────────────┤
│ • mod_roster         │          │ • Memory            │
│ • mod_disco          │          │ • File              │
│ • mod_presence       │          │ • PostgreSQL        │
│ • mod_message        │          │ • MongoDB           │
│ • mod_mam            │          │ • Redis Cache       │
│ • mod_muc            │          └─────────────────────┘
│ • mod_pubsub         │
│ • ... (extensible)   │
└──────────────────────┘
```

## Component Interaction Flow

### Client Connection Flow

```
Client                 C2S Server            XMPP Stream         Session Mgr
  │                        │                      │                   │
  │─── TCP Connect ────────>                      │                   │
  │                        │                      │                   │
  │                        │─── Create Stream ───>│                   │
  │                        │                      │                   │
  │<──── Stream Start ─────│<────────────────────│                   │
  │                        │                      │                   │
  │─── SASL Auth ─────────>│─────────────────────>│                   │
  │                        │                      │                   │
  │<──── Auth Success ─────│<────────────────────│                   │
  │                        │                      │                   │
  │─── Bind Resource ─────>│─────────────────────>│─── Create ──────>│
  │                        │                      │   Session         │
  │                        │                      │                   │
  │<──── Bound JID ────────│<────────────────────│<─── Authenticate ─│
  │                        │                      │                   │
  │─── Send Presence ─────>│                      │                   │
  │                        │                      │                   │
  ●                        ●                      ●                   ●
  Connected and Ready
```

### Message Routing Flow

```
Sender                Stanza Router        Session Mgr         Recipient
  │                        │                     │                 │
  │─── Send Message ──────>│                     │                 │
  │                        │                     │                 │
  │                        │─── Get Session ────>│                 │
  │                        │    by JID           │                 │
  │                        │<──── Session ───────│                 │
  │                        │                     │                 │
  │                        │───────── Route Message ──────────────>│
  │                        │                     │                 │
  │                        │<────── Delivered ───────────────────│
  │                        │                     │                 │
  │<──── Receipt (opt) ────│                     │                 │
```

### Module Hook Flow

```
Event                 Stanza Router       Module Manager      Module
  │                        │                     │               │
  │─── Stanza Arrives ────>│                     │               │
  │                        │                     │               │
  │                        │─── Emit Event ─────>│               │
  │                        │    (e.g., message)  │               │
  │                        │                     │               │
  │                        │                     │─── Hook ─────>│
  │                        │                     │   Called      │
  │                        │                     │               │
  │                        │                     │<── Process ───│
  │                        │                     │   Stanza      │
  │                        │                     │               │
  │                        │<─── Continue ───────│               │
  │                        │    or Block         │               │
```

## Data Flow Layers

```
┌──────────────────────────────────────────────────────────┐
│                  Application Layer                        │
│  (User Logic, Business Rules, Module Code)               │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                  XMPP Protocol Layer                      │
│  (Stanza Processing, Routing, Presence, Roster)          │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                  Session Layer                            │
│  (Authentication, Session Management, JID Mapping)       │
└────────────────────────┬─────────────────────────────────┘
                         │
┌────────────────────────▼─────────────────────────────────┐
│                  Transport Layer                          │
│  (TCP, TLS, HTTP, WebSocket)                             │
└──────────────────────────────────────────────────────────┘
```

## Storage Architecture

```
┌─────────────────────────────────────────────────────────┐
│                   Application Code                       │
└────────────────────────┬────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────┐
│               Storage Manager (Abstraction)             │
│  • getStore(host, name)                                 │
│  • Per-host isolation                                   │
└────────────────────────┬────────────────────────────────┘
                         │
            ┌────────────┴────────────┐
            │                         │
┌───────────▼──────────┐   ┌─────────▼─────────┐
│   Store Interface    │   │  Store Interface  │
│   (localhost:roster) │   │ (example.com:mam) │
└───────────┬──────────┘   └─────────┬─────────┘
            │                        │
┌───────────▼────────────────────────▼─────────┐
│          Storage Backend                     │
│  ┌─────────┐  ┌──────────┐  ┌────────────┐ │
│  │ Memory  │  │   File   │  │  Database  │ │
│  └─────────┘  └──────────┘  └────────────┘ │
└──────────────────────────────────────────────┘
```

## Security Layers

```
┌─────────────────────────────────────────────┐
│           Connection Security                │
│  • TLS/SSL Encryption                       │
│  • Certificate Validation                   │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│         Authentication Security              │
│  • SASL Mechanisms                          │
│  • Credential Validation                    │
│  • Session Tokens                           │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│          Application Security                │
│  • Rate Limiting                            │
│  • Connection Limits                        │
│  • Input Validation                         │
│  • ACL/Permissions                          │
└─────────────────────────────────────────────┘
```

## Event-Driven Architecture

```
                    ┌─────────────┐
                    │   Events    │
                    └──────┬──────┘
                           │
      ┌────────────────────┼────────────────────┐
      │                    │                    │
┌─────▼──────┐   ┌────────▼────────┐   ┌──────▼──────┐
│  Session   │   │     Stanza      │   │   Module    │
│  Events    │   │     Events      │   │   Events    │
│            │   │                 │   │             │
│ • created  │   │ • message       │   │ • loaded    │
│ • auth     │   │ • presence      │   │ • unloaded  │
│ • closed   │   │ • iq            │   │ • error     │
└────────────┘   └─────────────────┘   └─────────────┘
      │                    │                    │
      └────────────────────┼────────────────────┘
                           │
                    ┌──────▼──────┐
                    │  Listeners  │
                    │  (Modules)  │
                    └─────────────┘
```

## Deployment Architecture

### Single Instance

```
┌────────────────────────────────────┐
│         Load Balancer / Proxy       │
│         (Nginx, HAProxy)            │
└────────────┬───────────────────────┘
             │
┌────────────▼───────────────────────┐
│      Prosody Node.js Instance       │
│  ┌──────────────────────────────┐  │
│  │   Network Servers            │  │
│  │   (C2S, BOSH, WebSocket)     │  │
│  └──────────────────────────────┘  │
│  ┌──────────────────────────────┐  │
│  │   Core Components            │  │
│  └──────────────────────────────┘  │
└────────────┬───────────────────────┘
             │
┌────────────▼───────────────────────┐
│         Database                    │
│  (PostgreSQL, MongoDB)              │
└─────────────────────────────────────┘
```

### Clustered (Future)

```
┌────────────────────────────────────┐
│      Load Balancer (HAProxy)        │
└──────┬──────────┬──────────┬───────┘
       │          │          │
┌──────▼─────┐ ┌──▼──────┐ ┌▼────────┐
│ Instance 1 │ │Instance 2│ │Instance3│
└──────┬─────┘ └──┬──────┘ └┬────────┘
       │          │          │
       └──────────┼──────────┘
                  │
       ┌──────────▼──────────┐
       │   Shared Database   │
       │   Redis Cache       │
       └─────────────────────┘
```