> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

> Technical architecture overview of the Panguard AI platform: monorepo structure, deployment layers, and component interactions.

# System Architecture

Panguard AI is a TypeScript monorepo with 18 packages organized into three deployment layers. Every component -- from the CLI on your laptop to the Threat Cloud in the data center -- shares the same `@panguard-ai/core` foundation.

***

## Three Deployment Layers

```
  +-------------------------------------------------------+
  |                    Cloud Layer                         |
  |   Threat Cloud (collective intelligence)              |
  |   Cloud AI (Claude / OpenAI)                          |
  |   Web Dashboard                                       |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                   Manager Layer                        |
  |   Fleet orchestration, policy management              |
  |   Agent registration, centralized logging             |
  +-------------------------------------------------------+
                          ^
                          | HTTPS / WebSocket
                          v
  +-------------------------------------------------------+
  |                  Endpoint Layer                        |
  |   Guard agent (real-time protection)                  |
  |   Scan, Chat, Trap, Report (CLI tools)                |
  +-------------------------------------------------------+
```

<Tabs>
  <Tab title="Endpoint Layer">
    The Guard agent and CLI tools run directly on the protected machine. This is where security events are detected, analyzed by Layer 1 and Layer 2 AI, and responded to in real time.

    **Key components:**

    * Guard agent (continuous monitoring)
    * Scan engine (on-demand audits)
    * Chat notifications (Telegram, Slack, Email, LINE, Webhook)
    * Trap honeypots (8 decoy service types)
    * Report generator (PDF, JSON)
    * Local AI via Ollama (Layer 2)

    **Operates fully offline.** The endpoint layer functions without network connectivity using cached rules and local AI.
  </Tab>

  <Tab title="Manager Layer">
    The Manager orchestrates multiple Guard agents across a fleet of machines. It provides centralized policy management, agent registration, and aggregated logging.

    **Key capabilities:**

    * Fleet-wide policy deployment
    * Agent health monitoring and registration
    * Centralized log aggregation
    * WebSocket real-time dashboard
    * REST API for programmatic control

    **Deployment:** Self-hosted on your infrastructure or managed by Panguard.
  </Tab>

  <Tab title="Cloud Layer">
    The Cloud layer provides collective intelligence and deep AI analysis for threats that cannot be resolved locally.

    **Key services:**

    * Threat Cloud (community-driven IoC database)
    * Cloud AI analysis (Claude / OpenAI for Layer 3)
    * Local web dashboard for threat monitoring

    **Optional.** The cloud layer enhances protection but is never required. All core functionality works without it.
  </Tab>
</Tabs>

***

## 13-Package Monorepo

The codebase is organized as a pnpm workspace monorepo. Each package has a single responsibility:

| Package                        | Layer    | Purpose                                               |
| ------------------------------ | -------- | ----------------------------------------------------- |
| `@panguard-ai/core`            | Shared   | Rule engine, monitors, AI providers, i18n, encryption |
| `@panguard-ai/panguard`        | Endpoint | CLI entry point (`panguard` command)                  |
| `@panguard-ai/panguard-guard`  | Endpoint | Real-time protection agent (5-stage AI pipeline)      |
| `@panguard-ai/panguard-scan`   | Endpoint | Security scanner and risk scoring                     |
| `@panguard-ai/panguard-chat`   | Endpoint | Notification system (5 channels, 3 role formats)      |
| `@panguard-ai/panguard-trap`   | Endpoint | Honeypot system (8 service types)                     |
| `@panguard-ai/panguard-report` | Endpoint | Compliance report generation (TCSA, ISO 27001, SOC 2) |
| `@panguard-ai/threat-cloud`    | Cloud    | Collective intelligence API server                    |
| `@panguard-ai/website`         | Cloud    | Marketing website (panguard.ai)                       |

***

## @panguard-ai/core -- Shared Foundation

The `core` package is the foundation that every other package depends on. It provides:

<AccordionGroup>
  <Accordion title="Rule Engine">
    * ATR rule parser and evaluator (pattern matching, context-aware detection, multi-layer analysis)
    * 768 bundled ATR rules, custom rule loading
  </Accordion>

  <Accordion title="Monitors">
    4 system monitors that collect security-relevant events: - **Log Monitor** -- System log parsing
    (syslog, journald, Windows Event Log) - **Network Monitor** -- Connection tracking, port scanning,
    DNS queries - **Process Monitor** -- Process creation, termination, resource usage - **File
    Monitor** -- File system changes, permission modifications, new executables
  </Accordion>

  <Accordion title="AI Providers">
    * FunnelRouter for Layer 2/3 cascading - Ollama adapter (local AI) - Claude and OpenAI adapters
      (cloud AI) - Provider auto-detection at startup - AES-256-GCM encrypted key storage
      (`~/.panguard/llm.enc`)
  </Accordion>

  <Accordion title="Internationalization (i18n)">
    * English and Traditional Chinese - All CLI output, reports, and notifications are fully localized
    * Language selection via `panguard init` or `--lang` flag
  </Accordion>

  <Accordion title="System Reconnaissance">
    * OS detection (macOS, Linux, Windows)
    * Network interface enumeration
    * Running service inventory
    * Security tool detection (antivirus, EDR, IDS)
    * Hardware identifier collection for encryption key derivation
  </Accordion>
</AccordionGroup>

***

## Tech Stack

| Technology         | Version | Purpose                                            |
| ------------------ | ------- | -------------------------------------------------- |
| **TypeScript**     | 5.7     | Primary language across all packages               |
| **Node.js**        | 22      | Runtime                                            |
| **pnpm**           | 9+      | Workspace-aware package manager                    |
| **Vitest**         | Latest  | Unit and integration testing                       |
| **esbuild**        | Latest  | Fast bundling for CLI distribution                 |
| **better-sqlite3** | Latest  | Embedded database for Threat Cloud and Guard state |
| **Next.js**        | 14      | Web dashboard and marketing website                |

***

## Cross-Platform Support

Panguard runs on all three major operating systems:

| Platform               | Guard | Scan | Trap | Manager |
| ---------------------- | ----- | ---- | ---- | ------- |
| **macOS** (ARM64, x64) | Yes   | Yes  | Yes  | Yes     |
| **Linux** (x64, ARM64) | Yes   | Yes  | Yes  | Yes     |
| **Windows** (x64)      | Yes   | Yes  | Yes  | Yes     |

Platform-specific implementations are abstracted behind interfaces in `core`:

* **Firewall:** macOS `pfctl`, Linux `iptables`/`nftables`, Windows `netsh`
* **Service management:** macOS `launchd`, Linux `systemd`, Windows Services
* **Log sources:** macOS unified log, Linux `journald`/syslog, Windows Event Log

***

## Data Flow

A typical security event flows through the system as follows:

<Steps>
  <Step title="Event detected">
    A monitor in `core` (process, network, file, or log) detects a security-relevant event on the
    endpoint.
  </Step>

  <Step title="Layer 1 evaluation">
    The ATR rule engine evaluates the event in under 1ms. If a rule matches, the event is classified
    and a response is triggered immediately.
  </Step>

  <Step title="AI escalation (if needed)">
    Unmatched events are forwarded to Layer 2 (local Ollama) or Layer 3 (Cloud AI) for deeper
    analysis via the FunnelRouter.
  </Step>

  <Step title="Response execution">
    Based on classification and confidence, the auto-response engine takes action: block IP,
    quarantine file, terminate process, or notify only.
  </Step>

  <Step title="Reporting and notification">
    Chat sends a notification via the configured channel. The event is logged for Guard status,
    security score updates, and compliance reports.
  </Step>

  <Step title="Threat Cloud upload (optional)">
    If Threat Cloud participation is enabled, anonymized indicators are uploaded to benefit the
    community.
  </Step>
</Steps>

***

## Related

<CardGroup cols={3}>
  <Card title="Three-Layer AI" icon="brain-circuit" href="/concepts/three-layer-ai">
    Deep dive into the Rules, Local AI, and Cloud AI funnel.
  </Card>

  <Card title="Guard Pipeline" icon="shield" href="/products/guard/agent-pipeline">
    The 5-stage AI agent pipeline inside Guard.
  </Card>

  <Card title="Manager" icon="server" href="/products/guard/overview">
    Fleet orchestration and centralized management.
  </Card>
</CardGroup>