# abdullah-farooqi/palantir architecture

> Architecture diagram of the GitHub repository abdullah-farooqi/palantir, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdullah-farooqi/palantir
- Repository: https://github.com/abdullah-farooqi/palantir

## Overview

PALANTIR monitors Netdata agents through a FastAPI API and scheduled Celery workers. Its main flow registers monitored nodes, collects per-second metrics, stores snapshots, evaluates anomaly scores, and exposes metrics, alerts, and investigations to UI callers; Netdata also pushes alert webhooks. PostgreSQL backs API and worker persistence, with Redis as the Celery broker. The graph preserves the documented retention job and investigation capability. Relationships for unsampled routes and task implementations rely on the README or source-index references; optional agent investigation triggering is not shown because the sampled implementation leaves it commented out.

Main entry points: [`backend/main.py`](https://github.com/abdullah-farooqi/palantir/blob/main/backend/main.py) (FastAPI App), [`backend/services/metrics.py`](https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/metrics.py) (Metric Collection), [`backend/services/anomaly.py`](https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/anomaly.py) (Anomaly Evaluation), [`backend/core/database.py`](https://github.com/abdullah-farooqi/palantir/blob/main/backend/core/database.py) (Database Sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Webhooks"]
  node_api_app["FastAPI App<br/>[main.py]"]
  node_node_api["Node API<br/>[nodes.py]"]
  node_metrics_api["Metrics API<br/>[metrics.py]"]
  node_alerts_api["Alerts API<br/>[alerts.py]"]
  node_investigations_api["Investigations API<br/>[investigations.py]"]
  node_alert_webhook["Alert Webhook<br/>[internal.py]"]
end

subgraph group_collection["Monitoring Collection"]
  node_node_service["Node Registration<br/>[nodes.py]"]
  node_metrics_service["Metric Collection<br/>[metrics.py]"]
end

subgraph group_analysis["Detection and Events"]
  node_anomaly_service["Anomaly Evaluation<br/>[anomaly.py]"]
  node_alert_service["Alert Ingestion<br/>[alerts.py]"]
  node_anomaly_model["Anomaly Events<br/>[anomaly.py]"]
  node_alert_model["Alert Events<br/>[alert.py]"]
  node_investigation_model["Investigations<br/>[investigation.py]"]
end

subgraph group_runtime["Workers and Persistence"]
  node_celery["Celery Schedule<br/>[celery_app.py]"]
  node_metrics_task["Metrics Task<br/>[metrics_tasks.py]"]
  node_anomaly_task["Anomaly Task<br/>[anomaly_tasks.py]"]
  node_maintenance_task["Retention Task"]
  node_db_session["Database Sessions<br/>[database.py]"]
  node_node_model["Monitored Nodes<br/>[node.py]"]
  node_metric_model["Metric Snapshots<br/>[metric.py]"]
  node_settings["Configuration<br/>[config.py]"]
end

subgraph group_integration["Netdata Integration"]
  node_netdata_client["Netdata Client<br/>[client.py]"]
  node_netdata_parsers["Response Parsing<br/>[parsers.py]"]
  node_netdata_contexts["Metric Contexts<br/>[contexts.py]"]
  node_netdata_schemas["Response Schemas<br/>[schemas.py]"]
  node_netdata_errors["Netdata Errors<br/>[exceptions.py]"]
end

node_ui(("UI Caller"))
node_agent["Netdata Agent"]
node_redis["Redis Broker"]
node_postgres[("PostgreSQL")]

node_ui -->|"requests"| node_api_app
node_api_app -->|"routes to"| node_node_api
node_api_app -->|"routes to"| node_metrics_api
node_api_app -->|"routes to"| node_alerts_api
node_api_app -->|"routes to"| node_investigations_api
node_api_app -->|"routes to"| node_alert_webhook
node_node_api -->|"delegates to"| node_node_service
node_node_api -->|"uses session"| node_db_session
node_node_api -->|"handles"| node_netdata_errors
node_metrics_api -->|"uses session"| node_db_session
node_metrics_api -->|"queries"| node_metric_model
node_alerts_api -->|"uses session"| node_db_session
node_alerts_api -->|"queries"| node_alert_model
node_alerts_api -->|"queries"| node_anomaly_model
node_investigations_api -->|"uses session"| node_db_session
node_investigations_api -->|"queries"| node_investigation_model
node_agent -->|"pushes alerts"| node_alert_webhook
node_alert_webhook -->|"delegates to"| node_alert_service
node_alert_service -->|"uses node"| node_node_model
node_alert_service -->|"creates events"| node_alert_model
node_celery -->|"uses broker"| node_redis
node_celery -->|"schedules"| node_metrics_task
node_celery -->|"schedules"| node_anomaly_task
node_celery -->|"schedules"| node_maintenance_task
node_metrics_task -->|"invokes"| node_metrics_service
node_metrics_task -->|"opens session"| node_db_session
node_metrics_task -->|"loads nodes"| node_node_model
node_anomaly_task -->|"invokes"| node_anomaly_service
node_anomaly_task -->|"opens session"| node_db_session
node_anomaly_task -->|"loads nodes"| node_node_model
node_maintenance_task -->|"opens session"| node_db_session
node_maintenance_task -->|"prunes snapshots"| node_metric_model
node_metrics_service -->|"requests metrics"| node_netdata_client
node_metrics_service -->|"parses responses"| node_netdata_parsers
node_metrics_service -->|"selects contexts"| node_netdata_contexts
node_metrics_service -->|"handles failures"| node_netdata_errors
node_metrics_service -->|"writes snapshots"| node_metric_model
node_node_service -->|"probes agent"| node_netdata_client
node_node_service -->|"handles failures"| node_netdata_errors
node_node_service -->|"registers node"| node_node_model
node_anomaly_service -->|"requests scores"| node_netdata_client
node_anomaly_service -->|"parses rates"| node_netdata_parsers
node_anomaly_service -->|"selects contexts"| node_netdata_contexts
node_anomaly_service -->|"handles failures"| node_netdata_errors
node_anomaly_service -->|"records events"| node_anomaly_model
node_netdata_client -->|"queries"| node_agent
node_netdata_client -->|"validates with"| node_netdata_schemas
node_netdata_client -->|"raises"| node_netdata_errors

click node_api_app "https://github.com/abdullah-farooqi/palantir/blob/main/backend/main.py"
click node_node_api "https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/nodes.py"
click node_metrics_api "https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/metrics.py"
click node_alerts_api "https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/alerts.py"
click node_investigations_api "https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/investigations.py"
click node_alert_webhook "https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/internal.py"
click node_node_service "https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/nodes.py"
click node_metrics_service "https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/metrics.py"
click node_netdata_client "https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/client.py"
click node_netdata_parsers "https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/parsers.py"
click node_netdata_contexts "https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/contexts.py"
click node_netdata_schemas "https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/schemas.py"
click node_netdata_errors "https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/exceptions.py"
click node_anomaly_service "https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/anomaly.py"
click node_alert_service "https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/alerts.py"
click node_celery "https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/celery_app.py"
click node_metrics_task "https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/metrics_tasks.py"
click node_anomaly_task "https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/anomaly_tasks.py"
click node_maintenance_task "https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/maintenance_tasks.py"
click node_db_session "https://github.com/abdullah-farooqi/palantir/blob/main/backend/core/database.py"
click node_node_model "https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/node.py"
click node_metric_model "https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/metric.py"
click node_anomaly_model "https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/anomaly.py"
click node_alert_model "https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/alert.py"
click node_investigation_model "https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/investigation.py"
click node_settings "https://github.com/abdullah-farooqi/palantir/blob/main/backend/core/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_app,node_node_api,node_metrics_api,node_alerts_api,node_investigations_api,node_alert_webhook,node_ui toneBlue
class node_node_service,node_metrics_service,node_redis,node_postgres toneAmber
class node_anomaly_service,node_alert_service,node_anomaly_model,node_alert_model,node_investigation_model toneMint
class node_celery,node_metrics_task,node_anomaly_task,node_maintenance_task,node_db_session,node_node_model,node_metric_model,node_settings toneRose
class node_netdata_client,node_netdata_parsers,node_netdata_contexts,node_netdata_schemas,node_netdata_errors,node_agent toneIndigo
```

## Components

### API and Webhooks

- [FastAPI App](https://github.com/abdullah-farooqi/palantir/blob/main/backend/main.py): `backend/main.py`
- [Node API](https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/nodes.py): `backend/api/v1/nodes.py`
- [Metrics API](https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/metrics.py): `backend/api/v1/metrics.py`
- [Alerts API](https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/alerts.py): `backend/api/v1/alerts.py`
- [Investigations API](https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/investigations.py): `backend/api/v1/investigations.py`
- [Alert Webhook](https://github.com/abdullah-farooqi/palantir/blob/main/backend/api/v1/internal.py): `backend/api/v1/internal.py`

### Monitoring Collection

- [Node Registration](https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/nodes.py): `backend/services/nodes.py`
- [Metric Collection](https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/metrics.py): `backend/services/metrics.py`

### Detection and Events

- [Anomaly Evaluation](https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/anomaly.py): `backend/services/anomaly.py`
- [Alert Ingestion](https://github.com/abdullah-farooqi/palantir/blob/main/backend/services/alerts.py): `backend/services/alerts.py`
- [Anomaly Events](https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/anomaly.py): `backend/models/anomaly.py`
- [Alert Events](https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/alert.py): `backend/models/alert.py`
- [Investigations](https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/investigation.py): `backend/models/investigation.py`

### Workers and Persistence

- [Celery Schedule](https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/celery_app.py): `backend/workers/celery_app.py`
- [Metrics Task](https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/metrics_tasks.py): `backend/workers/metrics_tasks.py`
- [Anomaly Task](https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/anomaly_tasks.py): `backend/workers/anomaly_tasks.py`
- [Retention Task](https://github.com/abdullah-farooqi/palantir/blob/main/backend/workers/maintenance_tasks.py): `backend/workers/maintenance_tasks.py`
- [Database Sessions](https://github.com/abdullah-farooqi/palantir/blob/main/backend/core/database.py): `backend/core/database.py`
- [Monitored Nodes](https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/node.py): `backend/models/node.py`
- [Metric Snapshots](https://github.com/abdullah-farooqi/palantir/blob/main/backend/models/metric.py): `backend/models/metric.py`
- [Configuration](https://github.com/abdullah-farooqi/palantir/blob/main/backend/core/config.py): `backend/core/config.py`

### Netdata Integration

- [Netdata Client](https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/client.py): `backend/integrations/netdata/client.py`
- [Response Parsing](https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/parsers.py): `backend/integrations/netdata/parsers.py`
- [Metric Contexts](https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/contexts.py): `backend/integrations/netdata/contexts.py`
- [Response Schemas](https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/schemas.py): `backend/integrations/netdata/schemas.py`
- [Netdata Errors](https://github.com/abdullah-farooqi/palantir/blob/main/backend/integrations/netdata/exceptions.py): `backend/integrations/netdata/exceptions.py`

### Other components

- **UI Caller**
- **Netdata Agent**
- **Redis Broker**
- **PostgreSQL**

## Connections

- UI Caller → FastAPI App: requests (evidence: `README.md`)
- FastAPI App → Node API: routes to (evidence: `backend/main.py`)
- FastAPI App → Metrics API: routes to (evidence: `backend/main.py`)
- FastAPI App → Alerts API: routes to (evidence: `backend/main.py`)
- FastAPI App → Investigations API: routes to (evidence: `backend/main.py`)
- FastAPI App → Alert Webhook: routes to (evidence: `backend/main.py`)
- Node API → Node Registration: delegates to (evidence: `backend/api/v1/nodes.py`)
- Node API → Database Sessions: uses session (evidence: `backend/api/v1/nodes.py`)
- Node API → Netdata Errors: handles (evidence: `backend/api/v1/nodes.py`)
- Metrics API → Database Sessions: uses session (evidence: `backend/api/v1/metrics.py`)
- Metrics API → Metric Snapshots: queries (evidence: `backend/api/v1/metrics.py`)
- Alerts API → Database Sessions: uses session (evidence: `backend/api/v1/alerts.py`)
- Alerts API → Alert Events: queries (evidence: `backend/api/v1/alerts.py`)
- Alerts API → Anomaly Events: queries (evidence: `backend/api/v1/alerts.py`)
- Investigations API → Database Sessions: uses session (evidence: `backend/api/v1/investigations.py`)
- Investigations API → Investigations: queries (evidence: `backend/api/v1/investigations.py`)
- Netdata Agent → Alert Webhook: pushes alerts (evidence: `README.md`)
- Alert Webhook → Alert Ingestion: delegates to (evidence: `backend/api/v1/internal.py`)
- Alert Ingestion → Monitored Nodes: uses node (evidence: `backend/services/alerts.py`)
- Alert Ingestion → Alert Events: creates events (evidence: `backend/services/alerts.py`)
- Celery Schedule → Redis Broker: uses broker (evidence: `README.md`)
- Celery Schedule → Metrics Task: schedules (evidence: `backend/workers/celery_app.py`)
- Celery Schedule → Anomaly Task: schedules (evidence: `backend/workers/celery_app.py`)
- Celery Schedule → Retention Task: schedules (evidence: `backend/workers/celery_app.py`)
- Metrics Task → Metric Collection: invokes (evidence: `backend/workers/metrics_tasks.py`)
- Metrics Task → Database Sessions: opens session (evidence: `backend/workers/metrics_tasks.py`)
- Metrics Task → Monitored Nodes: loads nodes (evidence: `backend/workers/metrics_tasks.py`)
- Anomaly Task → Anomaly Evaluation: invokes (evidence: `backend/workers/anomaly_tasks.py`)
- Anomaly Task → Database Sessions: opens session (evidence: `backend/workers/anomaly_tasks.py`)
- Anomaly Task → Monitored Nodes: loads nodes (evidence: `backend/workers/anomaly_tasks.py`)
- Retention Task → Database Sessions: opens session (evidence: `backend/workers/maintenance_tasks.py`)
- Retention Task → Metric Snapshots: prunes snapshots (evidence: `backend/workers/maintenance_tasks.py`)
- Metric Collection → Netdata Client: requests metrics (evidence: `backend/services/metrics.py`)
- Metric Collection → Response Parsing: parses responses (evidence: `backend/services/metrics.py`)
- Metric Collection → Metric Contexts: selects contexts (evidence: `backend/services/metrics.py`)
- Metric Collection → Netdata Errors: handles failures (evidence: `backend/services/metrics.py`)
- Metric Collection → Metric Snapshots: writes snapshots (evidence: `backend/services/metrics.py`)
- Node Registration → Netdata Client: probes agent (evidence: `backend/services/nodes.py`)
- Node Registration → Netdata Errors: handles failures (evidence: `backend/services/nodes.py`)
- Node Registration → Monitored Nodes: registers node (evidence: `backend/services/nodes.py`)
- Anomaly Evaluation → Netdata Client: requests scores (evidence: `backend/services/anomaly.py`)
- Anomaly Evaluation → Response Parsing: parses rates (evidence: `backend/services/anomaly.py`)
- Anomaly Evaluation → Metric Contexts: selects contexts (evidence: `backend/services/anomaly.py`)
- Anomaly Evaluation → Netdata Errors: handles failures (evidence: `backend/services/anomaly.py`)
- Anomaly Evaluation → Anomaly Events: records events (evidence: `backend/services/anomaly.py`)
- Netdata Client → Netdata Agent: queries (evidence: `backend/integrations/netdata/client.py`)
- Netdata Client → Response Schemas: validates with (evidence: `backend/integrations/netdata/client.py`)
- Netdata Client → Netdata Errors: raises (evidence: `backend/integrations/netdata/client.py`)
