> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/platform-overview/pharos-platform-architecture.md).

# Pharos Platform Architecture

Comprehensive summary of Pharos platform architecture with shorthand navigation  to all major components and capabilities.

Pharos operates on a "bottom-up" data flow where everything derives from logs. The platform consists of multiple interconnected layers that transform raw error data into actionable intelligence.

{% hint style="info" %}
**Architecture Philosophy:** Everything in Pharos starts with logs. Issues aggregate logs, alerts notify about issues, and tickets track issue resolution—creating a complete observability lifecycle.
{% endhint %}

## Platform Architecture Diagram

![Pharos Platform Architecture — log ingestion flowing up through enrichment, the issue tracker, and analytics, with notification channels and external systems on either side](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-3037494d4448107fc5c841262e480066b2e40abd%2Fpharos-platform-architecture.png?alt=media)

## Data Flow in Action

When an error occurs in Salesforce, Pharos processes it through all architectural layers, moving from ingestion to notification without manual intervention:

| Stage              | What Happens                                                                       | Time                           |
| ------------------ | ---------------------------------------------------------------------------------- | ------------------------------ |
| **Error Occurs**   | User attempts to save an Opportunity, Apex trigger fails with DML Exception        | T+0                            |
| **Ingestion**      | Pharos intercepts exception email and creates log record                           | Near-real-time                 |
| **Processing**     | Log enriched with user context, stack trace, governor limits, environment snapshot | Scheduled batch                |
| **Issue Grouping** | Fingerprint matches existing issue, occurrence count and user impact updated       | After processing completes     |
| **Alerting**       | Rule evaluates conditions, sends Slack notification to #production-errors          | Per rule/notification schedule |
| **Triage**         | Admin reviews issue, assigns priority, creates Jira ticket                         | T+5min                         |
| **Resolution**     | Developer fixes problem, Jira syncs status back to Pharos                          | T+2hr                          |

{% hint style="success" %}
**Automated Processing:** From error occurrence to Slack notification, timing ranges from near-real-time to batch, depending on the ingestion path and your configured processing/notification schedules, ensuring teams are notified without manual intervention.
{% endhint %}

The entire workflow—from error detection to resolution tracking—operates automatically, requiring human intervention only for triage and fixing the actual problem.

## Architecture Components

The Pharos platform is organized into three main architectural layers, each building upon the previous to deliver comprehensive observability and error management capabilities.

### Core Data Layer

The foundation of Pharos consists of two primary components that handle data ingestion, storage, and intelligent organization:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>📚 Logs</strong></td><td>Foundation of observability: ingestion, storage, processing, and presentation</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs.md">Logs</a></td></tr><tr><td><strong>🎯 Issue Tracker</strong></td><td>Intelligent grouping and de-duplication of logs into manageable issues</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/issue-tracker.md">Issue Tracker</a></td></tr></tbody></table>

### Configuration & Automation

Once data flows through the core layer, Pharos provides powerful automation capabilities to ensure the right people are notified and the right actions are taken:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>📐 Rule-based Configuration</strong></td><td>Flexible rule engine for automation control</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/rule-based-configuration.md">Rule-based Configuration</a></td></tr><tr><td><strong>🔔 Alerting</strong></td><td>Context-aware notifications across multiple channels</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/alerting.md">Alerting</a></td></tr><tr><td><strong>🎫 Ticketing and Bugtracking</strong></td><td>Integration with development workflows</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ticketing-and-bugtracking.md">Ticketing and Bugtracking</a></td></tr></tbody></table>

### Advanced Capabilities

Beyond the core functionality, Pharos offers sophisticated features for deep system insights, AI-powered analysis, and comprehensive debugging:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>📈 Monitoring</strong></td><td>Complex monitoring scenarios including limits and event monitoring</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/monitoring.md">Monitoring</a></td></tr><tr><td><strong>🔬 Tracing</strong></td><td>Debug log capture and transaction tracing</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/tracing.md">Tracing</a></td></tr><tr><td><strong>🔁 Change Tracking</strong></td><td>Historical metadata backup via GitHub</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/change-tracking.md">Change Tracking</a></td></tr><tr><td><strong>🏢 Org Insights</strong></td><td>System overview dashboards for org complexity</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/org-insights.md">Org Insights</a></td></tr><tr><td><strong>🤖 AI Analysis</strong></td><td>AI-powered root cause analysis and remediation suggestions</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/ai-analysis.md">AI Analysis</a></td></tr></tbody></table>

### Openness & Extensibility

Pharos is open by design—signals flow out through open standards, and the platform is operated and extended through the tools you already run:

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🧩 Extensibility &#x26; Integrations</strong></td><td>APIs, platform events, webhooks, integrations, AI-agent operability, and Triton instrumentation</td><td><a href="https://docs.pharos.ai/platform-overview/pharos-platform-architecture/extensibility.md">Extensibility &amp; Integrations</a></td></tr><tr><td><strong>🛰️ Open Telemetry</strong></td><td>Export Salesforce telemetry to any OpenTelemetry-compatible backend</td><td><a href="https://docs.pharos.ai/open-telemetry/open-telemetry.md">Open Telemetry</a></td></tr></tbody></table>

## Architecture Principles

### 1. Native-First

All data stored as Salesforce objects:

* Inherits Salesforce security model
* Queryable via SOQL and APIs
* Reportable with standard Salesforce tools
* Compliant (data never leaves org)

### 2. Bottom-Up Data Flow

Everything starts with logs:

* Logs → Issues → Alerts → Tickets
* Aggregate metrics computed from individual events
* Historical accuracy preserved

### 3. Intelligent Automation

Rules drive behavior throughout the platform:

* Alerting rules
* Ticketing rules
* Retention rules
* Monitoring rules

### 4. Open & Extensible

Built to integrate with your ecosystem, not to lock you in:

* REST APIs for custom integrations
* Platform events for real-time streaming
* Webhooks for outbound notifications
* Standard Salesforce APIs for data access
* OpenTelemetry export to any OTLP backend (Honeycomb, Splunk, Datadog, Grafana)
* Triton instrumentation for custom Apex/LWC/Flow signals

### 5. AI-Native

Intelligence runs through the platform, not beside it:

* Org Genie root-cause analysis and remediation at the issue and org level
* Fingerprinting and impact ranking to separate signal from noise
* Natural-language investigation by AI agents via the MCP server (human-gated actions)

## Architectural Benefits

The layered architecture provides multiple advantages that make Pharos both powerful and maintainable:

| Benefit                     | Description                                                                               | Impact                                                |
| --------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| **Separation of Concerns**  | Each layer has a single responsibility; components don't depend on upstream layers        | Independent evolution and easier troubleshooting      |
| **Progressive Enhancement** | Data becomes more valuable as it moves up the stack from raw logs to integrated workflows | Maximum ROI from observability data                   |
| **Extensibility**           | Multiple integration points for custom ingestion, enrichment, alerting, and reporting     | Adapts to unique org requirements                     |
| **Native Data Model**       | All data stored in Salesforce objects with standard security and compliance               | No external databases, reduced operational complexity |

{% hint style="info" %}
**Bottom-Up Architecture:** Because everything starts with logs, you can always drill down from high-level trends (issues) to specific occurrences (logs) to understand exactly what happened.
{% endhint %}

## Scalability Considerations

The architecture is designed to scale with your Salesforce environment:

| Component          | Technology                                    | Typical Throughput                            |
| ------------------ | --------------------------------------------- | --------------------------------------------- |
| **Log Ingestion**  | Platform events + email processing            | Scales with your org's event and email volume |
| **Log Storage**    | Native custom objects with retention policies | Limited by org storage                        |
| **Issue Grouping** | Asynchronous processing                       | 1,000+ active issues                          |
| **Alerting**       | Async API callouts                            | Limited by org API limits                     |
| **Ticketing Sync** | Scheduled batch jobs                          | Configurable frequency                        |

{% hint style="warning" %}
**High-Volume Orgs:** Use retention policies and log level filtering to manage storage consumption. Most orgs retain logs for 30-90 days depending on compliance requirements.
{% endhint %}

{% hint style="info" %}
Each component is designed to work independently but provides maximum value when used together as an integrated observability platform.
{% endhint %}
