# prxcode/cross-layer-behavioral-detection architecture

> Architecture diagram of the GitHub repository prxcode/cross-layer-behavioral-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prxcode/cross-layer-behavioral-detection
- Repository: https://github.com/prxcode/cross-layer-behavioral-detection

## Overview

This research system simulates compromised service-account behavior, correlates API and database audit events by trace ID, and compares four anomaly-detection configurations. The principal path is workload/client traffic through gateway and domain services into PostgreSQL, then telemetry collection, correlation, feature building, Isolation Forest scoring, and dashboard presentation. The README documents gateway, database, and deployment components whose source paths are absent from the supplied tree; they are represented only where that documented flow is meaningful. Relationships among unsampled components are omitted unless documented.

Main entry points: [`detector/src/main.py`](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/main.py) (Training and scoring API), [`detector/src/models.py`](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/models.py) (Four Isolation Forests), [`telemetry/src/main.py`](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/main.py) (Telemetry API and stream), [`detector/src/experiments/run_matrix.py`](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/experiments/run_matrix.py) (Experiment matrix)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_traffic["Traffic simulation"]
  node_workload["Workload generator<br/>[generator.py]"]
  node_attack_scenarios["Attack scenarios"]
  node_gateway["Trace-ID gateway"]
end

subgraph group_services["Commerce services"]
  node_user_service["User service<br/>[routes.py]"]
  node_order_service["Order and payment service<br/>[routes.py]"]
  node_admin_service["Admin service<br/>[routes.py]"]
  node_postgres[("PostgreSQL and pgaudit")]
end

subgraph group_telemetry["Telemetry pipeline"]
  node_api_logs["Nginx access logs"]
  node_audit_logs["pgaudit logs"]
  node_collectors["Log collectors<br/>[collector.py]"]
  node_correlation["Trace correlation engine<br/>[correlation.py]"]
  node_record_storage[("Correlation storage<br/>[storage.py]")]
  node_telemetry_api["Telemetry API and stream<br/>[main.py]"]
end

subgraph group_detection["Detection research"]
  node_feature_builder["Feature builder<br/>[features.py]"]
  node_detectors["Four Isolation Forests<br/>[models.py]"]
  node_detector_api["Training and scoring API<br/>[main.py]"]
  node_thresholds["Threshold calibration<br/>[threshold.py]"]
  node_matrix["Experiment matrix<br/>[run_matrix.py]"]
end

subgraph group_presentation["Results and analysis"]
  node_dashboard["SOC dashboard<br/>[main.py]"]
  node_evaluation["Reports and statistics"]
end

node_client(("Client"))

node_client -->|"sends requests"| node_gateway
node_workload -->|"generates traffic"| node_gateway
node_attack_scenarios -->|"simulates attacks"| node_gateway
node_gateway -->|"routes requests"| node_user_service
node_gateway -->|"routes requests"| node_order_service
node_gateway -->|"routes requests"| node_admin_service
node_gateway -->|"writes access logs"| node_api_logs
node_user_service -->|"queries with trace ID"| node_postgres
node_order_service -->|"queries with trace ID"| node_postgres
node_admin_service -.->|"executes SQL"| node_postgres
node_postgres -->|"emits SQL audit"| node_audit_logs
node_api_logs -->|"tails logs"| node_collectors
node_audit_logs -->|"tails logs"| node_collectors
node_collectors -->|"ingests events"| node_correlation
node_correlation -->|"stores records"| node_record_storage
node_record_storage -->|"serves records"| node_telemetry_api
node_telemetry_api -->|"provides training data"| node_detector_api
node_detector_api -->|"builds vectors"| node_feature_builder
node_feature_builder -->|"supplies features"| node_detectors
node_detector_api -->|"trains and scores"| node_detectors
node_thresholds -->|"calibrates thresholds"| node_detectors
node_detector_api -->|"starts experiments"| node_matrix
node_matrix -->|"loads model registry"| node_detectors
node_telemetry_api -.->|"streams results"| node_dashboard
node_detector_api -.->|"provides detections"| node_dashboard
node_matrix -.->|"produces experiment results"| node_evaluation

click node_workload "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/workload/src/generator.py"
click node_attack_scenarios "https://github.com/prxcode/cross-layer-behavioral-detection/tree/main/workload/src/attacks"
click node_user_service "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/services/user_service/src/routes.py"
click node_order_service "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/services/order_service/src/routes.py"
click node_admin_service "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/services/admin_service/src/routes.py"
click node_collectors "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/collector.py"
click node_correlation "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/correlation.py"
click node_record_storage "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/storage.py"
click node_telemetry_api "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/main.py"
click node_feature_builder "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/features.py"
click node_detectors "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/models.py"
click node_detector_api "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/main.py"
click node_thresholds "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/threshold.py"
click node_matrix "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/experiments/run_matrix.py"
click node_dashboard "https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/dashboard/main.py"
click node_evaluation "https://github.com/prxcode/cross-layer-behavioral-detection/tree/main/evaluation/src"

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_workload,node_attack_scenarios,node_gateway,node_client toneBlue
class node_user_service,node_order_service,node_admin_service,node_postgres toneAmber
class node_api_logs,node_audit_logs,node_collectors,node_correlation,node_record_storage,node_telemetry_api toneMint
class node_feature_builder,node_detectors,node_detector_api,node_thresholds,node_matrix toneRose
class node_dashboard,node_evaluation toneIndigo
```

## Components

### Traffic simulation

- [Workload generator](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/workload/src/generator.py): `workload/src/generator.py`
- [Attack scenarios](https://github.com/prxcode/cross-layer-behavioral-detection/tree/main/workload/src/attacks): `workload/src/attacks`
- **Trace-ID gateway**

### Commerce services

- [User service](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/services/user_service/src/routes.py): `services/user_service/src/routes.py`
- [Order and payment service](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/services/order_service/src/routes.py): `services/order_service/src/routes.py`
- [Admin service](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/services/admin_service/src/routes.py): `services/admin_service/src/routes.py`
- **PostgreSQL and pgaudit**

### Telemetry pipeline

- **Nginx access logs**
- **pgaudit logs**
- [Log collectors](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/collector.py): `telemetry/src/collector.py`
- [Trace correlation engine](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/correlation.py): `telemetry/src/correlation.py`
- [Correlation storage](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/storage.py): `telemetry/src/storage.py`
- [Telemetry API and stream](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/telemetry/src/main.py): `telemetry/src/main.py`

### Detection research

- [Feature builder](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/features.py): `detector/src/features.py`
- [Four Isolation Forests](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/models.py): `detector/src/models.py`
- [Training and scoring API](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/main.py): `detector/src/main.py`
- [Threshold calibration](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/threshold.py): `detector/src/threshold.py`
- [Experiment matrix](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/detector/src/experiments/run_matrix.py): `detector/src/experiments/run_matrix.py`

### Results and analysis

- [SOC dashboard](https://github.com/prxcode/cross-layer-behavioral-detection/blob/main/dashboard/main.py): `dashboard/main.py`
- [Reports and statistics](https://github.com/prxcode/cross-layer-behavioral-detection/tree/main/evaluation/src): `evaluation/src`

### Other components

- **Client**

## Connections

- Client → Trace-ID gateway: sends requests (evidence: `README.md`)
- Workload generator → Trace-ID gateway: generates traffic (evidence: `README.md`)
- Attack scenarios → Trace-ID gateway: simulates attacks (evidence: `README.md`)
- Trace-ID gateway → User service: routes requests (evidence: `README.md`)
- Trace-ID gateway → Order and payment service: routes requests (evidence: `README.md`)
- Trace-ID gateway → Admin service: routes requests (evidence: `README.md`)
- Trace-ID gateway → Nginx access logs: writes access logs (evidence: `README.md`)
- User service → PostgreSQL and pgaudit: queries with trace ID
- Order and payment service → PostgreSQL and pgaudit: queries with trace ID
- Admin service → PostgreSQL and pgaudit: executes SQL (evidence: `README.md`)
- PostgreSQL and pgaudit → pgaudit logs: emits SQL audit (evidence: `README.md`)
- Nginx access logs → Log collectors: tails logs
- pgaudit logs → Log collectors: tails logs
- Log collectors → Trace correlation engine: ingests events (evidence: `telemetry/src/main.py`)
- Trace correlation engine → Correlation storage: stores records (evidence: `telemetry/src/main.py`)
- Correlation storage → Telemetry API and stream: serves records (evidence: `telemetry/src/main.py`)
- Telemetry API and stream → Training and scoring API: provides training data (evidence: `detector/src/main.py`)
- Training and scoring API → Feature builder: builds vectors (evidence: `detector/src/main.py`)
- Feature builder → Four Isolation Forests: supplies features (evidence: `detector/src/main.py`)
- Training and scoring API → Four Isolation Forests: trains and scores (evidence: `detector/src/main.py`)
- Threshold calibration → Four Isolation Forests: calibrates thresholds (evidence: `detector/src/threshold.py`)
- Training and scoring API → Experiment matrix: starts experiments (evidence: `detector/src/main.py`)
- Experiment matrix → Four Isolation Forests: loads model registry (evidence: `detector/src/experiments/run_matrix.py`)
- Telemetry API and stream → SOC dashboard: streams results (evidence: `README.md`)
- Training and scoring API → SOC dashboard: provides detections (evidence: `README.md`)
- Experiment matrix → Reports and statistics: produces experiment results (evidence: `README.md`)
