# Architecture

{{portalName}} runs as a single Node.js process acting as a gateway between external connectors and AI engines.

## Components

```
┌─────────────────────────────────────────────────┐
│              {{portalName}} Gateway                │
│                                                  │
│  ┌───────────┐  ┌────────────┐  ┌────────────┐  │
│  │ HTTP Server│  │ WebSocket  │  │   Cron     │  │
│  │ REST + UI  │  │  Server    │  │ Scheduler  │  │
│  └─────┬─────┘  └─────┬──────┘  └─────┬──────┘  │
│        │               │               │         │
│  ┌─────┴───────────────┴───────────────┴──────┐  │
│  │            Session Manager                  │  │
│  │  Routes messages, manages engine lifecycle  │  │
│  └─────────────────┬──────────────────────────┘  │
│                    │                              │
│  ┌─────────────────┴──────────────────────────┐  │
│  │              Engine Adapters                │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  ┌────────────┐  ┌────────────┐  ┌───────────┐  │
│  │ Connector  │  │   File     │  │  SQLite   │  │
│  │  System    │  │  Watcher   │  │  Registry │  │
│  └────────────┘  └────────────┘  └───────────┘  │
└─────────────────────────────────────────────────┘
```

### HTTP Server
REST API for session management, configuration, and health checks. Also serves the static web UI.

### WebSocket Server
Pushes live events (session updates, engine output, cron results) to connected clients.

### Session Manager
Central router. Receives messages from connectors, resolves the target employee and engine, creates or reuses sessions, and delivers responses back through the originating connector.

### Engine Abstraction
Uniform adapters support the canonical engines: claude, codex, antigravity, grok, pi, hermes. Each adapter owns its engine-specific session and tool integration while the gateway keeps routing uniform.

### Connector System
Modular adapters that implement a standard interface. Each connector translates between its platform's message format and {{portalName}}'s internal message format. See `connectors.md`.

### Cron Scheduler
Uses `node-cron` to run scheduled AI jobs. Watches `cron/jobs.json` for hot-reload. See `cron.md`.

### File Watcher
Uses `chokidar` to watch `~/.jinn/` for changes and trigger appropriate reloads:
- `config.yaml` changes → reload gateway configuration
- `cron/jobs.json` changes → reschedule cron jobs
- `org/` changes → rebuild employee registry

### SQLite Session Registry
Stores session metadata (id, engine, employee, connector source, timestamps) in `sessions/registry.db`.

## Data Flow

1. Connector receives an external message (e.g., Slack message)
2. Connector normalizes the message and calls session manager
3. Session manager resolves the target employee and engine
4. Session manager creates or reuses a session for the source reference
5. The selected engine adapter processes the message
6. Engine streams or returns the result
7. Session manager delivers the result back through the originating connector
8. WebSocket server broadcasts the event to any connected web UI clients